Object Interest

WpObjectInterest

wp_object_interest_new

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
  • 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);

wp_object_interest_new_type

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.

wp_object_interest_new_valist

WpObjectInterest *
wp_object_interest_new_valist (GType gtype,
                               va_list* args)

va_list version of wp_object_interest_new

wp_object_interest_add_constraint

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.

wp_object_interest_copy

WpObjectInterest *
wp_object_interest_copy (WpObjectInterest * self)

wp_object_interest_free

wp_object_interest_free (WpObjectInterest * self)

Releases self and all the memory associated with it

wp_object_interest_matches

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

Equivalent to wp_object_interest_matches_full (self, G_OBJECT_TYPE (object), object, NULL, NULL)

wp_object_interest_matches_full

gboolean
wp_object_interest_matches_full (WpObjectInterest * self,
                                 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_proxy_get_properties and wp_proxy_get_global_properties respectively.

wp_object_interest_validate

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.

WpConstraintType

WpConstraintVerb

WP_TYPE_OBJECT_INTEREST

#define WP_TYPE_OBJECT_INTEREST (wp_object_interest_get_type ())

The WpObjectInterest GType