Session Items Interfaces

digraph inheritance { rankdir=LR; GInterface -> WpSiEndpoint; GInterface -> WpSiAdapter; GInterface -> WpSiLinkable; GInterface -> WpSiLink; GInterface -> WpSiAcquisition; }

struct WpSiEndpoint

An interface for session items that implement a PipeWire endpoint.

GObject Signals

endpoint-properties-changed

void
endpoint_properties_changed_callback (WpSiEndpoint * self,
                                      gpointer user_data)
Emitted when the endpoint properties change

Flags: G_SIGNAL_RUN_LAST

struct _WpSiEndpointInterface

Public Members

GTypeInterface interface
GVariant *(*get_registration_info)(WpSiEndpoint *self)
WpProperties *(*get_properties)(WpSiEndpoint *self)
struct WpSiAdapter

An interface for port adapters

struct _WpSiAdapterInterface

Public Members

GTypeInterface interface
WpSpaPod *(*get_ports_format)(WpSiAdapter *self, const gchar **mode)
void (*set_ports_format)(WpSiAdapter *self, WpSpaPod *format, const gchar *mode, GAsyncReadyCallback callback, gpointer data)
gboolean (*set_ports_format_finish)(WpSiAdapter *self, GAsyncResult *res, GError **error)
struct WpSiLinkable

An interface for retrieving PipeWire port information from a session item. This information is used to create links in the nodes graph.

This is normally implemented by the same session items that implement WpSiEndpoint. The standard link implementation expects to be able to cast a WpSiEndpoint into a WpSiLinkable.

struct _WpSiLinkableInterface

Public Members

GTypeInterface interface
GVariant *(*get_ports)(WpSiLinkable *self, const gchar *context)
WpSiAcquisition *(*get_acquisition)(WpSiLinkable *self)

An interface for session items that provide a PipeWire endpoint link.

GObject Signals

link-properties-changed

void
link_properties_changed_callback (WpSiLink * self,
                                  gpointer user_data)
Emitted when the properties of the link change

Flags: G_SIGNAL_RUN_LAST

struct _WpSiLinkInterface

Public Members

GTypeInterface interface
GVariant *(*get_registration_info)(WpSiLink *self)
WpProperties *(*get_properties)(WpSiLink *self)
WpSiLinkable *(*get_out_item)(WpSiLink *self)
WpSiLinkable *(*get_in_item)(WpSiLink *self)
struct WpSiAcquisition

This interface provides a way to request an item for linking before doing so. This allows item implementations to apply internal policy rules.

A WpSiAcquisition is associated directly with a WpSiLinkable via wp_si_linkable_get_acquisition(). In order to allow switching policies, it is recommended that port info implementations use a separate session item to implement this interface and allow replacing it.

struct _WpSiAcquisitionInterface

Public Members

GTypeInterface interface
void (*acquire)(WpSiAcquisition *self, WpSiLink *acquisitor, WpSiLinkable *item, GAsyncReadyCallback callback, gpointer data)
gboolean (*acquire_finish)(WpSiAcquisition *self, GAsyncResult *res, GError **error)
void (*release)(WpSiAcquisition *self, WpSiLink *acquisitor, WpSiLinkable *item)
GVariant *wp_si_endpoint_get_registration_info(WpSiEndpoint *self)

This should return information that is used for registering the endpoint.

The return value should be a GVariant tuple of type (ssya{ss}) that contains, in order:

  • s: the endpoint’s name

  • s: the media class

  • y: the direction

  • a{ss}: additional properties to be added to the list of global properties

Parameters

  • self – the session item

Returns

(transfer full): registration info for the endpoint

WpProperties *wp_si_endpoint_get_properties(WpSiEndpoint *self)

Gets the properties of the endpoint.

Parameters

  • self – the session item

Returns

(transfer full) (nullable): the properties of the endpoint

WpSpaPod *wp_si_adapter_get_ports_format(WpSiAdapter *self, const gchar **mode)

Gets the format used to configure the adapter session item’s ports.

Parameters

  • self – the session item

  • mode – (out) (nullable): the mode

Returns

(transfer full): The format used to configure the ports of the adapter session item. Some items automatically choose a format when being activated, others never set a format on activation and the user needs to manually set it externally with wp_si_adapter_set_ports_format().

void wp_si_adapter_set_ports_format(WpSiAdapter *self, WpSpaPod *format, const gchar *mode, GAsyncReadyCallback callback, gpointer data)

Sets the format and configures the adapter session item ports using the given format.

The result of the operation can be checked using the wp_si_adapter_set_ports_format_finish() API. If format is NULL, the adapter will be configured with the default format. If mode is NULL, the adapter will use “dsp” mode.

Parameters

  • self – the session item

  • format – (transfer full) (nullable): the format to be set

  • mode – (nullable): the mode

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

  • data – (closure): user data for callback

gboolean wp_si_adapter_set_ports_format_finish(WpSiAdapter *self, GAsyncResult *res, GError **error)

Finishes the operation started by wp_si_adapter_set_format(). This is meant to be called in the callback that was passed to that method.

Parameters

  • self – the session item

  • res – the async result

  • error – (out) (optional): the operation’s error, if it occurred

Returns

TRUE on success, FALSE if there was an error

GVariant *wp_si_linkable_get_ports(WpSiLinkable *self, const gchar *context)

This method returns a variant of type “a(uuu)”, where each tuple in the array contains the following information:

  • u: (guint32) node id

  • u: (guint32) port id (the port must belong on the node specified above)

  • u: (guint32) the audio channel (enum spa_audio_channel) that this port makes available, or 0 for non-audio content

The order in which ports appear in this array is important when no channel information is available. The link implementation should link the ports in the order they appear. This is normally a good enough substitute for channel matching.

The context argument can be used to get different sets of ports from the item. The following well-known contexts are defined:

  • NULL: get the standard ports to be linked

  • ”monitor”: get the monitor ports

  • ”control”: get the control port

  • ”reverse”: get the reverse direction ports, if this item controls a filter node, which would have ports on both directions

Contexts other than NULL may only be used internally to ease the implementation of more complex item relationships. For example, a WpSessionItem that is in control of an input (sink) adapter node may implement WpSiLinkable where the NULL context will return the standard input ports and the “monitor” context will return the adapter’s monitor ports. When linking this item to another item, the NULL context will always be used, but the item may internally spawn a secondary WpSessionItem that implements the “monitor” item. That secondary item may implement WpSiLinkable, chaining calls to the WpSiLinkable of the original item using the “monitor” context. This way, the monitor WpSessionItem does not need to share control of the underlying node; it only proxies calls to satisfy the API.

Parameters

  • self – the session item

  • context – (nullable): an optional context for the ports

Returns

(transfer full): a GVariant containing information about the ports of this item

WpSiAcquisition *wp_si_linkable_get_acquisition(WpSiLinkable *self)

Gets the acquisition interface associated with the item.

Parameters

  • self – the session item

Returns

(transfer none) (nullable): the acquisition interface associated with this item, or NULL if this item does not require acquiring items before linking them

This should return information that is used for registering the link, as a GVariant of type a{ss} that contains additional properties to be added to the list of global properties.

Parameters

  • self – the session item

Returns

(transfer full): registration info for the link

Gets the properties of the link.

Parameters

  • self – the session item

Returns

(transfer full) (nullable): the properties of the link

Gets the output item linked by the link.

Parameters

  • self – the session item

Returns

(transfer none): the output item that is linked by this link

Gets the input item linked by the link.

Parameters

  • self – the session item

Returns

(transfer none): the input item that is linked by this link

void wp_si_acquisition_acquire(WpSiAcquisition *self, WpSiLink *acquisitor, WpSiLinkable *item, GAsyncReadyCallback callback, gpointer data)

Acquires the item for linking by acquisitor.

When a link is not allowed by policy, this operation should return an error.

When a link needs to be delayed for a short amount of time (ex. to apply a fade out effect on another item), this operation should finish with a delay. It is safe to assume that after this operation completes, the item will be linked immediately.

Parameters

  • self – the session item

  • acquisitor – the link that is trying to acquire a port info item

  • item – the item that is being acquired

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

  • data – (closure): user data for callback

gboolean wp_si_acquisition_acquire_finish(WpSiAcquisition *self, GAsyncResult *res, GError **error)

Finishes the operation started by wp_si_acquisition_acquire(). This is meant to be called in the callback that was passed to that method.

Parameters

  • self – the session item

  • res – the async result

  • error – (out) (optional): the operation’s error, if it occurred

Returns

TRUE on success, FALSE if there was an error

void wp_si_acquisition_release(WpSiAcquisition *self, WpSiLink *acquisitor, WpSiLinkable *item)

Releases the item, which means that it is being unlinked.

Parameters

  • self – the session item

  • acquisitor – the link that had previously acquired the item

  • item – the port info that is being released

WP_TYPE_SI_ENDPOINT (wp_si_endpoint_get_type ())

The WpSiEndpoint GType.

WP_TYPE_SI_ADAPTER (wp_si_adapter_get_type ())

The WpSiAdapter GType.

WP_TYPE_SI_LINKABLE (wp_si_linkable_get_type ())

The WpSiLinkable GType.

The WpSiLink GType.

WP_TYPE_SI_ACQUISITION (wp_si_acquisition_get_type ())

The WpSiAcquisition GType.