Core

digraph inheritance { rankdir=LR; GObject -> WpObject; WpObject -> WpCore; }

struct WpCore

The core is the central object around which everything operates. It is essential to create a WpCore before using any other WirePlumber API.

The core object has the following responsibilities:

  • it initializes the PipeWire library

  • it creates a pw_context and allows connecting to the PipeWire server, creating a local pw_core

  • it glues the PipeWire library’s event loop system with GMainLoop

  • it maintains a list of registered objects, which other classes use to keep objects loaded permanently into memory

  • it watches the PipeWire registry and keeps track of remote and local objects that appear in the registry, making them accessible through the WpObjectManager API.

The core is also responsible for loading components, which are defined in the main configuration file. Components are loaded when WP_CORE_FEATURE_COMPONENTS is activated.

Configuration

The main configuration file needs to be created and opened before the core is created, using the WpConf API. It is then passed to the core as an argument in the constructor.

If a configuration file is not provided, the core will let the underlying pw_context load its own configuration, based on the rules that apply to all pipewire clients (e.g. it respects the PIPEWIRE_CONFIG_NAME environment variable and loads “client.conf” as a last resort).

If a configuration file is provided, the core does not let the underlying pw_context load any configuration and instead uses the provided WpConf object.

GObject Properties

g-main-context

A GMainContext to attach to

GMainContext *

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

properties

The pipewire properties of the pw_core

WpProperties *

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

pw-context

The pipewire context

gpointer (struct pw_context *)

G_PARAM_READABLE

pw-core

The pipewire core

gpointer (struct pw_core *)

G_PARAM_READABLE

conf

The main configuration file

WpConf *

G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY

GObject Signals

connected

void
connected_callback (WpCore * self,
                    gpointer user_data)
Emitted when the core is successfully connected to the PipeWire server

disconnected

void
disconnected_callback (WpCore * self,
                       gpointer user_data)
Emitted when the core is disconnected from the PipeWire server

enum WpCoreFeatures

Flags to be used as WpObjectFeatures on WpCore.

Values:

enumerator WP_CORE_FEATURE_CONNECTED = (1 << 0)

connects to pipewire

enumerator WP_CORE_FEATURE_COMPONENTS = (1 << 1)

loads components defined in the configuration

WpCore *wp_core_new(GMainContext *context, WpConf *conf, WpProperties *properties)

Creates a new core object.

Parameters:

  • context – (transfer none) (nullable): the GMainContext to use for events

  • conf – (transfer full) (nullable): the main configuration file

  • properties – (transfer full) (nullable): additional properties, which are also passed to pw_context_new() and pw_context_connect()

Returns:

(transfer full): a new WpCore

WpCore *wp_core_clone(WpCore *self)

Clones a core with the same context as self.

Parameters:

  • self – the core

Returns:

(transfer full): the clone WpCore

WpCore *wp_core_get_export_core(WpCore *self)

Returns the special WpCore that is used to maintain a secondary connection to PipeWire, for exporting objects.

The export core is enabled by loading the built-in “export-core” component.

Parameters:

  • self – the core

Returns:

(transfer full): the export WpCore

WpConf *wp_core_get_conf(WpCore *self)

Gets the main configuration file of the core.

Parameters:

  • self – the core

Returns:

(transfer full) (nullable): the main configuration file

GMainContext *wp_core_get_g_main_context(WpCore *self)

Gets the GMainContext of the core.

Parameters:

  • self – the core

Returns:

(transfer none) (nullable): the GMainContext that is in use by this core for events

struct pw_context *wp_core_get_pw_context(WpCore *self)

Gets the internal PipeWire context of the core.

Parameters:

  • self – the core

Returns:

(transfer none): the internal pw_context object

struct pw_core *wp_core_get_pw_core(WpCore *self)

Gets the internal PipeWire core of the core.

Parameters:

  • self – the core

Returns:

(transfer none) (nullable): the internal pw_core object, or NULL if the core is not connected to PipeWire

gchar *wp_core_get_vm_type(WpCore *self)

Gets the virtual machine type of the core.

Since

0.4.11

Parameters:

  • self – the core

Returns:

(transfer full) (nullable): a comma separated string with all the virtual machine types that this core matches, or NULL if the core is not running in a virtual machine.

gboolean wp_core_connect(WpCore *self)

Connects this core to the PipeWire server.

When connection succeeds, the WpCore "connected" signal is emitted.

Parameters:

  • self – the core

Returns:

TRUE if the core is effectively connected or FALSE if connection failed

gboolean wp_core_connect_fd(WpCore *self, int fd)

Connects this core to the PipeWire server on the given socket.

When connection succeeds, the WpCore "connected" signal is emitted.

Since

0.5.6

Parameters:

  • self – the core

  • fd – the connected socket to use, the socket will be closed automatically on disconnect or error

Returns:

TRUE if the core is effectively connected or FALSE if connection failed

void wp_core_disconnect(WpCore *self)

Disconnects this core from the PipeWire server.

This also effectively destroys all WpCore objects that were created through the registry, destroys the pw_core and finally emits the WpCore "disconnected" signal.

Parameters:

  • self – the core

gboolean wp_core_is_connected(WpCore *self)

Checks if the core is connected to PipeWire.

Parameters:

  • self – the core

Returns:

TRUE if the core is connected to PipeWire, FALSE otherwise

guint32 wp_core_get_own_bound_id(WpCore *self)

Gets the bound id of the client object that is created as a result of this core being connected to the PipeWire daemon.

Since

0.4.16

Parameters:

  • self – the core

Returns:

the bound id of this client

Gets the cookie of the core’s connected PipeWire instance.

Parameters:

  • self – the core

Returns:

The cookie of the PipeWire instance that self is connected to. The cookie is a unique random number for identifying an instance of PipeWire

const gchar *wp_core_get_remote_name(WpCore *self)

Gets the name of the core’s connected PipeWire instance.

Parameters:

  • self – the core

Returns:

The name of the PipeWire instance that self is connected to

const gchar *wp_core_get_remote_user_name(WpCore *self)

Gets the user name of the core’s connected PipeWire instance.

Parameters:

  • self – the core

Returns:

The name of the user that started the PipeWire instance that self is connected to

const gchar *wp_core_get_remote_host_name(WpCore *self)

Gets the host name of the core’s connected PipeWire instance.

Parameters:

  • self – the core

Returns:

The name of the host where the PipeWire instance that self is connected to is running on

const gchar *wp_core_get_remote_version(WpCore *self)

Gets the version of the core’s connected PipeWire instance.

Parameters:

  • self – the core

Returns:

The version of the PipeWire instance that self is connected to

WpProperties *wp_core_get_remote_properties(WpCore *self)

Gets the properties of the core’s connected PipeWire instance.

Parameters:

  • self – the core

Returns:

(transfer full): the properties of the PipeWire instance that self is connected to

WpProperties *wp_core_get_properties(WpCore *self)

Gets the properties of the core.

Parameters:

  • self – the core

Returns:

(transfer full): the properties of self

void wp_core_update_properties(WpCore *self, WpProperties *updates)

Updates the properties of self on the connection, making them appear on the client object that represents this connection.

If self is not connected yet, these properties are stored and passed to pw_context_connect() when connecting.

Parameters:

  • self – the core

  • updates – (transfer full): updates to apply to the properties of self; this does not need to include properties that have not changed

void wp_core_idle_add(WpCore *self, GSource **source, GSourceFunc function, gpointer data, GDestroyNotify destroy)

Adds an idle callback to be called in the same GMainContext as the one used by this core.

This is essentially the same as g_idle_add_full(), but it adds the created GSource on the GMainContext used by this core instead of the default context.

Parameters:

  • self – the core

  • source – (out) (optional): the source

  • function – (scope notified): the function to call

  • data – (closure): data to pass to function

  • destroy – (nullable): a function to destroy data

void wp_core_idle_add_closure(WpCore *self, GSource **source, GClosure *closure)

Adds an idle callback to be called in the same GMainContext as the one used by this core.

This is the same as wp_core_idle_add(), but it allows you to specify a GClosure instead of a C callback.

Parameters:

  • self – the core

  • source – (out) (optional): the source

  • closure – the closure to invoke

void wp_core_timeout_add(WpCore *self, GSource **source, guint timeout_ms, GSourceFunc function, gpointer data, GDestroyNotify destroy)

Adds a timeout callback to be called at regular intervals in the same GMainContext as the one used by this core.

The function is called repeatedly until it returns FALSE, at which point the timeout is automatically destroyed and the function will not be called again. The first call to the function will be at the end of the first interval.

This is essentially the same as g_timeout_add_full(), but it adds the created GSource on the GMainContext used by this core instead of the default context.

Parameters:

  • self – the core

  • source – (out) (optional): the source

  • timeout_ms – the timeout in milliseconds

  • function – (scope notified): the function to call

  • data – (closure): data to pass to function

  • destroy – (nullable): a function to destroy data

void wp_core_timeout_add_closure(WpCore *self, GSource **source, guint timeout_ms, GClosure *closure)

Adds a timeout callback to be called at regular intervals in the same GMainContext as the one used by this core.

This is the same as wp_core_timeout_add(), but it allows you to specify a GClosure instead of a C callback.

Parameters:

  • self – the core

  • source – (out) (optional): the source

  • timeout_ms – the timeout in milliseconds

  • closure – the closure to invoke

gboolean wp_core_sync(WpCore *self, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)

Asks the PipeWire server to call the callback via an event.

Since methods are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous methods and the resulting events have been handled.

In both success and error cases, callback is always called. Use wp_core_sync_finish() from within the callback to determine whether the operation completed successfully or if an error occurred.

Parameters:

  • self – the core

  • cancellable – (nullable): a GCancellable to cancel the operation

  • callback – (scope async): a function to call when the operation is done

  • user_data – (closure): data to pass to callback

Returns:

TRUE if the sync operation was started, FALSE if an error occurred before returning from this function

gboolean wp_core_sync_closure(WpCore *self, GCancellable *cancellable, GClosure *closure)

Asks the PipeWire server to invoke the closure via an event.

Since methods are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous methods and the resulting events have been handled.

In both success and error cases, closure is always invoked. Use wp_core_sync_finish() from within the closure to determine whether the operation completed successfully or if an error occurred.

Since

0.4.6

Parameters:

  • self – the core

  • cancellable – (nullable): a GCancellable to cancel the operation

  • closure – (transfer floating): a closure to invoke when the operation is done

Returns:

TRUE if the sync operation was started, FALSE if an error occurred before returning from this function

gboolean wp_core_sync_finish(WpCore *self, GAsyncResult *res, GError **error)

This function is meant to be called from within the callback of wp_core_sync() in order to determine the success or failure of the operation.

Parameters:

  • self – the core

  • res – a GAsyncResult

  • error – (out) (optional): the error that occurred, if any

Returns:

TRUE if the operation succeeded, FALSE otherwise

gpointer wp_core_find_object(WpCore *self, GEqualFunc func, gconstpointer data)

Finds a registered object.

Parameters:

  • self – the core

  • func – (scope call): a function that takes the object being searched as the first argument and data as the second. it should return TRUE if the object is found or FALSE otherwise

  • data – the second argument to func

Returns:

(transfer full) (type GObject*) (nullable): the registered object or NULL if not found

void wp_core_register_object(WpCore *self, gpointer obj)

Registers obj with the core, making it appear on WpObjectManager instances as well.

The core will also maintain a ref to that object until it is removed.

Parameters:

  • self – the core

  • obj – (transfer full) (type GObject*): the object to register

void wp_core_remove_object(WpCore *self, gpointer obj)

Detaches and unrefs the specified object from this core.

Parameters:

  • self – the core

  • obj – (transfer none) (type GObject*): a pointer to the object to remove

gboolean wp_core_test_feature(WpCore *self, const gchar *feature)

Test if a global feature is provided.

Parameters:

  • self – the core

  • feature – the feature name

Returns:

TRUE if the feature is provided, FALSE otherwise

WP_TYPE_CORE (wp_core_get_type ())

The WpCore GType.