Visitar URL original
GI.Wp.Structs.ObjectInterest
gi-wireplumber-0.5.14.2: WirePlumber bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellNone
LanguageHaskell2010

GI.Wp.Structs.ObjectInterest

Description

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.

Synopsis

Exported types

Methods

Click to display all available methods, including inherited ones

Expand

Methods

addConstraint, findDefinedConstraintValues, matches, matchesFull, ref, unref, validate.

Getters

None.

Setters

None.

addConstraint

objectInterestAddConstraint Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> ObjectInterest

self: the object interest

-> ConstraintType

type: the constraint type

-> Text

subject: the subject that the constraint applies to

-> ConstraintVerb

verb: the operation that is performed to check the constraint

-> Maybe GVariant

value: the value to check for

-> m () 

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:

C code

 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 valueTransform, 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, objectInterestValidate should be called after adding all the constraints on an interest in order to catch errors.

findDefinedConstraintValues

objectInterestFindDefinedConstraintValues Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> ObjectInterest

self: the object interest

-> ConstraintType

type: the constraint type

-> Text

subject: the subject that the constraint applies to

-> m (Maybe [GVariant])

Returns: the defined constraint values for this object interest.

Finds all the defined constraint values for a subject in self.

A defined constraint value is the value of a constraint with the 'equal' or 'in-list' verb, because the full value must be defined with those verbs. This can be useful for cases where we want to enumerate interests that are interested in specific subjects.

Since: 0.5.13

matches

objectInterestMatches Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> ObjectInterest

self: the object interest

-> Ptr ()

object: the target object to check for a match

-> m Bool

Returns: TRUE if the object matches, FALSE otherwise

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

matchesFull

objectInterestMatchesFull Source #

Arguments

:: (HasCallStack, MonadIO m, IsObject a) 
=> ObjectInterest

self: the object interest

-> [InterestMatchFlags]

flags: flags to alter the behavior of this function

-> GType

objectType: the type to be checked against the interest's type

-> Maybe a

object: the object to be used for checking constraints of type WP_CONSTRAINT_TYPE_G_PROPERTY

-> Maybe Properties

pwProps: the properties to be used for checking constraints of type WP_CONSTRAINT_TYPE_PW_PROPERTY

-> Maybe Properties

pwGlobalProps: the properties to be used for checking constraints of type WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY

-> m [InterestMatch]

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

A low-level version of objectInterestMatches.

In this version, the object's type is directly given in objectType and is not inferred from the object. object is only used to check for constraints against GObject properties. pwProps and pwGlobalProps are used to check constraints against PipeWire object properties and global properties, respectively. object, pwProps and pwGlobalProps 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 pwProps and pwGlobalProps, if required, will be internally retrieved from object by calling pipewireObjectGetProperties and globalProxyGetGlobalProperties 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...)

newType

objectInterestNewType Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> GType

gtype: the type of the object to declare interest in

-> m ObjectInterest

Returns: the new object interest

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

To add property constraints, you can call objectInterestAddConstraint afterwards.

ref

objectInterestRef Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> ObjectInterest

self: the object interest to ref

-> m ObjectInterest

Returns: self with an additional reference count on it

Increases the reference count of an object interest.

unref

objectInterestUnref Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> ObjectInterest

self: the object interest to unref

-> m () 

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

validate

objectInterestValidate Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> ObjectInterest

self: the object interest to validate

-> m ()

(Can throw GError)

Validates the interest, ensuring that the interest 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