Object Interest

digraph inheritance { rankdir=LR; GBoxed -> WpObjectInterest; }

struct WpObjectInterest

An object interest is a helper that is used in WpObjectManager to declare interest in certain kinds of objects.

An interest is defined by a GType and a set of constraints on the object’s properties. An object “matches” the interest if it is of the specified GType (either the same type or a descendant of it) and all the constraints are satisfied.

enum WpConstraintType

Constraint types for wp_object_interest_add_constraint()

Values:

enumerator WP_CONSTRAINT_TYPE_NONE = 0

invalid constraint type

enumerator WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY

constraint applies to a PipeWire global property of the object (the ones returned by wp_global_proxy_get_global_properties())

enumerator WP_CONSTRAINT_TYPE_PW_PROPERTY

constraint applies to a PipeWire property of the object (the ones returned by wp_pipewire_object_get_properties())

enumerator WP_CONSTRAINT_TYPE_G_PROPERTY

constraint applies to a GObject property of the object

enum WpConstraintVerb

Verbs to use with wp_object_interest_add_constraint()

Values:

enumerator WP_CONSTRAINT_VERB_EQUALS = '='

the subject’s value must equal the constraint’s value

enumerator WP_CONSTRAINT_VERB_NOT_EQUALS = '!'

the subject’s value must be different from the constraint’s value

enumerator WP_CONSTRAINT_VERB_IN_LIST = 'c'

the subject’s value must equal at least one of the values in the list given as the constraint’s value

enumerator WP_CONSTRAINT_VERB_IN_RANGE = '~'

the subject’s value must be a number in the range defined by the constraint’s value

enumerator WP_CONSTRAINT_VERB_MATCHES = '#'

the subject’s value must match the pattern specified in the constraint’s value

enumerator WP_CONSTRAINT_VERB_IS_PRESENT = '+'

the subject property must exist

enumerator WP_CONSTRAINT_VERB_IS_ABSENT = '-'

the subject property must not exist

enum WpInterestMatch

Flags that indicate which constraints have been matched in wp_object_interest_matches_full()

Values:

enumerator WP_INTEREST_MATCH_NONE = 0
enumerator WP_INTEREST_MATCH_GTYPE = (1 << 0)
enumerator WP_INTEREST_MATCH_PW_GLOBAL_PROPERTIES = (1 << 1)
enumerator WP_INTEREST_MATCH_PW_PROPERTIES = (1 << 2)
enumerator WP_INTEREST_MATCH_G_PROPERTIES = (1 << 3)
enum WpInterestMatchFlags

Flags to alter the behaviour of wp_object_interest_matches_full()

Values:

enumerator WP_INTEREST_MATCH_FLAGS_NONE = 0
enumerator WP_INTEREST_MATCH_FLAGS_CHECK_ALL = (1 << 0)

check all the constraints instead of returning after the first mis-match

WpObjectInterest *wp_object_interest_new(GType gtype, ...)

Creates a new interest that declares interest in objects of the specified gtype, with the constraints specified in the variable arguments.

The variable arguments should be a list of constraints terminated with NULL, where each constraint consists of the following arguments:

  • a WpConstraintType: the constraint type

  • a const gchar *: the subject name

  • a const gchar *: the format string

  • 0 or more arguments according to the format string

The format string is interpreted as follows:

  • the first character is the constraint verb:

    • =: WP_CONSTRAINT_VERB_EQUALS

    • !: WP_CONSTRAINT_VERB_NOT_EQUALS

    • c: WP_CONSTRAINT_VERB_IN_LIST

    • ~: WP_CONSTRAINT_VERB_IN_RANGE

    • #: WP_CONSTRAINT_VERB_MATCHES

    • +: WP_CONSTRAINT_VERB_IS_PRESENT

    • -: WP_CONSTRAINT_VERB_IS_ABSENT

  • the rest of the characters are interpreted as a GVariant format string, as it would be used in g_variant_new()

The rest of this function’s arguments up to the start of the next constraint depend on the GVariant format part of the format string and are used to construct a GVariant for the constraint’s value argument.

For further reading on the constraint’s arguments, see wp_object_interest_add_constraint()

For example, this interest matches objects that are descendands of WpProxy with a “bound-id” between 0 and 100 (inclusive), with a pipewire property called “format.dsp” that contains the string “audio” somewhere in the value and with a pipewire property “port.name” being present (with any value): 

interest = wp_object_interest_new (WP_TYPE_PROXY,
    WP_CONSTRAINT_TYPE_G_PROPERTY, "bound-id", "~(uu)", 0, 100,
    WP_CONSTRAINT_TYPE_PW_PROPERTY, "format.dsp", "#s", "*audio*",
    WP_CONSTRAINT_TYPE_PW_PROPERTY, "port.name", "+",
    NULL);

Parameters:

  • gtype – the type of the object to declare interest in

  • ... – a set of constraints, terminated with NULL

Returns:

(transfer full): the new object interest

WpObjectInterest *wp_object_interest_new_valist(GType gtype, va_list *args)

va_list version of wp_object_interest_new()

Parameters:

  • gtype – the type of the object to declare interest in

  • args – pointer to va_list containing the constraints

Returns:

(transfer full): the new object interest

WpObjectInterest *wp_object_interest_new_type(GType gtype)

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_object_interest_add_constraint() afterwards.

Parameters:

  • gtype – the type of the object to declare interest in

Returns:

(transfer full): the new object interest

void wp_object_interest_add_constraint(WpObjectInterest *self, WpConstraintType type, const gchar *subject, WpConstraintVerb verb, GVariant *value)

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_CONSTRAINT_VERB_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_CONSTRAINT_VERB_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_CONSTRAINT_VERB_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_CONSTRAINT_VERB_MATCHES: value must be a string that defines a pattern usable with GPatternSpec 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 properties, this conversion is done using g_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_object_interest_validate() should be called after adding all the constraints on an interest in order to catch errors.

Parameters:

  • self – the object interest

  • type – the constraint type

  • subject – the subject that the constraint applies to

  • verb – the operation that is performed to check the constraint

  • value – (transfer floating)(nullable): the value to check for

WpObjectInterest *wp_object_interest_ref(WpObjectInterest *self)

Increases the reference count of an object interest.

Parameters:

  • self – the object interest to ref

Returns:

(transfer full): self with an additional reference count on it

void wp_object_interest_unref(WpObjectInterest *self)

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

Parameters:

  • self – (transfer full): the object interest to unref

gboolean wp_object_interest_validate(WpObjectInterest *self, GError **error)

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

Remark

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

Parameters:

  • self – the object interest to validate

  • error – (out) (optional): the error, in case validation failed

Returns:

TRUE if the interest is valid and can be used in a match, FALSE otherwise

gboolean wp_object_interest_matches(WpObjectInterest *self, gpointer object)

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

If self is configured to match GObject subclasses, this is equivalent to wp_object_interest_matches_full (self, G_OBJECT_TYPE (object), object, NULL, NULL) and if it is configured to match WpProperties, this is equivalent to wp_object_interest_matches_full (self, self->gtype, NULL, (WpProperties *) object, NULL);

Parameters:

  • self – the object interest

  • object – the target object to check for a match

Returns:

TRUE if the object matches, FALSE otherwise

WpInterestMatch wp_object_interest_matches_full(WpObjectInterest *self, WpInterestMatchFlags flags, GType object_type, gpointer object, WpProperties *pw_props, WpProperties *pw_global_props)

A low-level version of wp_object_interest_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 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 NULL, but in case there are any constraints that require them, the match will fail. As a special case, if object is not NULL and is a subclass of WpProxy, then pw_props and pw_global_props, if required, will be internally retrieved from object by calling wp_pipewire_object_get_properties() and wp_global_proxy_get_global_properties() respectively.

When flags contains WP_INTEREST_MATCH_FLAGS_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…)

Parameters:

  • self – the object interest

  • flags – flags to alter the behavior of this function

  • object_type – the type to be checked against the interest’s type

  • object – (type GObject)(transfer none)(nullable): the object to be used for checking constraints of type WP_CONSTRAINT_TYPE_G_PROPERTY

  • pw_props – (transfer none)(nullable): the properties to be used for checking constraints of type WP_CONSTRAINT_TYPE_PW_PROPERTY

  • pw_global_props – (transfer none)(nullable): the properties to be used for checking constraints of type WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY

Returns:

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

WP_INTEREST_MATCH_ALL

(WP_INTEREST_MATCH_GTYPE | \

WP_INTEREST_MATCH_PW_GLOBAL_PROPERTIES | \

WP_INTEREST_MATCH_PW_PROPERTIES | \

WP_INTEREST_MATCH_G_PROPERTIES)


Special WpInterestMatch value that indicates that all constraints have been matched.

WP_TYPE_OBJECT_INTEREST (wp_object_interest_get_type ())

The WpObjectInterest GType.