Wp.ObjectInterest

Fields

None

Methods

class

new_type (gtype)

add_constraint (type, subject, verb, value)

matches (object)

matches_full (flags, object_type, object, pw_props, pw_global_props)

ref ()

unref ()

validate ()

Details

class Wp.ObjectInterest

An object interest is a helper that is used in Wp.ObjectManager to declare interest in certain kinds of objects. An interest is defined by a GObject.GType and a set of constraints on the object’s properties. An object “matches” the interest if it is of the specified GObject.GType (either the same type or a descendant of it) and all the constraints are satisfied.

classmethod new_type(gtype)
Parameters:

gtype (GObject.GType) – the type of the object to declare interest in

Returns:

the new object interest

Return type:

Wp.ObjectInterest

Creates a new interest that declares interest in objects of the specified gtype, without any property constraints.

To add property constraints, you can call Wp.ObjectInterest.add_constraint() afterwards.

add_constraint(type, subject, verb, value)
Parameters:

Adds a constraint to this interest. Constraints consist of a type, a subject, a verb and, depending on the verb, a value.

Constraints are almost like a spoken language sentence that declare a condition that must be true in order to consider that an object can match this interest. For instance, a constraint can be “pipewire property ‘object.id’ equals 10”. This would be translated to:

wp_object_interest_add_constraint (i,
WP_CONSTRAINT_TYPE_PW_PROPERTY, "object.id",
WP_CONSTRAINT_VERB_EQUALS, g_variant_new_int (10));

Some verbs require a value and some others do not. For those that do, the value must be of a specific type:

  • Wp.ConstraintVerb.EQUALS: value can be a string, a (u)int32, a (u)int64, a double or a boolean. The subject value must equal this value for the constraint to be satisfied

  • Wp.ConstraintVerb.IN_LIST: value must be a tuple that contains any number of items of the same type; the items can be string, (u)int32, (u)int64 or double. These items make a list that the subject's value will be checked against. If any of the items equals the subject value, the constraint is satisfied

  • Wp.ConstraintVerb.IN_RANGE: value must be a tuple that contains exactly 2 numbers of the same type ((u)int32, (u)int64 or double), meaning the minimum and maximum (inclusive) of the range. If the subject value is a number within this range, the constraint is satisfied

  • Wp.ConstraintVerb.MATCHES: value must be a string that defines a pattern usable with GLib.PatternSpec If the subject value matches this pattern, the constraint is satisfied

In case the type of the subject value is not the same type as the one requested by the type of the value, the subject value is converted. For GObject.Object properties, this conversion is done using GObject.Value.transform(), so limitations of this function apply. In the case of PipeWire properties, which are always strings, conversion is done as follows:

  • to boolean: “true” or “1” means True, “false” or “0” means False

  • to int / uint / int64 / uint64: One of the strtol() family of functions is used to convert, using base 10

  • to double: strtod() is used

This method does not fail if invalid arguments are given. However, Wp.ObjectInterest.validate() should be called after adding all the constraints on an interest in order to catch errors.

matches(object)
Parameters:

object (object or None) – the target object to check for a match

Returns:

True if the object matches, False otherwise

Return type:

bool

Checks if the specified object matches the type and all the constraints that are described in self.

If self is configured to match GObject.Object subclasses, this is equivalent to Wp.ObjectInterest.matches_full (self, G_OBJECT_TYPE (object), object, None, None) and if it is configured to match Wp.Properties, this is equivalent to Wp.ObjectInterest.matches_full (self, self->gtype, None, (Wp.Properties *) object, None);

matches_full(flags, object_type, object, pw_props, pw_global_props)
Parameters:
Returns:

flags that indicate which components of the interest match. Wp.InterestMatch.ALL indicates a fully successful match; any other combination indicates a failure on the component(s) that do not appear on the flag set

Return type:

Wp.InterestMatch

A low-level version of Wp.ObjectInterest.matches().

In this version, the object’s type is directly given in object_type and is not inferred from the object. object is only used to check for constraints against GObject.Object properties. pw_props and pw_global_props are used to check constraints against PipeWire object properties and global properties, respectively. object, pw_props and pw_global_props may be None, but in case there are any constraints that require them, the match will fail. As a special case, if object is not None and is a subclass of Wp.Proxy, then pw_props and pw_global_props, if required, will be internally retrieved from object by calling Wp.PipewireObject.get_properties() and Wp.GlobalProxy.get_global_properties() respectively. When flags contains Wp.InterestMatchFlags.CHECK_ALL, all the constraints are checked and the returned value contains accurate information about which types of constraints have failed to match, if any. When this flag is not present, this function returns after the first failure has been encountered. This means that the returned flags set will contain all but one flag, which will indicate the kind of constraint that failed (more could have failed, but they are not checked…)

ref()
Returns:

self with an additional reference count on it

Return type:

Wp.ObjectInterest

Increases the reference count of an object interest.

unref()

Decreases the reference count on self and frees it when the ref count reaches zero.

validate()
Raises:

GLib.Error

Returns:

True if the interest is valid and can be used in a match, False otherwise

Return type:

bool

Validates the interest, ensuring that the interest GObject.GType is a valid object and that all the constraints have been expressed properly.

This is called internally when self is first used to find a match, so it is not necessary to call it explicitly