| Copyright | Will Thompson and Iñaki García Etxebarria |
|---|---|
| License | LGPL-2.1 |
| Maintainer | Iñaki García Etxebarria |
| Safe Haskell | None |
| Language | Haskell2010 |
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
- newtype ObjectInterest = ObjectInterest (ManagedPtr ObjectInterest)
- objectInterestAddConstraint :: (HasCallStack, MonadIO m) => ObjectInterest -> ConstraintType -> Text -> ConstraintVerb -> Maybe GVariant -> m ()
- objectInterestFindDefinedConstraintValues :: (HasCallStack, MonadIO m) => ObjectInterest -> ConstraintType -> Text -> m (Maybe [GVariant])
- objectInterestMatches :: (HasCallStack, MonadIO m) => ObjectInterest -> Ptr () -> m Bool
- objectInterestMatchesFull :: (HasCallStack, MonadIO m, IsObject a) => ObjectInterest -> [InterestMatchFlags] -> GType -> Maybe a -> Maybe Properties -> Maybe Properties -> m [InterestMatch]
- objectInterestNewType :: (HasCallStack, MonadIO m) => GType -> m ObjectInterest
- objectInterestRef :: (HasCallStack, MonadIO m) => ObjectInterest -> m ObjectInterest
- objectInterestUnref :: (HasCallStack, MonadIO m) => ObjectInterest -> m ()
- objectInterestValidate :: (HasCallStack, MonadIO m) => ObjectInterest -> m ()
Exported types
newtype ObjectInterest Source #
Memory-managed wrapper type.
Constructors
| ObjectInterest (ManagedPtr ObjectInterest) |
Instances
| Eq ObjectInterest Source # | |
Defined in GI.Wp.Structs.ObjectInterest Methods (==) :: ObjectInterest -> ObjectInterest -> Bool # (/=) :: ObjectInterest -> ObjectInterest -> Bool # | |
| GBoxed ObjectInterest Source # | |
Defined in GI.Wp.Structs.ObjectInterest | |
| ManagedPtrNewtype ObjectInterest Source # | |
Defined in GI.Wp.Structs.ObjectInterest Methods toManagedPtr :: ObjectInterest -> ManagedPtr ObjectInterest # | |
| TypedObject ObjectInterest Source # | |
Defined in GI.Wp.Structs.ObjectInterest | |
| HasParentTypes ObjectInterest Source # | |
Defined in GI.Wp.Structs.ObjectInterest | |
| IsGValue (Maybe ObjectInterest) Source # | Convert |
Defined in GI.Wp.Structs.ObjectInterest Methods gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe ObjectInterest -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe ObjectInterest) # | |
| type ParentTypes ObjectInterest Source # | |
Defined in GI.Wp.Structs.ObjectInterest | |
Methods
Click to display all available methods, including inherited ones
Methods
addConstraint, findDefinedConstraintValues, matches, matchesFull, ref, unref, validate.
Getters
None.
Setters
None.
addConstraint
objectInterestAddConstraint Source #
Arguments
| :: (HasCallStack, MonadIO m) | |
| => ObjectInterest |
|
| -> ConstraintType |
|
| -> Text |
|
| -> ConstraintVerb |
|
| -> Maybe GVariant |
|
| -> 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 |
|
| -> ConstraintType |
|
| -> Text |
|
| -> 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 |
|
| -> Ptr () |
|
| -> 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 |
|
| -> [InterestMatchFlags] |
|
| -> GType |
|
| -> Maybe a |
|
| -> Maybe Properties |
|
| -> Maybe Properties |
|
| -> 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 |
|
| -> 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
Arguments
| :: (HasCallStack, MonadIO m) | |
| => ObjectInterest |
|
| -> m ObjectInterest | Returns: |
Increases the reference count of an object interest.
unref
Arguments
| :: (HasCallStack, MonadIO m) | |
| => ObjectInterest |
|
| -> m () |
Decreases the reference count on self and frees it when the ref count reaches zero.
validate
objectInterestValidate Source #
Arguments
| :: (HasCallStack, MonadIO m) | |
| => ObjectInterest |
|
| -> m () | (Can throw |
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