docs: api: Replace hotdoc specific commands with Doxygen specific commands
This commit is contained in:
Raghavendra
committed by
George Kiagiadakis
George Kiagiadakis
parent
89549247f8
commit
d692f06f0d
@@ -6,11 +6,9 @@
|
||||
* SPDX-License-Identifier: MIT
|
||||
*/
|
||||
|
||||
/**
|
||||
* SECTION: object-interest
|
||||
* @title: Object Interest
|
||||
/*!
|
||||
* @file object-interest.c
|
||||
*/
|
||||
|
||||
#define G_LOG_DOMAIN "wp-object-interest"
|
||||
|
||||
#include "object-interest.h"
|
||||
@@ -31,6 +29,30 @@ struct constraint
|
||||
GVariant *value;
|
||||
};
|
||||
|
||||
/*!
|
||||
* @struct WpObjectInterest
|
||||
*
|
||||
* @section object_interest_section Object Interest
|
||||
*
|
||||
* @brief An object interest is a helper that is used in
|
||||
* [WpObjectManager](@ref object_manager_section) to
|
||||
* declare interest in certain kinds of objects.
|
||||
*
|
||||
* An interest is defined by a
|
||||
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
|
||||
* GType</a> and a set of constraints on the object's
|
||||
* properties. An object "matches" the interest if it is of the specified
|
||||
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
|
||||
* GType</a> (either the same type or a descendant of it) and all the constraints
|
||||
* are satisfied.
|
||||
*/
|
||||
/*!
|
||||
* @brief
|
||||
* @em ref
|
||||
* @em valid
|
||||
* @em gtype
|
||||
* @em constraints
|
||||
*/
|
||||
struct _WpObjectInterest
|
||||
{
|
||||
grefcount ref;
|
||||
@@ -39,30 +61,19 @@ struct _WpObjectInterest
|
||||
struct pw_array constraints;
|
||||
};
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
G_DEFINE_BOXED_TYPE (WpObjectInterest, wp_object_interest,
|
||||
wp_object_interest_copy, wp_object_interest_unref)
|
||||
|
||||
/**
|
||||
* wp_object_interest_new:
|
||||
* @gtype: the type of the object to declare interest in
|
||||
* @...: a set of constraints, terminated with %NULL
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param gtype: the type of the object to declare interest in, ... a set of constraints, terminated with %NULL
|
||||
*
|
||||
* Creates a new interest that declares interest in objects of the specified
|
||||
* @gtype, with the constraints specified in the variable arguments.
|
||||
* @brief Creates a new interest that declares interest in objects of the specified
|
||||
* @em 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 [WpConstraintType](@ref constraint_type_section): the constraint type
|
||||
* - a `const gchar *`: the subject name
|
||||
* - a `const gchar *`: the format string
|
||||
* - 0 or more arguments according to the format string
|
||||
@@ -76,17 +87,23 @@ G_DEFINE_BOXED_TYPE (WpObjectInterest, wp_object_interest,
|
||||
* - `#`: %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,
|
||||
* - the rest of the characters are interpreted as a
|
||||
* <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
|
||||
* GVariant</a> 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.
|
||||
* depend on the
|
||||
* <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
|
||||
* GVariant</a> format part of the format string and are used to
|
||||
* construct a
|
||||
* <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
|
||||
* GVariant</a> 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
|
||||
* For example, this interest matches objects that are descendands of [WpProxy](@ref proxy_section)
|
||||
* 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):
|
||||
@@ -98,8 +115,9 @@ G_DEFINE_BOXED_TYPE (WpObjectInterest, wp_object_interest,
|
||||
* NULL);
|
||||
* ]|
|
||||
*
|
||||
* Returns: (transfer full): the new object interest
|
||||
* @returns (transfer full): the new object interest
|
||||
*/
|
||||
|
||||
WpObjectInterest *
|
||||
wp_object_interest_new (GType gtype, ...)
|
||||
{
|
||||
@@ -111,15 +129,16 @@ wp_object_interest_new (GType gtype, ...)
|
||||
return self;
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_new_valist:
|
||||
* @gtype: the type of the object to declare interest in
|
||||
* @args: pointer to va_list containing the constraints
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param gtype: the type of the object to declare interest in
|
||||
* @param args: pointer to va_list containing the constraints
|
||||
*
|
||||
* va_list version of wp_object_interest_new()
|
||||
* @brief va_list version of wp_object_interest_new()
|
||||
*
|
||||
* Returns: (transfer full): the new object interest
|
||||
* @returns (transfer full): the new object interest
|
||||
*/
|
||||
|
||||
WpObjectInterest *
|
||||
wp_object_interest_new_valist (GType gtype, va_list *args)
|
||||
{
|
||||
@@ -151,16 +170,17 @@ wp_object_interest_new_valist (GType gtype, va_list *args)
|
||||
return self;
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_new_type: (rename-to wp_object_interest_new)
|
||||
* @gtype: the type of the object to declare interest in
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param gtype: the type of the object to declare interest in
|
||||
*
|
||||
* Creates a new interest that declares interest in objects of the specified
|
||||
* @gtype, without any property constraints. To add property constraints,
|
||||
* @brief Creates a new interest that declares interest in objects of the specified
|
||||
* @em gtype, without any property constraints. To add property constraints,
|
||||
* you can call wp_object_interest_add_constraint() afterwards.
|
||||
*
|
||||
* Returns: (transfer full): the new object interest
|
||||
* @returns (transfer full): the new object interest
|
||||
*/
|
||||
|
||||
WpObjectInterest *
|
||||
wp_object_interest_new_type (GType gtype)
|
||||
{
|
||||
@@ -172,16 +192,16 @@ wp_object_interest_new_type (GType gtype)
|
||||
return self;
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_add_constraint:
|
||||
* @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
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: the object interest
|
||||
* @param type: the constraint type
|
||||
* @param subject: the subject that the constraint applies to
|
||||
* @param verb: the operation that is performed to check the constraint
|
||||
* @param value: (transfer floating)(nullable): the value to check for
|
||||
*
|
||||
* Adds a constraint to this interest. Constraints consist of a @type,
|
||||
* a @subject, a @verb and, depending on the @verb, a @value.
|
||||
* @brief Adds a constraint to this interest. Constraints consist of a @em type,
|
||||
* a @em subject, a @em verb and, depending on the @em verb, a @em 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
|
||||
@@ -193,27 +213,31 @@ wp_object_interest_new_type (GType gtype)
|
||||
* 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
|
||||
* Some verbs require a @em value and some others do not. For those that do,
|
||||
* the @em value must be of a specific type:
|
||||
* - %WP_CONSTRAINT_VERB_EQUALS: @em value can be a string, a (u)int32,
|
||||
* a (u)int64, a double or a boolean. The @em 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
|
||||
* - %WP_CONSTRAINT_VERB_IN_LIST: @em 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,
|
||||
* (u)int64 or double. These items make a list that the @em subject's value
|
||||
* will be checked against. If any of the items equals the @em subject value,
|
||||
* the constraint is satisfied
|
||||
* - %WP_CONSTRAINT_VERB_IN_RANGE: @value must be a tuple that contains exactly
|
||||
* - %WP_CONSTRAINT_VERB_IN_RANGE: @em 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
|
||||
* minimum and maximum (inclusive) of the range. If the @em 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
|
||||
* - %WP_CONSTRAINT_VERB_MATCHES: @em value must be a string that defines a
|
||||
* pattern usable with
|
||||
* <a href="https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html#GPatternSpec">
|
||||
* GPatternSpec.</a> If the @em 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(),
|
||||
* In case the type of the @em subject value is not the same type as the one
|
||||
* requested by the type of the @em value, the @em subject value is converted.
|
||||
* For
|
||||
* <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
|
||||
* GObject</a> 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
|
||||
@@ -225,6 +249,7 @@ wp_object_interest_new_type (GType gtype)
|
||||
* wp_object_interest_validate() should be called after adding all the
|
||||
* constraints on an interest in order to catch errors.
|
||||
*/
|
||||
|
||||
void
|
||||
wp_object_interest_add_constraint (WpObjectInterest * self,
|
||||
WpConstraintType type, const gchar * subject,
|
||||
@@ -247,12 +272,13 @@ wp_object_interest_add_constraint (WpObjectInterest * self,
|
||||
self->valid = FALSE;
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_copy:
|
||||
* @self: the object interest to copy
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: the object interest to copy
|
||||
*
|
||||
* Returns: (transfer full): a deep copy of @self
|
||||
* @returns (transfer full): a deep copy of @em self
|
||||
*/
|
||||
|
||||
WpObjectInterest *
|
||||
wp_object_interest_copy (WpObjectInterest * self)
|
||||
{
|
||||
@@ -279,12 +305,13 @@ wp_object_interest_copy (WpObjectInterest * self)
|
||||
return copy;
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_ref:
|
||||
* @self: the object interest to ref
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: the object interest to ref
|
||||
*
|
||||
* Returns: (transfer full): @self with an additional reference count on it
|
||||
* @returns (transfer full): @em self with an additional reference count on it
|
||||
*/
|
||||
|
||||
WpObjectInterest *
|
||||
wp_object_interest_ref (WpObjectInterest *self)
|
||||
{
|
||||
@@ -307,13 +334,14 @@ wp_object_interest_free (WpObjectInterest * self)
|
||||
g_slice_free (WpObjectInterest, self);
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_unref:
|
||||
* @self: (transfer full): the object interest to unref
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: (transfer full): the object interest to unref
|
||||
*
|
||||
* Decreases the reference count on @self and frees it when the ref count
|
||||
* @brief Decreases the reference count on @em self and frees it when the ref count
|
||||
* reaches zero.
|
||||
*/
|
||||
|
||||
void
|
||||
wp_object_interest_unref (WpObjectInterest * self)
|
||||
{
|
||||
@@ -321,17 +349,19 @@ wp_object_interest_unref (WpObjectInterest * self)
|
||||
wp_object_interest_free (self);
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_validate:
|
||||
* @self: the object interest to validate
|
||||
* @error: (out) (optional): the error, in case validation failed
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: the object interest to validate
|
||||
* @param error: (out) (optional): the error, in case validation failed
|
||||
*
|
||||
* Validates the interest, ensuring that the interest #GType is a valid
|
||||
* object and that all the constraints have been expressed properly.
|
||||
* @brief Validates the interest, ensuring that the interest
|
||||
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
|
||||
* GType</a> is a valid object and that all the constraints have been expressed properly.
|
||||
*
|
||||
* Returns: %TRUE if the interest is valid and can be used in a match,
|
||||
* @returns %TRUE if the interest is valid and can be used in a match,
|
||||
* %FALSE otherwise
|
||||
*/
|
||||
|
||||
gboolean
|
||||
wp_object_interest_validate (WpObjectInterest * self, GError ** error)
|
||||
{
|
||||
@@ -685,22 +715,25 @@ constraint_verb_in_range (gchar subj_type, const GValue * subj_val,
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_matches:
|
||||
* @self: the object interest
|
||||
* @object: the target object to check for a match
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: the object interest
|
||||
* @param object: the target object to check for a match
|
||||
*
|
||||
* Checks if the specified @object matches the type and all the constraints
|
||||
* that are described in @self
|
||||
* @brief Checks if the specified @em object matches the type and all the constraints
|
||||
* that are described in @em self
|
||||
*
|
||||
* If @self is configured to match #GObject subclasses, this is equivalent to
|
||||
* If @em self is configured to match
|
||||
* <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
|
||||
* GObject</a> 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
|
||||
* NULL, NULL)` and if it is configured to match [WpProperties](@ref properties_section), this is
|
||||
* equivalent to `wp_object_interest_matches_full (self, self->gtype, NULL,
|
||||
* (WpProperties *) object, NULL);`
|
||||
*
|
||||
* Returns: %TRUE if the object matches, %FALSE otherwise
|
||||
* @returns %TRUE if the object matches, %FALSE otherwise
|
||||
*/
|
||||
|
||||
gboolean
|
||||
wp_object_interest_matches (WpObjectInterest * self, gpointer object)
|
||||
{
|
||||
@@ -716,35 +749,37 @@ wp_object_interest_matches (WpObjectInterest * self, gpointer object)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* wp_object_interest_matches_full:
|
||||
* @self: the object interest
|
||||
* @object_type: the type to be checked against the interest's type
|
||||
* @object: (type GObject)(transfer none)(nullable): the object to be used for
|
||||
/*!
|
||||
* @memberof WpObjectInterest
|
||||
* @param self: the object interest
|
||||
* @param object_type: the type to be checked against the interest's type
|
||||
* @param 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
|
||||
* @param 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
|
||||
* @param pw_global_props: (transfer none)(nullable): the properties to be used for
|
||||
* checking constraints of type %WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY
|
||||
*
|
||||
* 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.
|
||||
* @brief A low-level version of wp_object_interest_matches(). In this version,
|
||||
* the object's type is directly given in @em object_type and is not inferred
|
||||
* from the @em object. @em object is only used to check for constraints against
|
||||
* <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
|
||||
* GObject</a> properties.
|
||||
*
|
||||
* @pw_props and @pw_global_props are used to check constraints against
|
||||
* @em pw_props and @em 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
|
||||
* @em object, @em pw_props and @em 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
|
||||
* As a special case, if @em object is not %NULL and is a subclass of [WpProxy](@ref proxy_section),
|
||||
* then @em pw_props and @em pw_global_props, if required, will be internally
|
||||
* retrieved from @em object by calling wp_pipewire_object_get_properties() and
|
||||
* wp_global_proxy_get_global_properties() respectively.
|
||||
*
|
||||
* Returns: %TRUE if the the type matches this interest and the properties
|
||||
* @returns %TRUE if the the type matches this interest and the properties
|
||||
* match the constraints, %FALSE otherwise
|
||||
*/
|
||||
|
||||
gboolean
|
||||
wp_object_interest_matches_full (WpObjectInterest * self,
|
||||
GType object_type, gpointer object, WpProperties * pw_props,
|
||||
@@ -887,4 +922,4 @@ wp_object_interest_matches_full (WpObjectInterest * self,
|
||||
}
|
||||
}
|
||||
return TRUE;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user