Object Manager

digraph inheritance { rankdir=LR; GObject -> WpObjectManager; }

struct WpObjectManager

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 (WpImplMetadata, WpImplEndpoint, 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 plugins, factories and session items

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 WpObjectManager object-added signal will be emitted for all of them. However, note that if these objects need to be prepared (to activate some features on them), the emission of object-added will be delayed. To know when it is safe to access the initial set of objects, wait until the installed signal has been emitted. That signal is emitted asynchronously after all the initial objects have been prepared.

GObject Properties

core

The core

WpCore *

G_PARAM_READABLE

GObject Signals

installed

void
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.

Flags: G_SIGNAL_RUN_FIRST

object-added

void
object_added_callback (WpObjectManager * self,
                       gpointer object,
                       gpointer user_data)

Emitted when an object that matches the interests of this object manager is made available.

Parameters:

  • object - the managed object that was just added

Flags: G_SIGNAL_RUN_FIRST

object-removed

void
object_removed_callback (WpObjectManager * self,
                         gpointer 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:

  • object - the managed object that is being removed

Flags: G_SIGNAL_RUN_FIRST

objects-changed

void
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()

Flags: G_SIGNAL_RUN_FIRST

WpObjectManager *wp_object_manager_new(void)

Constructs a new object manager.

Returns:

(transfer full): the newly constructed object manager

gboolean wp_object_manager_is_installed(WpObjectManager *self)

Checks if an object manager is installed.

Parameters:

  • self – the object manager

Returns:

TRUE if the object manager is installed (i.e. the WpObjectManager installed signal has been emitted), FALSE otherwise

void 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

void 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

void 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

guint wp_object_manager_get_n_objects(WpObjectManager *self)

Gets the number of objects managed by the object manager.

Parameters:

  • self – the object manager

Returns:

the number of objects managed by this WpObjectManager

WpIterator *wp_object_manager_new_iterator(WpObjectManager *self)

Iterates through all the objects managed by this object manager.

Parameters:

  • self – the object manager

Returns:

(transfer full): a WpIterator that iterates over all the managed objects of this object manager

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

Returns:

(transfer full): a WpIterator that iterates over all the matching objects of this object manager

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

Returns:

(transfer full): a WpIterator that iterates over all the matching objects of this object manager

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

Returns:

(type GObject)(transfer full)(nullable): the first managed object that matches the lookup interest, or NULL if no object matches

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

Returns:

(type GObject)(transfer full)(nullable): the first managed object that matches the lookup interest, or NULL if no object matches

void wp_core_install_object_manager(WpCore *self, WpObjectManager *om)

Installs the object manager on this core, activating its internal management engine.

This will immediately emit signals about objects added on om if objects that the om is interested in were in existence already.

Parameters:

  • self – the core

  • om – (transfer none): a WpObjectManager

WP_TYPE_OBJECT_MANAGER (wp_object_manager_get_type ())

The WpObjectManager GType.