Object Manager
The WpObjectManager class provides a way to collect a set of objects and be notified when objects that fulfill a certain set of criteria are created or destroyed.
There are 4 kinds of objects that can be managed by a WpObjectManager:
- remote PipeWire global objects that are advertised on the registry; these are bound locally to subclasses of WpGlobalProxy
- remote PipeWire global objects that are created by calling a remote factory through the WirePlumber API; these are very similar to other global objects but it should be noted that the same WpGlobalProxy instance that created them appears in the WpObjectManager (as soon as its WP_PROXY_FEATURE_BOUND is enabled)
- local PipeWire objects that are being exported to PipeWire (#WpImplSession, WpImplEndpoint [private], etc); these appear in the WpObjectManager as soon as they are exported (so, when their WP_PROXY_FEATURE_BOUND is enabled)
- WirePlumber-specific objects, such as WirePlumber factories
To start an object manager, you first need to declare interest in a certain kind of object by calling wp_object_manager_add_interest and then install it on the WpCore with wp_core_install_object_manager.
Upon installing a WpObjectManager on a WpCore, any pre-existing objects that match the interests of this WpObjectManager will immediately become available to get through wp_object_manager_new_iterator and the object-added signal will be emitted for all of them.
WpObjectManager
GObject
╰──WpObjectManager
Class structure
WpObjectManagerClass
Fields
parent_class
(GObjectClass)
–
Constructors
wp_object_manager_new
WpObjectManager * wp_object_manager_new ()
Constructs a new object manager.
the newly constructed object manager
Methods
wp_object_manager_add_interest
wp_object_manager_add_interest (WpObjectManager * self, GType gtype, ... ...)
Equivalent to:
WpObjectInterest *i = wp_object_interest_new (gtype, ...);
wp_object_manager_add_interest_full (self, i);
The constraints specified in the variable arguments must follow the rules documented in wp_object_interest_new.
Parameters:
self
–
the object manager
gtype
–
the GType of the objects that we are declaring interest in
...
–
a list of constraints, terminated by NULL
wp_object_manager_add_interest_full
wp_object_manager_add_interest_full (WpObjectManager * self, WpObjectInterest * interest)
Declares interest in a certain kind of object. Interest consists of a GType that the object must be an ancestor of (g_type_is_a must match) and optionally, a set of additional constraints on certain properties of the object. Refer to WpObjectInterest for more details.
Parameters:
self
–
the object manager
interest
(
[transfer: full])
–
the interest
wp_object_manager_get_n_objects
guint wp_object_manager_get_n_objects (WpObjectManager * self)
Parameters:
self
–
the object manager
the number of objects managed by this WpObjectManager
wp_object_manager_is_installed
gboolean wp_object_manager_is_installed (WpObjectManager * self)
Parameters:
self
–
the object manager
TRUE if the object manager is installed (the WpObjectManager::installed has been emitted), FALSE otherwise
wp_object_manager_lookup
gpointer wp_object_manager_lookup (WpObjectManager * self, GType gtype, ... ...)
Equivalent to:
WpObjectInterest *i = wp_object_interest_new (gtype, ...);
return wp_object_manager_lookup_full (self, i);
The constraints specified in the variable arguments must follow the rules documented in wp_object_interest_new.
Parameters:
self
–
the object manager
gtype
–
the GType of the object to lookup
...
–
a list of constraints, terminated by NULL
the first managed object that matches the lookup interest, or NULL if no object matches
wp_object_manager_lookup_full
gpointer wp_object_manager_lookup_full (WpObjectManager * self, WpObjectInterest * interest)
Searches for an object that matches the specified interest and returns it, if found. If more than one objects match, only the first one is returned. To find multiple objects that match certain criteria, wp_object_manager_new_filtered_iterator is more suitable.
Parameters:
self
–
the object manager
interest
(
[transfer: full])
–
the interst
the first managed object that matches the lookup interest, or NULL if no object matches
wp_object_manager_new_filtered_iterator
WpIterator * wp_object_manager_new_filtered_iterator (WpObjectManager * self, GType gtype, ... ...)
Equivalent to:
WpObjectInterest *i = wp_object_interest_new (gtype, ...);
return wp_object_manager_new_filtered_iterator_full (self, i);
The constraints specified in the variable arguments must follow the rules documented in wp_object_interest_new.
Parameters:
self
–
the object manager
gtype
–
the GType of the objects to iterate through
...
–
a list of constraints, terminated by NULL
a WpIterator that iterates over all the matching objects of this object manager
wp_object_manager_new_filtered_iterator_full
WpIterator * wp_object_manager_new_filtered_iterator_full (WpObjectManager * self, WpObjectInterest * interest)
Iterates through all the objects managed by this object manager that match the specified interest.
Parameters:
self
–
the object manager
interest
(
[transfer: full])
–
the interest
a WpIterator that iterates over all the matching objects of this object manager
wp_object_manager_new_iterator
WpIterator * wp_object_manager_new_iterator (WpObjectManager * self)
Parameters:
self
–
the object manager
a WpIterator that iterates over all the managed objects of this object manager
wp_object_manager_request_object_features
wp_object_manager_request_object_features (WpObjectManager * self, GType object_type, WpObjectFeatures wanted_features)
Requests the object manager to automatically prepare the wanted_features on any managed object that is of the specified object_type. These features will always be prepared before the object appears on the object manager.
Parameters:
self
–
the object manager
object_type
–
the WpProxy descendant type
wanted_features
–
the features to enable on this kind of object
Signals
installed
installed_callback (WpObjectManager * self, gpointer user_data)
This is emitted once after the object manager is installed with wp_core_install_object_manager. If there are objects that need to be prepared asynchronously internally, emission of this signal is delayed until all objects are ready.
Parameters:
self
–
the object manager
user_data
–
Flags: Run First
object-added
object_added_callback (WpObjectManager * self, GObject* object, gpointer user_data)
Emitted when an object that matches the interests of this object manager is made available.
Parameters:
self
–
the object manager
object
(
[transfer: none])
–
the managed object that was just added
user_data
–
Flags: Run First
object-removed
object_removed_callback (WpObjectManager * self, GObject* object, gpointer user_data)
Emitted when an object that was previously added on this object manager is now being removed (and most likely destroyed). At the time that this signal is emitted, the object is still alive.
Parameters:
self
–
the object manager
object
(
[transfer: none])
–
the managed object that is being removed
user_data
–
Flags: Run First
objects-changed
objects_changed_callback (WpObjectManager * self, gpointer user_data)
Emitted when one or more objects have been recently added or removed from this object manager. This signal is useful to get notified only once when multiple changes happen in a short timespan. The receiving callback may retrieve the updated list of objects by calling wp_object_manager_new_iterator
Parameters:
self
–
the object manager
user_data
–
Flags: Run First
Properties
Constants
WP_TYPE_OBJECT_MANAGER
#define WP_TYPE_OBJECT_MANAGER (wp_object_manager_get_type ())
The WpObjectManager GType
The results of the search are