colin/wireplumber
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: api: Replace hotdoc specific commands with Doxygen specific commands

Browse Source
This commit is contained in:
Raghavendra
2021-05-13 17:54:58 +03:00
committed by George Kiagiadakis
parent 89549247f8
commit d692f06f0d
90 changed files with 4716 additions and 2766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/api/client_api.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _client_api:
Pipewire Client
===============
.. doxygenstruct:: WpClient
:project: WirePlumber
:members:

7
docs/api/components_api.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _components_api:
Pipewire Components
===================
.. doxygenstruct:: WpComponentLoader
:project: WirePlumber
:members:

7
docs/api/core_api.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _core_api:
Pipewire Core
=============
.. doxygenstruct:: WpCore
:project: WirePlumber
:members:

7
docs/api/device_api.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _device_api:
Pipewire Device
===============
.. doxygenstruct:: WpDevice
:project: WirePlumber
:members:

6
docs/api/endpoint_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _endpoint_api:
Pipewire Endpoint
=================
.. doxygenstruct:: WpEndpoint
:project: WirePlumber

6
docs/api/global_proxy_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _global_proxy_api:
Pipewire Global Object Proxy
============================
.. doxygenstruct:: WpGlobalProxy
:project: WirePlumber

6
docs/api/iterator_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _iterator_api:
Iterator
========
.. doxygenstruct:: WpIterator
:project: WirePlumber

31
docs/api/library_root.rst Normal file
View File

@@ -0,0 +1,31 @@
.. _library_root:
API Documentation
=================
* :ref:`client_api`
* :ref:`components_api`
* :ref:`core_api`
* :ref:`device_api`
* :ref:`endpoint_api`
* :ref:`global_proxy_api`
* :ref:`iterator_api`
* :ref:`link_api`
* :ref:`metadata_api`
* :ref:`node_api`
* :ref:`obj_interest_api`
* :ref:`obj_manager_api`
* :ref:`object_api`
* :ref:`plugin_api`
* :ref:`port_api`
* :ref:`properties_api`
* :ref:`proxy_interfaces_api`
* :ref:`proxy_api`
* :ref:`session_item_api`
* :ref:`si_factory_api`
* :ref:`si_interfaces_api`
* :ref:`state_api`
* :ref:`transitions_api`
* :ref:`spa_type_api`
* :ref:`spa_pod_api`
* :ref:`wp_api`

6
docs/api/link_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _link_api:
Pipewire Link
=============
.. doxygenstruct:: WpLink
:project: WirePlumber

34
docs/api/meson.build Normal file
View File

@@ -0,0 +1,34 @@
# you need to add here any files you add to the api directory as well
files = [
'library_root.rst',
'client_api.rst',
'components_api.rst',
'core_api.rst',
'device_api.rst',
'endpoint_api.rst',
'global_proxy_api.rst',
'iterator_api.rst',
'link_api.rst',
'metadata_api.rst',
'node_api.rst',
'obj_interest_api.rst',
'obj_manager_api.rst',
'object_api.rst',
'plugin_api.rst',
'port_api.rst',
'properties_api.rst',
'proxy_interfaces_api.rst',
'proxy_api.rst',
'session_item_api.rst',
'si_factory_api.rst',
'si_interfaces_api.rst',
'state_api.rst',
'transitions_api.rst',
'spa_type_api.rst',
'spa_pod_api.rst',
'wp_api.rst'
]
foreach file : files
configure_file(input: file, output: file, copy: true)
endforeach

11
docs/api/metadata_api.rst Normal file
View File

@@ -0,0 +1,11 @@
.. _metadata_api:
PipeWire Metadata
=================
.. doxygenstruct:: WpMetadata
:project: WirePlumber
:members:
.. doxygenstruct:: WpImplMetadata
:project: WirePlumber
:members:

11
docs/api/node_api.rst Normal file
View File

@@ -0,0 +1,11 @@
.. _node_api:
PipeWire Node
=============
.. doxygenstruct:: WpNode
:project: WirePlumber
:members:
.. doxygenstruct:: WpImplNode
:project: WirePlumber
:members:

6
docs/api/obj_interest_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _obj_interest_api:
Object Interest
===============
.. doxygenstruct:: WpObjectInterest
:project: WirePlumber

6
docs/api/obj_manager_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _obj_manager_api:
Object Manager
==============
.. doxygenstruct:: WpObjectManager
:project: WirePlumber

6
docs/api/object_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _object_api:
Base Object Type
================
.. doxygenstruct:: WpObject
:project: WirePlumber

6
docs/api/plugin_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _plugin_api:
Wireplumber Daemon Plugins
==========================
.. doxygenstruct:: WpPlugin
:project: WirePlumber

6
docs/api/port_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _port_api:
PipeWire Port
=============
.. doxygenstruct:: WpPort
:project: WirePlumber

6
docs/api/properties_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _properties_api:
PipeWire Properties Dictionary
==============================
.. doxygenstruct:: WpProperties
:project: WirePlumber

6
docs/api/proxy_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _proxy_api:
PipeWire Object Proxy
=====================
.. doxygenstruct:: WpProxy
:project: WirePlumber

6
docs/api/proxy_interfaces_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _proxy_interfaces_api:
PipeWire Object Proxy Interfaces
================================
.. doxygenstruct:: WpPipewireObject
:project: WirePlumber

6
docs/api/session_item_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _session_item_api:
Session Items
=============
.. doxygenstruct:: WpSessionItem
:project: WirePlumber

6
docs/api/si_factory_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _si_factory_api:
Session Items Factory
=====================
.. doxygenstruct:: WpSiFactory
:project: WirePlumber

9
docs/api/si_interfaces_api.rst Normal file
View File

@@ -0,0 +1,9 @@
.. _si_interfaces_api:
Session Items Interfaces
========================
.. doxygenstruct:: WpSiAcquisition
.. doxygenstruct:: WpSiEndpoint
.. doxygenstruct:: WpSiLink
.. doxygenstruct:: WpSiPortInfo
:project: WirePlumber

6
docs/api/spa_pod_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _spa_pod_api:
Spa Pod (Plain Old Data)
========================
.. doxygenstruct:: WpSpaPod
:project: WirePlumber

6
docs/api/spa_type_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _spa_type_api:
Spa Type Information
====================
.. doxygenstruct:: WpSpaType
:project: WirePlumber

6
docs/api/state_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _state_api:
State Storage
=============
.. doxygenstruct:: WpState
:project: WirePlumber

6
docs/api/transitions_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _transitions_api:
Transitions
===========
.. doxygenstruct:: WpTransition
:project: WirePlumber

6
docs/api/wp_api.rst Normal file
View File

@@ -0,0 +1,6 @@
.. _wp_api:
Library Initialization
======================
.. doxygenstruct:: Wp
:project: WirePlumber

3
docs/meson.build
View File

@@ -95,8 +95,9 @@ foreach file : sphinx_files
configure_file(input: file, output: file, copy: true)
endforeach
# and those in toc
# and those in toc and api
subdir('toc')
subdir('api')
sphinx_doc = custom_target(
'breathe',

64
lib/wp/client.c
View File

@@ -6,16 +6,33 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: client
* @title: PipeWire Client
*/
#define G_LOG_DOMAIN "wp-client"
#include "client.h"
#include "private/pipewire-object-mixin.h"
/*!
* @file client.c
*/
/*!
* @section client_section Pipewire Client
*
* @struct WpClient
*
* @brief
*
* The [WpClient](@ref client_section) class allows accessing the properties and methods of a PipeWire
* client object (`struct pw_client`). A [WpClient](@ref client_section) is constructed internally
* when a new client connects to PipeWire and it is made available through the
* [WpObjectManager](@ref object_manager_section) API.
*
*/
/*!
* @brief
* @em parent
*/
struct _WpClient
{
WpGlobalProxy parent;
@@ -24,14 +41,6 @@ struct _WpClient
static void wp_client_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpClient:
*
* The #WpClient class allows accessing the properties and methods of a PipeWire
* client object (`struct pw_client`). A #WpClient is constructed internally
* when a new client connects to PipeWire and it is made available through the
* #WpObjectManager API.
*/
G_DEFINE_TYPE_WITH_CODE (WpClient, wp_client, WP_TYPE_GLOBAL_PROXY,
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
wp_pw_object_mixin_object_interface_init)
@@ -113,15 +122,18 @@ wp_client_pw_object_mixin_priv_interface_init (
wp_pw_object_mixin_priv_interface_info_init_no_params (iface, client, CLIENT);
}
/**
* wp_client_update_permissions:
* @self: the client
* @n_perm: the number of permissions specified in the variable arguments
* @...: @n_perm pairs of #guint32 numbers; the first number is the object id
/*!
* @memberof WpClient
*
* @param self: the client
* @param n_perm: the number of permissions specified in the variable arguments
* @...: @em n_perm pairs of
* <a href="https://developer.gnome.org/glib/stable/glib-Basic-Types.html#guint32">
* guint32</a> numbers; the first number is the object id
* and the second is the permissions that this client should have
* on this object
*
* Update client's permissions on a list of objects. An object id of `-1`
* @brief Update client's permissions on a list of objects. An object id of `-1`
* can be used to set the default object permissions for this client
*/
void
@@ -141,15 +153,17 @@ wp_client_update_permissions (WpClient * self, guint n_perm, ...)
wp_client_update_permissions_array (self, n_perm, perm);
}
/**
* wp_client_update_permissions_array:
* @self: the client
* @n_perm: the number of permissions specified in the @permissions array
* @permissions: (array length=n_perm) (element-type pw_permission): an array
/*!
* @memberof WpClient
*
* @param self: the client
* @param n_perm: the number of permissions specified in the @em permissions array
* @param permissions: (array length=n_perm) (element-type pw_permission): an array
* of permissions per object id
*
* Update client's permissions on a list of objects. An object id of `-1`
* @brief Update client's permissions on a list of objects. An object id of `-1`
* can be used to set the default object permissions for this client
*
*/
void
wp_client_update_permissions_array (WpClient * self,

12
lib/wp/client.h
View File

@@ -15,10 +15,16 @@ G_BEGIN_DECLS
struct pw_permission;
/**
* WP_TYPE_CLIENT:
/*!
* @memberof WpClient
*
* The #WpClient #GType
* @brief The [WpClient](@ref client_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_CLIENT (wp_client_get_type ())
* @endcode
*/
#define WP_TYPE_CLIENT (wp_client_get_type ())
WP_API

28
lib/wp/component-loader.c
View File

@@ -6,11 +6,16 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: component-loader
* @title: Components
/*!
* @file component-loader.c
*/
/*!
* @struct WpComponentLoader
* @section component_loader_section Components
*/
#define G_LOG_DOMAIN "wp-comp-loader"
#include "component-loader.h"
@@ -113,17 +118,18 @@ wp_component_loader_load (WpComponentLoader * self, const gchar * component,
args, error);
}
/**
* wp_core_load_component:
* @self: the core
* @component: the module name or file name
* @type: the type of the component
* @args: (transfer floating)(nullable): additional arguments for the component,
/*!
* @memberof WpCore
* @param self: the core
* @param component: the module name or file name
* @param type: the type of the component
* @param args (transfer floating)(nullable): additional arguments for the component,
* usually a dict or a string
* @error: (out) (optional): return location for errors, or NULL to ignore
* @param error: (out) (optional): return location for errors, or NULL to ignore
*
* Returns: %TRUE if loaded, %FALSE if there was an error
* @returns %TRUE if loaded, %FALSE if there was an error
*/
gboolean
wp_core_load_component (WpCore * self, const gchar * component,
const gchar * type, GVariant * args, GError ** error)

16
lib/wp/component-loader.h
View File

@@ -13,16 +13,26 @@
G_BEGIN_DECLS
/**
* WP_TYPE_COMPONENT_LOADER:
/*!
* @memberof WpComponentLoader
*
* The #WpComponentLoader #GType
* @brief The [WpComponentLoader](@ref component_loader_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_COMPONENT_LOADER (wp_component_loader_get_type ())
* @endcode
*/
#define WP_TYPE_COMPONENT_LOADER (wp_component_loader_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpComponentLoader, wp_component_loader,
WP, COMPONENT_LOADER, WpPlugin)
/*!
* @brief
* @em parent_class
*/
struct _WpComponentLoaderClass
{
WpPluginClass parent_class;

407
lib/wp/core.c
View File

@@ -6,25 +6,9 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: core
* @title: Core
*
* 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.
/*!
* @file core.c
*/
#define G_LOG_DOMAIN "wp-core"
#include "core.h"
@@ -95,10 +79,26 @@ wp_loop_source_new (void)
return (GSource *) s;
}
/**
* WpCore
/*!
* @struct WpCore
*
* @section core_section Core
*
* @brief The core is the central object around which everything operates. It is
* essential to create a [WpCore](@ref core_section) 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](@ref object_manager_section) API.
*
*/
struct _WpCore
{
GObject parent;
@@ -122,6 +122,41 @@ struct _WpCore
GHashTable *async_tasks; // <int seq, GTask*>
};
/*!
* @memberof WpCore
*
* @props @b g-main-context
*
* @code
* "g-main-context" GMainContext *
* @endcode
*
* Flags : Read / Write / Construct Only
*
* @props @b properties
*
* @code
* "properties" WpProperties *
* @endcode
*
* Flags : Read / Write / Construct Only
*
* @props @b pw-context
*
* @code
* "pw-context" gpointer *
* @endcode
*
* Flags : Read
*
* @props @b pw-core
*
* @code
* "pw-core" gpointer *
* @endcode
*
* Flags : Read
*/
enum {
PROP_0,
PROP_G_MAIN_CONTEXT,
@@ -130,6 +165,33 @@ enum {
PROP_PW_CORE,
};
/*!
* @memberof WpCore
*
* @signal @b connected
*
* Params:
* @arg @c self: the core
*
* Emitted when the core is successfully connected to the PipeWire server
* @code
* connected_callback (WpCore * self,
* gpointer user_data)
* @endcode
*
*
* @signal @b disconnected
*
* Params:
* @arg @c self: the core
*
* Emitted when the core is disconnected from the PipeWire server
* @code
* disconnected_callback (WpCore * self,
* gpointer user_data)
* @endcode
*
*/
enum {
SIGNAL_CONNECTED,
SIGNAL_DISCONNECTED,
@@ -138,11 +200,7 @@ enum {
static guint32 signals[NUM_SIGNALS];
/**
* WP_TYPE_CORE:
*
* The #WpCore #GType
*/
G_DEFINE_TYPE (WpCore, wp_core, G_TYPE_OBJECT)
static void
@@ -388,8 +446,9 @@ wp_core_class_init (WpCoreClass * klass)
g_param_spec_pointer ("pw-core", "pw-core", "The pipewire core",
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
/*
* WpCore::connected:
*
* @self: the core
*
* Emitted when the core is successfully connected to the PipeWire server
@@ -398,8 +457,9 @@ wp_core_class_init (WpCoreClass * klass)
G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL,
G_TYPE_NONE, 0);
/**
/*
* WpCore::disconnected:
*
* @self: the core
*
* Emitted when the core is disconnected from the PipeWire server
@@ -409,13 +469,16 @@ wp_core_class_init (WpCoreClass * klass)
G_TYPE_NONE, 0);
}
/**
* wp_core_new:
* @context: (transfer none) (nullable): the #GMainContext to use for events
* @properties: (transfer full) (nullable): additional properties, which are
/*!
* @memberof WpCore
*
* @param context: (transfer none) (nullable): the
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> to use for events
* @param properties: (transfer full) (nullable): additional properties, which are
* passed to `pw_context_new` and `pw_context_connect`
*
* Returns: (transfer full): a new #WpCore
* @returns (transfer full): a new [WpCore](@ref core_section)
*/
WpCore *
wp_core_new (GMainContext *context, WpProperties * properties)
@@ -428,13 +491,13 @@ wp_core_new (GMainContext *context, WpProperties * properties)
NULL);
}
/**
* wp_core_clone:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Clones a core with the same context as @self
* @brief Clones a core with the same context as @em self
*
* Returns: (transfer full): the clone #WpCore
* @returns (transfer full): the clone [WpCore](@ref core_section)
*/
WpCore *
wp_core_clone (WpCore * self)
@@ -446,12 +509,13 @@ wp_core_clone (WpCore * self)
NULL);
}
/**
* wp_core_get_g_main_context:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: (transfer none) (nullable): the #GMainContext that is in use by
* this core for events
* @returns (transfer none) (nullable): the
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> that is in use by this core for events
*/
GMainContext *
wp_core_get_g_main_context (WpCore * self)
@@ -460,11 +524,11 @@ wp_core_get_g_main_context (WpCore * self)
return self->g_main_context;
}
/**
* wp_core_get_pw_context:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: (transfer none): the internal `pw_context` object
* @returns (transfer none): the internal `pw_context` object
*/
struct pw_context *
wp_core_get_pw_context (WpCore * self)
@@ -473,11 +537,11 @@ wp_core_get_pw_context (WpCore * self)
return self->pw_context;
}
/**
* wp_core_get_pw_core:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: (transfer none) (nullable): the internal `pw_core` object,
* @returns (transfer none) (nullable): the internal `pw_core` object,
* or %NULL if the core is not connected to PipeWire
*/
struct pw_core *
@@ -487,14 +551,14 @@ wp_core_get_pw_core (WpCore * self)
return self->pw_core;
}
/**
* wp_core_connect:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Connects this core to the PipeWire server. When connection succeeds,
* the #WpCore::connected signal is emitted
* @brief Connects this core to the PipeWire server. When connection succeeds,
* the [WpCore](@ref core_section) [connected](@ref signal_connected_section) signal is emitted
*
* Returns: %TRUE if the core is effectively connected or %FALSE if
* @returns %TRUE if the core is effectively connected or %FALSE if
* connection failed
*/
gboolean
@@ -525,13 +589,14 @@ wp_core_connect (WpCore *self)
return TRUE;
}
/**
* wp_core_disconnect:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Disconnects this core from the PipeWire server. This also effectively
* destroys all #WpProxy objects that were created through the registry,
* destroys the `pw_core` and finally emits the #WpCore::disconnected signal.
* @brief Disconnects this core from the PipeWire server. This also effectively
* destroys all [WpCore](@ref core_section) objects that were created through the registry,
* destroys the `pw_core` and finally emits the [WpCore](@ref core_section)
* [disconnected](@ref signal_disconnected_section) signal.
*/
void
wp_core_disconnect (WpCore *self)
@@ -544,11 +609,11 @@ wp_core_disconnect (WpCore *self)
pw_core_disconnect (self->pw_core);
}
/**
* wp_core_is_connected:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: %TRUE if the core is connected to PipeWire, %FALSE otherwise
* @returns %TRUE if the core is connected to PipeWire, %FALSE otherwise
*/
gboolean
wp_core_is_connected (WpCore * self)
@@ -557,11 +622,11 @@ wp_core_is_connected (WpCore * self)
return self->pw_core != NULL;
}
/**
* wp_core_get_remote_cookie:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: The cookie of the PipeWire instance that @self is connected to.
* @returns The cookie of the PipeWire instance that @em self is connected to.
* The cookie is a unique random number for identifying an instance of
* PipeWire
*/
@@ -574,11 +639,11 @@ wp_core_get_remote_cookie (WpCore * self)
return self->info->cookie;
}
/**
* wp_core_get_remote_name:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: The name of the PipeWire instance that @self is connected to
* @returns The name of the PipeWire instance that @em self is connected to
*/
const gchar *
wp_core_get_remote_name (WpCore * self)
@@ -589,12 +654,12 @@ wp_core_get_remote_name (WpCore * self)
return self->info->name;
}
/**
* wp_core_get_remote_user_name:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: The name of the user that started the PipeWire instance that
* @self is connected to
* @returns The name of the user that started the PipeWire instance that
* @em self is connected to
*/
const gchar *
wp_core_get_remote_user_name (WpCore * self)
@@ -605,12 +670,12 @@ wp_core_get_remote_user_name (WpCore * self)
return self->info->user_name;
}
/**
* wp_core_get_remote_host_name:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: The name of the host where the PipeWire instance that
* @self is connected to is running on
* @returns The name of the host where the PipeWire instance that
* @em self is connected to is running on
*/
const gchar *
wp_core_get_remote_host_name (WpCore * self)
@@ -621,11 +686,11 @@ wp_core_get_remote_host_name (WpCore * self)
return self->info->host_name;
}
/**
* wp_core_get_remote_version:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: The version of the PipeWire instance that @self is connected to
* @returns The version of the PipeWire instance that @em self is connected to
*/
const gchar *
wp_core_get_remote_version (WpCore * self)
@@ -636,12 +701,12 @@ wp_core_get_remote_version (WpCore * self)
return self->info->version;
}
/**
* wp_core_get_remote_properties:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: (transfer full): the properties of the PipeWire instance that
* @self is connected to
* @returns (transfer full): the properties of the PipeWire instance that
* @em self is connected to
*/
WpProperties *
wp_core_get_remote_properties (WpCore * self)
@@ -652,11 +717,11 @@ wp_core_get_remote_properties (WpCore * self)
return wp_properties_new_wrap_dict (self->info->props);
}
/**
* wp_core_get_properties:
* @self: the core
/*!
* @memberof WpCore
* @param self: the core
*
* Returns: (transfer full): the properties of @self
* @returns (transfer full): the properties of @em self
*/
WpProperties *
wp_core_get_properties (WpCore * self)
@@ -682,16 +747,16 @@ wp_core_get_properties (WpCore * self)
}
}
/**
* wp_core_update_properties:
* @self: the core
* @updates: (transfer full): updates to apply to the properties of @self;
/*!
* @memberof WpCore
* @param self: the core
* @param updates: (transfer full): updates to apply to the properties of @em self;
* this does not need to include properties that have not changed
*
* Updates the properties of @self on the connection, making them appear on
* @brief Updates the properties of @em 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
* If @em self is not connected yet, these properties are stored and passed to
* `pw_context_connect` when connecting.
*/
void
@@ -713,18 +778,22 @@ wp_core_update_properties (WpCore * self, WpProperties * updates)
pw_core_update_properties (self->pw_core, wp_properties_peek_dict (upd));
}
/**
* wp_core_idle_add:
* @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
/*!
* @memberof WpCore
* @param self: the core
* @param source: (out) (optional): the source
* @param function: (scope notified): the function to call
* @param data: (closure): data to pass to @em function
* @param destroy: (nullable): a function to destroy @em data
*
* 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.
* @brief Adds an idle callback to be called in the same
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> as the one used by this core. This is essentially the same as g_idle_add_full(),
* but it adds the created
* <a href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">
* GSource</a> on the
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> used by this core instead of the default context.
*/
void
wp_core_idle_add (WpCore * self, GSource **source, GSourceFunc function,
@@ -742,17 +811,19 @@ wp_core_idle_add (WpCore * self, GSource **source, GSourceFunc function,
*source = g_source_ref (s);
}
/**
* wp_core_idle_add_closure: (rename-to wp_core_idle_add)
* @self: the core
* @source: (out) (optional): the source
* @closure: the closure to invoke
/*!
* @memberof WpCore
* @param self: the core
* @param source: (out) (optional): the source
* @param closure: the closure to invoke
*
* Adds an idle callback to be called in the same #GMainContext as the
* one used by this core.
* @brief Adds an idle callback to be called in the same
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext </a> 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.
* This is the same as wp_core_idle_add(), but it allows you to specify a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Closures.html#GClosure-struct">
* GClosure</a> instead of a C callback.
*/
void
wp_core_idle_add_closure (WpCore * self, GSource **source, GClosure * closure)
@@ -770,22 +841,26 @@ wp_core_idle_add_closure (WpCore * self, GSource **source, GClosure * closure)
*source = g_source_ref (s);
}
/**
* wp_core_timeout_add:
* @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
/*!
* @memberof WpCore
* @param self: the core
* @param source: (out) (optional): the source
* @param timeout_ms: the timeout in milliseconds
* @param function: (scope notified): the function to call
* @param data: (closure): data to pass to @em function
* @param destroy: (nullable): a function to destroy @em data
*
* 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
* @brief Adds a timeout callback to be called at regular intervals in the same
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> 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.
* g_timeout_add_full(), but it adds the created
* <a href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">
* GSource</a> on the
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> used by this core instead of the default context.
*/
void
wp_core_timeout_add (WpCore * self, GSource **source, guint timeout_ms,
@@ -803,18 +878,20 @@ wp_core_timeout_add (WpCore * self, GSource **source, guint timeout_ms,
*source = g_source_ref (s);
}
/**
* wp_core_timeout_add_closure: (rename-to wp_core_timeout_add)
* @self: the core
* @source: (out) (optional): the source
* @timeout_ms: the timeout in milliseconds
* @closure: the closure to invoke
/*!
* @memberof WpCore
* @param self: the core
* @param source: (out) (optional): the source
* @param timeout_ms: the timeout in milliseconds
* @param closure: the closure to invoke
*
* Adds a timeout callback to be called at regular intervals in the same
* #GMainContext as the one used by this core.
* @brief Adds a timeout callback to be called at regular intervals in the same
* <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
* GMainContext</a> 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.
* This is the same as wp_core_timeout_add(), but it allows you to specify a
* <a href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">
* GClosure</a> instead of a C callback.
*/
void
wp_core_timeout_add_closure (WpCore * self, GSource **source, guint timeout_ms,
@@ -833,24 +910,26 @@ wp_core_timeout_add_closure (WpCore * self, GSource **source, guint timeout_ms,
*source = g_source_ref (s);
}
/**
* wp_core_sync:
* @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
/*!
* @memberof WpCore
* @param self: the core
* @param cancellable: (nullable):
* a <a href="https://developer.gnome.org/gio/stable/GCancellable.html#GCancellable-struct">
* GCancellable</a> to cancel the operation
* @param callback: (scope async): a function to call when the operation is done
* @param user_data: (closure): data to pass to @em callback
*
* Asks the PipeWire server to call the @callback via an event.
* @brief Asks the PipeWire server to call the @em 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
* In both success and error cases, @em callback is always called. Use
* wp_core_sync_finish() from within the @em callback to determine whether
* the operation completed successfully or if an error occurred.
*
* Returns: %TRUE if the sync operation was started, %FALSE if an error
* @returns %TRUE if the sync operation was started, %FALSE if an error
* occurred before returning from this function
*/
gboolean
@@ -887,16 +966,18 @@ wp_core_sync (WpCore * self, GCancellable * cancellable,
return TRUE;
}
/**
* wp_core_sync_finish:
* @self: the core
* @res: a #GAsyncResult
* @error: (out) (optional): the error that occurred, if any
/*!
* @memberof WpCore
* @param self: the core
* @param res: a
* <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncResult-struct">
* GAsyncResult</a>
* @param error: (out) (optional): the error that occurred, if any
*
* This function is meant to be called from within the callback of
* @brief 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.
*
* Returns: %TRUE if the operation succeeded, %FALSE otherwise
* @returns %TRUE if the operation succeeded, %FALSE otherwise
*/
gboolean
wp_core_sync_finish (WpCore * self, GAsyncResult * res, GError ** error)

12
lib/wp/core.h
View File

@@ -19,6 +19,18 @@ struct pw_context;
struct pw_core;
typedef struct _WpObjectManager WpObjectManager;
/*!
* @memberof WpCore
*
* @brief The [WpCore](@ref core_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_CORE (wp_core_get_type ())
* @endcode
*/
#define WP_TYPE_CORE (wp_core_get_type ())
WP_API
G_DECLARE_FINAL_TYPE (WpCore, wp_core, WP, CORE, GObject)

229
lib/wp/device.c
View File

@@ -6,11 +6,6 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: device
* @title: PipeWire Device
*/
#define G_LOG_DOMAIN "wp-device"
#include "device.h"
@@ -25,6 +20,10 @@
#include <spa/monitor/device.h>
#include <spa/utils/result.h>
/*!
* @brief
* @em parent
*/
struct _WpDevice
{
WpGlobalProxy parent;
@@ -33,18 +32,41 @@ struct _WpDevice
static void wp_device_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpDevice:
/*!
* @file device.c
*/
/*!
* @struct WpDevice
* @section device_section Pipewire Device
*
* The #WpDevice class allows accessing the properties and methods of a
* @brief The [WpDevice](@ref device_section) class allows accessing the properties and methods of a
* PipeWire device object (`struct pw_device`).
*
* A #WpDevice is constructed internally when a new device appears on the
* PipeWire registry and it is made available through the #WpObjectManager API.
* Alternatively, a #WpDevice can also be constructed using
* A [WpDevice](@ref device_section) is constructed internally when a new device appears on the
* PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
* Alternatively, a [WpDevice](@ref device_section) can also be constructed using
* wp_device_new_from_factory(), which creates a new device object
* on the remote PipeWire server by calling into a factory.
*
* @section spa_device_section WpSpaDevice
*
* @brief A [WpSpaDevice](@ref spa_device_section) allows running a `spa_device` object locally,
* loading the implementation from a SPA factory. This is useful to run device
* monitors inside the session manager and have control over creating the
* actual nodes that the `spa_device` requests to create.
*
* To enable the spa device, call wp_object_activate() requesting
* %WP_SPA_DEVICE_FEATURE_ENABLED.
*
* For actual devices (not device monitors) it also possible and desirable
* to export the device to PipeWire, which can be done by requesting
* %WP_PROXY_FEATURE_BOUND from wp_object_activate(). When exporting, the
* export should be done before enabling the device, by requesting both
* features at the same time.
*
*/
G_DEFINE_TYPE_WITH_CODE (WpDevice, wp_device, WP_TYPE_GLOBAL_PROXY,
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
wp_pw_object_mixin_object_interface_init)
@@ -158,14 +180,14 @@ wp_device_pw_object_mixin_priv_interface_init (
iface->set_param = wp_device_set_param;
}
/**
* wp_device_new_from_factory:
* @core: the wireplumber core
* @factory_name: the pipewire factory name to construct the device
* @properties: (nullable) (transfer full): the properties to pass to the factory
/*!
* @memberof WpDevice
* @param core: the wireplumber core
* @param factory_name: the pipewire factory name to construct the device
* @param properties: (nullable) (transfer full): the properties to pass to the factory
*
* Constructs a device on the PipeWire server by asking the remote factory
* @factory_name to create it.
* @brief Constructs a device on the PipeWire server by asking the remote factory
* @em factory_name to create it.
*
* Because of the nature of the PipeWire protocol, this operation completes
* asynchronously at some point in the future. In order to find out when
@@ -174,9 +196,10 @@ wp_device_pw_object_mixin_priv_interface_init (
* use on the server. If the device cannot be created, this activation operation
* will fail.
*
* Returns: (nullable) (transfer full): the new device or %NULL if the core
* @returns (nullable) (transfer full): the new device or %NULL if the core
* is not connected and therefore the device cannot be created
*/
WpDevice *
wp_device_new_from_factory (WpCore * core,
const gchar * factory_name, WpProperties * properties)
@@ -189,7 +212,24 @@ wp_device_new_from_factory (WpCore * core,
NULL);
}
/*!
* @memberof WpDevice
* @props @b properties
*
* @code
* "properties" WpProperties *
* @endcode
*
* @brief Flags : Read / Write / Construct Only
*
* @props @b spa-device-handle
*
* @code
* "spa-device-handle" gpointer *
* @endcode
*
* @brief Flags : Read / Write / Construct Only
*/
enum {
PROP_0,
PROP_SPA_DEVICE_HANDLE,
@@ -206,6 +246,57 @@ struct _WpSpaDevice
GPtrArray *managed_objs;
};
/*!
* @memberof WpDevice
* @signal @b create-object
*
* @code
* create_object_callback (WpSpaDevice * self,
* guint id,
* gchar * type,
* gchar * factory,
* WpProperties * properties,
* gpointer user_data)
* @endcode
*
* @brief This signal is emitted when the device is creating a managed object
* The handler is expected to actually construct the object using the requested SPA factory and
* with the given properties. The handler should then store the object with
* wp_spa_device_store_managed_object. The WpSpaDevice will later unref the reference stored by
* this function when the managed object is to be destroyed.
*
* Params:
* @arg self - the [WpSpaDevice](@ref spa_device_section)
* @arg id - the id of the managed object
* @arg type - the SPA type that the managed object should have
* @arg factory - the name of the SPA factory to use to construct the managed object
* @arg properties - additional properties that the managed object should have
* @arg user_data
*
* Flags: Run First
*
* @signal @b remove-object
*
* @code
* object_removed_callback (WpSpaDevice * self,
* guint id,
* gpointer user_data)
* @endcode
*
* @brief This signal is emitted when the device has deleted a managed object.
* The handler may optionally release additional resources associated with this object.
*
* It is not necessary to call wp_spa_device_store_managed_object() to remove the managed object,
* as this is done internally after this signal is fired.
*
* Params:
* @arg self - the [WpSpaDevice](@ref spa_device_section)
* @arg id - the id of the managed object
* @arg user_data
*
* Flags: Run First
*
*/
enum
{
SIGNAL_CREATE_OBJECT,
@@ -215,23 +306,6 @@ enum
static guint spa_device_signals[SPA_DEVICE_LAST_SIGNAL] = { 0 };
/**
* WpSpaDevice:
*
* A #WpSpaDevice allows running a `spa_device` object locally,
* loading the implementation from a SPA factory. This is useful to run device
* monitors inside the session manager and have control over creating the
* actual nodes that the `spa_device` requests to create.
*
* To enable the spa device, call wp_object_activate() requesting
* %WP_SPA_DEVICE_FEATURE_ENABLED.
*
* For actual devices (not device monitors) it also possible and desirable
* to export the device to PipeWire, which can be done by requesting
* %WP_PROXY_FEATURE_BOUND from wp_object_activate(). When exporting, the
* export should be done before enabling the device, by requesting both
* features at the same time.
*/
G_DEFINE_TYPE (WpSpaDevice, wp_spa_device, WP_TYPE_PROXY)
static void
@@ -493,19 +567,19 @@ wp_spa_device_class_init (WpSpaDeviceClass * klass)
"Properties of the device", WP_TYPE_PROPERTIES,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
/**
/*
* WpSpaDevice::create-object:
* @self: the #WpSpaDevice
* @self: the [WpSpaDevice](@ref spa_device_section)
* @id: the id of the managed object
* @type: the SPA type that the managed object should have
* @factory: the name of the SPA factory to use to construct the managed object
* @properties: additional properties that the managed object should have
*
* This signal is emitted when the device is creating a managed object
* @brief This signal is emitted when the device is creating a managed object
* The handler is expected to actually construct the object using the
* requested SPA @factory and with the given @properties.
* requested SPA @em factory and with the given @em properties.
* The handler should then store the object with
* wp_spa_device_store_managed_object(). The #WpSpaDevice will later unref
* wp_spa_device_store_managed_object(). The [WpSpaDevice](@ref spa_device_section) will later unref
* the reference stored by this function when the managed object is to be
* destroyed.
*/
@@ -514,12 +588,12 @@ wp_spa_device_class_init (WpSpaDeviceClass * klass)
0, NULL, NULL, NULL, G_TYPE_NONE, 4, G_TYPE_UINT, G_TYPE_STRING,
G_TYPE_STRING, WP_TYPE_PROPERTIES);
/**
/*
* WpSpaDevice::object-removed:
* @self: the #WpSpaDevice
* @self: the [WpSpaDevice](@ref spa_device_section)
* @id: the id of the managed object that was removed
*
* This signal is emitted when the device has deleted a managed object.
* @brief This signal is emitted when the device has deleted a managed object.
* The handler may optionally release additional resources associated
* with this object.
*
@@ -532,14 +606,15 @@ wp_spa_device_class_init (WpSpaDeviceClass * klass)
0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_UINT);
}
/**
* wp_spa_device_new_wrap:
* @core: the wireplumber core
* @spa_device_handle: the spa device handle
* @properties: (nullable) (transfer full): additional properties of the device
/*!
* @memberof WpDevice
* @param core: the wireplumber core
* @param spa_device_handle: the spa device handle
* @param properties: (nullable) (transfer full): additional properties of the device
*
* Returns: (transfer full): A new #WpSpaDevice
* @returns (transfer full): A new [WpSpaDevice](@ref spa_device_section)
*/
WpSpaDevice *
wp_spa_device_new_wrap (WpCore * core, gpointer spa_device_handle,
WpProperties * properties)
@@ -552,24 +627,25 @@ wp_spa_device_new_wrap (WpCore * core, gpointer spa_device_handle,
NULL);
}
/**
* wp_spa_device_new_from_spa_factory:
* @core: the wireplumber core
* @factory_name: the name of the SPA factory
* @properties: (nullable) (transfer full): properties to be passed to device
/*!
* @memberof WpDevice
* @param core: the wireplumber core
* @param factory_name: the name of the SPA factory
* @param properties: (nullable) (transfer full): properties to be passed to device
* constructor
*
* Constructs a `SPA_TYPE_INTERFACE_Device` by loading the given SPA
* @factory_name.
* @brief Constructs a `SPA_TYPE_INTERFACE_Device` by loading the given SPA
* @em factory_name.
*
* To export this device to the PipeWire server, you need to call
* wp_object_activate() requesting %WP_PROXY_FEATURE_BOUND and
* wait for the operation to complete.
*
* Returns: (nullable) (transfer full): A new #WpSpaDevice wrapping the
* @returns (nullable) (transfer full): A new [WpSpaDevice](@ref spa_device_section) wrapping the
* device that was constructed by the factory, or %NULL if the factory
* does not exist or was unable to construct the device
*/
WpSpaDevice *
wp_spa_device_new_from_spa_factory (WpCore * core,
const gchar * factory_name, WpProperties * properties)
@@ -592,12 +668,13 @@ wp_spa_device_new_from_spa_factory (WpCore * core,
return wp_spa_device_new_wrap (core, handle, g_steal_pointer (&props));
}
/**
* wp_spa_device_get_properties:
* @self: the spa device
/*!
* @memberof WpDevice
* @param self: the spa device
*
* Returns: (transfer full): the device properties
* @returns (transfer full): the device properties
*/
WpProperties *
wp_spa_device_get_properties (WpSpaDevice * self)
{
@@ -605,13 +682,14 @@ wp_spa_device_get_properties (WpSpaDevice * self)
return wp_properties_ref (self->properties);
}
/**
* wp_spa_device_get_managed_object:
* @self: the spa device
* @id: the (device-internal) id of the object to get
/*!
* @memberof WpDevice
* @param self: the spa device
* @param id: the (device-internal) id of the object to get
*
* Returns: (transfer full): the managed object associated with @id
* @returns (transfer full): the managed object associated with @em id
*/
GObject *
wp_spa_device_get_managed_object (WpSpaDevice * self, guint id)
{
@@ -622,13 +700,14 @@ wp_spa_device_get_managed_object (WpSpaDevice * self, guint id)
return ret ? g_object_ref (ret) : ret;
}
/**
* wp_spa_device_store_managed_object:
* @self: the spa device
* @id: the (device-internal) id of the object
* @object: (transfer full) (nullable): the object to store or %NULL to remove
* the managed object associated with @id
/*!
* @memberof WpDevice
* @param self: the spa device
* @param id: the (device-internal) id of the object
* @param object: (transfer full) (nullable): the object to store or %NULL to remove
* the managed object associated with @em id
*/
void
wp_spa_device_store_managed_object (WpSpaDevice * self, guint id,
GObject * object)
@@ -638,7 +717,7 @@ wp_spa_device_store_managed_object (WpSpaDevice * self, guint id,
if (id >= self->managed_objs->len)
g_ptr_array_set_size (self->managed_objs, id + 1);
/* replace the item at @id; g_ptr_array_insert is tempting to use here
/* replace the item at @em id; g_ptr_array_insert is tempting to use here
instead, but it's wrong because it will not remove the previous item */
gpointer *ptr = &g_ptr_array_index (self->managed_objs, id);
if (*ptr)

37
lib/wp/device.h
View File

@@ -15,10 +15,17 @@ G_BEGIN_DECLS
/* WpDevice */
/**
* WP_TYPE_DEVICE:
/*!
* @memberof WpDevice
*
* @brief The [WpDevice](@ref device_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_DEVICE (wp_device_get_type ())
* @endcode
*
* The #WpDevice #GType
*/
#define WP_TYPE_DEVICE (wp_device_get_type ())
WP_API
@@ -30,20 +37,30 @@ WpDevice * wp_device_new_from_factory (WpCore * core,
/* WpSpaDevice */
/**
* WpSpaDeviceFeatures:
* @WP_SPA_DEVICE_FEATURE_ENABLED: enables a device
/*!
* @memberof WpDevice
*
* Flags to be used as #WpObjectFeatures for #WpSpaDevice
* @brief
* @arg WP_SPA_DEVICE_FEATURE_ENABLED: enables a device
*
* Flags to be used as [WpObjectFeatures](@ref object_features_section) for
* [WpSpaDevice](@ref spa_device_section)
*/
typedef enum { /*< flags >*/
WP_SPA_DEVICE_FEATURE_ENABLED = (WP_PROXY_FEATURE_CUSTOM_START << 0),
} WpSpaDeviceFeatures;
/**
* WP_TYPE_SPA_DEVICE:
/*!
* @memberof WpDevice
*
* @brief The [WpSpaDevice](@ref spa_device_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SPA_DEVICE (wp_spa_device_get_type ())
* @endcode
*
* The #WpSpaDevice #GType
*/
#define WP_TYPE_SPA_DEVICE (wp_spa_device_get_type ())
WP_API

133
lib/wp/endpoint.c
View File

@@ -6,11 +6,6 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: endpoint
* @title: PIpeWire Endpoint
*/
#define G_LOG_DOMAIN "wp-endpoint"
#include "endpoint.h"
@@ -27,6 +22,40 @@
#include <pipewire/extensions/session-manager/introspect-funcs.h>
#include <spa/utils/result.h>
/*!
* @memberof WpEndpoint
*
* @props @b direction
*
* @code
* "direction" WpDirection *
* @endcode
*
* @brief The direction of the endpoint
*
* Flags : Read
*
* @props @b media-class
*
* @code
* "media-class" gchar *
* @endcode
*
* @brief The media class of the endpoint (ex. "Audio/Sink")
*
* Flags : Read
*
* @props @b name
*
* @code
* "name" gchar *
* @endcode
*
* @brief The name of the endpoint
*
* Flags : Read
*
*/
enum {
PROP_NAME = WP_PW_OBJECT_MIXIN_PROP_CUSTOM_START,
PROP_MEDIA_CLASS,
@@ -42,16 +71,23 @@ struct _WpEndpointPrivate
static void wp_endpoint_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpEndpoint:
*
* The #WpEndpoint class allows accessing the properties and methods of a
* PipeWire endpoint object (`struct pw_endpoint` from the session-manager
* extension).
*
* A #WpEndpoint is constructed internally when a new endpoint appears on the
* PipeWire registry and it is made available through the #WpObjectManager API.
/*!
* @file endpoint.c
*/
/*!
* @struct WpEndpoint
*
* @section endpoint_section Pipewire Endpoint
*
* @brief The [WpEndpoint](@ref endpoint_section) class allows accessing the properties and methods of a
* PipeWire endpoint object (`struct pw_endpoint` from the session-manager extension).
*
* A [WpEndpoint](@ref endpoint_section) is constructed internally when a new endpoint appears on the
* PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
*
*/
G_DEFINE_TYPE_WITH_CODE (WpEndpoint, wp_endpoint, WP_TYPE_GLOBAL_PROXY,
G_ADD_PRIVATE (WpEndpoint)
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
@@ -168,28 +204,28 @@ wp_endpoint_class_init (WpEndpointClass * klass)
wp_pw_object_mixin_class_override_properties (object_class);
/**
/*
* WpEndpoint:name:
*
* The name of the endpoint
* @brief The name of the endpoint
*/
g_object_class_install_property (object_class, PROP_NAME,
g_param_spec_string ("name", "name", "name", NULL,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
/*
* WpEndpoint:media-class:
*
* The media class of the endpoint (ex. "Audio/Sink")
* @brief The media class of the endpoint (ex. "Audio/Sink")
*/
g_object_class_install_property (object_class, PROP_MEDIA_CLASS,
g_param_spec_string ("media-class", "media-class", "media-class", NULL,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
/*
* WpEndpoint:direction:
*
* The direction of the endpoint
* @brief The direction of the endpoint
*/
g_object_class_install_property (object_class, PROP_DIRECTION,
g_param_spec_enum ("direction", "direction", "direction",
@@ -223,14 +259,15 @@ wp_endpoint_pw_object_mixin_priv_interface_init (
iface->set_param = wp_endpoint_set_param;
}
/**
* wp_endpoint_get_name:
* @self: the endpoint
/*!
* @memberof WpEndpoint
* @param self: the endpoint
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: the name of the endpoint
* @returns the name of the endpoint
*/
const gchar *
wp_endpoint_get_name (WpEndpoint * self)
{
@@ -242,14 +279,15 @@ wp_endpoint_get_name (WpEndpoint * self)
return ((struct pw_endpoint_info *) d->info)->name;
}
/**
* wp_endpoint_get_media_class:
* @self: the endpoint
/*!
* @memberof WpEndpoint
* @param self: the endpoint
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: the media class of the endpoint (ex. "Audio/Sink")
* @returns the media class of the endpoint (ex. "Audio/Sink")
*/
const gchar *
wp_endpoint_get_media_class (WpEndpoint * self)
{
@@ -261,14 +299,15 @@ wp_endpoint_get_media_class (WpEndpoint * self)
return ((struct pw_endpoint_info *) d->info)->media_class;
}
/**
* wp_endpoint_get_direction:
* @self: the endpoint
/*!
* @memberof WpEndpoint
* @param self: the endpoint
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: the direction of this endpoint
* @returns the direction of this endpoint
*/
WpDirection
wp_endpoint_get_direction (WpEndpoint * self)
{
@@ -287,6 +326,22 @@ enum {
IMPL_PROP_ITEM,
};
/*!
* @struct WpImplEndpoint
* @memberof WpEndpoint
*
* @section impl_endpoint_section WpImplEndpoint
*
* @section impl_endpoint_class_props_section Properties
*
* @b item
*
* @code
* “item” WpSiEndpoint *
* @endcode
*
* @brief Flags : Read / Write / Construct Only
*/
struct _WpImplEndpoint
{
WpEndpoint parent;
@@ -677,6 +732,14 @@ wp_endpoint_impl_pw_object_mixin_priv_interface_init (
iface->emit_param = wp_impl_endpoint_emit_param;
}
/*!
* @memberof WpEndpoint
* @param core: the core
* @param item: the endpoint
*
* Returns: (transfer full): a new [WpImplEndpoint](@ref impl_endpoint_section)
*/
WpImplEndpoint *
wp_impl_endpoint_new (WpCore * core, WpSiEndpoint * item)
{

31
lib/wp/endpoint.h
View File

@@ -17,15 +17,28 @@
G_BEGIN_DECLS
/**
* WP_TYPE_ENDPOINT:
/*!
* @memberof WpEndpoint
*
* @brief The [WpEndpoint](@ref endpoint_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_ENDPOINT (wp_endpoint_get_type ())
* @endcode
*
* The #WpEndpoint #GType
*/
#define WP_TYPE_ENDPOINT (wp_endpoint_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpEndpoint, wp_endpoint, WP, ENDPOINT, WpGlobalProxy)
/*!
* @memberof WpEndpoint
*
* @brief
* @em parent_class
*/
struct _WpEndpointClass
{
WpGlobalProxyClass parent_class;
@@ -40,10 +53,16 @@ const gchar * wp_endpoint_get_media_class (WpEndpoint * self);
WP_API
WpDirection wp_endpoint_get_direction (WpEndpoint * self);
/**
* WP_TYPE_IMPL_ENDPOINT:
/*!
* @memberof WpEndpoint
*
* @brief The [WpImplEndpoint](@ref impl_endpoint_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
* @code
* #define WP_TYPE_IMPL_ENDPOINT (wp_impl_endpoint_get_type ())
* @endcode
*
* The #WpImplEndpoint #GType
*/
#define WP_TYPE_IMPL_ENDPOINT (wp_impl_endpoint_get_type ())
WP_API

15
lib/wp/error.c
View File

@@ -6,16 +6,17 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: error
* @title: Error codes
*
* Error domain and codes for #GError
*/
#include "error.h"
/**
* wp_domain_library_quark:
*
* @file error.c
*
* @section error_section Error codes
*
* Error domain and codes for
* <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a>
*/
G_DEFINE_QUARK (wireplumber-library, wp_domain_library);

51
lib/wp/error.h
View File

@@ -17,21 +17,58 @@ G_BEGIN_DECLS
/**
* WP_DOMAIN_LIBRARY:
*
* A #GError domain for errors that occurred within the context of the
* @file error.c
* @struct ErrorCodes
* @section error_section Error codes
*
* @brief Error domain and codes for <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a>
*
* @b wp_domain_library_quark
*
* @code
* GQuark wp_domain_library_quark ()
* @endcode
*
* @subsection error_enum_subsection Enumerations
*
* @subsubsection error_enum_subsubsection WpLibraryErrorEnum:
*
* @brief Error codes that can appear in a
* <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">GError</a>
* when the error domain is [WP_DOMAIN_LIBRARY](@ref error_constants_subsection)
*
* @b Members:
*
* @arg `WP_LIBRARY_ERROR_INVARIANT (0) – an invariant check failed; this most likely indicates a programming error`
* @arg `WP_LIBRARY_ERROR_INVALID_ARGUMENT (1) – an unexpected/invalid argument was given`
* @arg `WP_LIBRARY_ERROR_OPERATION_FAILED (2) – an operation failed`
*
* @subsection error_constants_subsection Constants
*
* @b WP_DOMAIN_LIBRARY:
*
* A <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a> domain for errors that occurred within the context of the
* WirePlumber library.
*
* @code
* #define WP_DOMAIN_LIBRARY (wp_domain_library_quark ())
* @endcode
*/
#define WP_DOMAIN_LIBRARY (wp_domain_library_quark ())
WP_API
GQuark wp_domain_library_quark (void);
/**
* WpLibraryErrorEnum:
* @WP_LIBRARY_ERROR_INVARIANT: an invariant check failed; this most likely
/*!
* @em WP_LIBRARY_ERROR_INVARIANT: an invariant check failed; this most likely
* indicates a programming error
* @WP_LIBRARY_ERROR_INVALID_ARGUMENT: an unexpected/invalid argument was given
* @WP_LIBRARY_ERROR_OPERATION_FAILED: an operation failed
* @em WP_LIBRARY_ERROR_INVALID_ARGUMENT: an unexpected/invalid argument was given
* @em WP_LIBRARY_ERROR_OPERATION_FAILED: an operation failed
*
* Error codes that can appear in a #GError when the error domain
* Error codes that can appear in a
* <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a> when the error domain
* is %WP_DOMAIN_LIBRARY
*/
typedef enum {

93
lib/wp/global-proxy.c
View File

@@ -6,11 +6,6 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: global-proxy
* @title: PipeWire Global Object Proxy
*/
#define G_LOG_DOMAIN "wp-global-proxy"
#include "global-proxy.h"
@@ -26,6 +21,34 @@ struct _WpGlobalProxyPrivate
WpProperties *properties;
};
/*!
* @memberof WpGlobalProxy
*
* @props @b global
*
* @code
* “global” object *
* @endcode
*
* @brief Flags : Read / Write / Construct Only
*
* @props @b global-properties
*
* @code
* “global-properties” [WpProperties](@ref properties_section) *
* @endcode
*
* @brief Flags : Read
*
* @props @b permissions
*
* @code
* “permissions” <a href="https://developer.gnome.org/glib/stable/glib-Basic-Types.html#guint">guint</a>
* @endcode
*
* @brief Flags : Read
*
*/
enum {
PROP_0,
PROP_GLOBAL,
@@ -34,12 +57,19 @@ enum {
PROP_PERMISSIONS,
};
/**
* WpGlobalProxy:
*
* A proxy that represents a PipeWire global object, i.e. an object that is
* made available through the PipeWire registry.
/*!
* @file global-proxy.c
*/
/*!
* @struct WpGlobalProxy
* @section global_proxy_section Global Proxy
*
* @brief A proxy that represents a PipeWire global object, i.e. an object that is
* made available through the PipeWire registry.
*
*/
G_DEFINE_TYPE_WITH_PRIVATE (WpGlobalProxy, wp_global_proxy, WP_TYPE_PROXY)
static void
@@ -134,7 +164,7 @@ wp_global_proxy_activate_get_next_step (WpObject * object,
WpObjectFeatures missing)
{
/* we only support BOUND, so this is the only
feature that can be in @missing */
feature that can be in @em missing */
g_return_val_if_fail (missing == WP_PROXY_FEATURE_BOUND,
WP_TRANSITION_STEP_ERROR);
@@ -285,17 +315,19 @@ wp_global_proxy_class_init (WpGlobalProxyClass * klass)
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
}
/**
* wp_global_proxy_request_destroy:
* @self: the pipewire global
/*!
* @memberof WpGlobalProxy
* @param self: the pipewire global
*
* Requests the PipeWire server to destroy the object represented by this proxy.
* @brief Requests the PipeWire server to destroy the object represented by this proxy.
* If the server allows it, the object will be destroyed and the
* WpProxy::pw-proxy-destroyed signal will be emitted. If the server does
* not allow it, nothing will happen.
*
* This is mostly useful for destroying #WpLink and #WpEndpointLink objects.
* This is mostly useful for destroying [WpLink](@ref link_section) and
* [WpEndpointLink](@ref endpoint_link_section) objects.
*/
void
wp_global_proxy_request_destroy (WpGlobalProxy * self)
{
@@ -311,12 +343,13 @@ wp_global_proxy_request_destroy (WpGlobalProxy * self)
}
}
/**
* wp_global_proxy_get_permissions:
* @self: the pipewire global
/*!
* @memberof WpGlobalProxy
* @param self: the pipewire global
*
* Returns: the permissions that wireplumber has on this object
* @returns the permissions that wireplumber has on this object
*/
guint32
wp_global_proxy_get_permissions (WpGlobalProxy * self)
{
@@ -328,13 +361,14 @@ wp_global_proxy_get_permissions (WpGlobalProxy * self)
return priv->global ? priv->global->permissions : PW_PERM_ALL;
}
/**
* wp_global_proxy_get_global_properties:
* @self: the pipewire global
/*!
* @memberof WpGlobalProxy
* @param self: the pipewire global
*
* Returns: (transfer full): the global (immutable) properties of this
* @returns (transfer full): the global (immutable) properties of this
* pipewire object
*/
WpProperties *
wp_global_proxy_get_global_properties (WpGlobalProxy * self)
{
@@ -348,18 +382,19 @@ wp_global_proxy_get_global_properties (WpGlobalProxy * self)
return NULL;
}
/**
* wp_global_proxy_bind:
* @self: the pipewire global
/*!
* @memberof WpGlobalProxy
* @param self: the pipewire global
*
* Binds to the global and creates the underlying `pw_proxy`. This may only
* @brief Binds to the global and creates the underlying `pw_proxy`. This may only
* be called if there is no `pw_proxy` associated with this object yet.
*
* This is mostly meant to be called internally. It will create the `pw_proxy`
* and will activate the %WP_PROXY_FEATURE_BOUND feature.
*
* Returns: %TRUE on success, %FALSE if there is no global to bind to
* @returns %TRUE on success, %FALSE if there is no global to bind to
*/
gboolean
wp_global_proxy_bind (WpGlobalProxy * self)
{

19
lib/wp/global-proxy.h
View File

@@ -14,16 +14,29 @@
G_BEGIN_DECLS
/**
* WP_TYPE_GLOBAL_PROXY:
/*!
* @memberof WpGlobalProxy
*
* @brief The [WpGlobalProxy](@ref global_proxy_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_GLOBAL_PROXY (wp_global_proxy_get_type ())
* @endcode
*
* The #WpGlobalProxy #GType
*/
#define WP_TYPE_GLOBAL_PROXY (wp_global_proxy_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpGlobalProxy, wp_global_proxy,
WP, GLOBAL_PROXY, WpProxy)
/*!
* @memberof WpGlobalProxy
*
* @brief
* @em parent_class
*/
struct _WpGlobalProxyClass
{
WpProxyClass parent_class;

118
lib/wp/iterator.c
View File

@@ -5,10 +5,8 @@
*
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: iterator
* @title: Iterator
/*!
* @file iterator.c
*/
#define G_LOG_DOMAIN "wp-iterator"
@@ -16,6 +14,11 @@
#include "iterator.h"
#include <spa/utils/defs.h>
/*!
* @struct WpIterator
* @section iterator_section Iterator
*
*/
struct _WpIterator
{
const WpIteratorMethods *methods;
@@ -63,19 +66,20 @@ wp_iterator_default_foreach (WpIterator *self, WpIteratorForeachFunc func,
return wp_iterator_fold (self, foreach_fold_func, NULL, &d);
}
/**
* wp_iterator_new:
* @methods: method implementations for the new iterator
* @user_size: size of the user_data structure to be allocated
/*!
* @memberof WpIterator
* @param methods: method implementations for the new iterator
* @param user_size: size of the user_data structure to be allocated
*
* Constructs an iterator that uses the provided @methods to implement its API.
* The WpIterator structure is internally allocated with @user_size additional
* @brief Constructs an iterator that uses the provided @em methods to implement its API.
* The WpIterator structure is internally allocated with @em user_size additional
* space at the end. A pointer to this space can be retrieved with
* wp_iterator_get_user_data() and is available for implementation-specific
* storage.
*
* Returns: (transfer full): a new custom iterator
* @returns (transfer full): a new custom iterator
*/
WpIterator *
wp_iterator_new (const WpIteratorMethods *methods, size_t user_size)
{
@@ -91,26 +95,28 @@ wp_iterator_new (const WpIteratorMethods *methods, size_t user_size)
return self;
}
/**
* wp_iterator_get_user_data:
* @self: an iterator object
/*!
* @memberof WpIterator
* @param self: an iterator object
*
* Note: this only for use by implementations of WpIterator
*
* Returns: a pointer to the implementation-specific storage area
* @returns a pointer to the implementation-specific storage area
*/
gpointer
wp_iterator_get_user_data (WpIterator *self)
{
return self->user_data;
}
/**
* wp_iterator_ref:
* @self: an iterator object
/*!
* @memberof WpIterator
* @param self: an iterator object
*
* Returns: (transfer full): @self with an additional reference count on it
* @returns (transfer full): @em self with an additional reference count on it
*/
WpIterator *
wp_iterator_ref (WpIterator *self)
{
@@ -124,25 +130,27 @@ wp_iterator_free (WpIterator *self)
self->methods->finalize (self);
}
/**
* wp_iterator_unref:
* @self: (transfer full): an iterator object
/*!
* @memberof WpIterator
* @param self: (transfer full): an iterator object
*
* 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_iterator_unref (WpIterator *self)
{
g_rc_box_release_full (self, (GDestroyNotify) wp_iterator_free);
}
/**
* wp_iterator_reset:
* @self: the iterator
/*!
* @memberof WpIterator
* @param self: the iterator
*
* Resets the iterator so we can iterate again from the beginning.
* @brief Resets the iterator so we can iterate again from the beginning.
*/
void
wp_iterator_reset (WpIterator *self)
{
@@ -152,16 +160,17 @@ wp_iterator_reset (WpIterator *self)
self->methods->reset (self);
}
/**
* wp_iterator_next:
* @self: the iterator
* @item: (out): the next item of the iterator
/*!
* @memberof WpIterator
* @param self: the iterator
* @param item: (out): the next item of the iterator
*
* Gets the next item of the iterator.
* @brief Gets the next item of the iterator.
*
* Returns: TRUE if next iterator was obtained, FALSE when the iterator has no
* @returns TRUE if next iterator was obtained, FALSE when the iterator has no
* more items to iterate through.
*/
gboolean
wp_iterator_next (WpIterator *self, GValue *item)
{
@@ -171,17 +180,19 @@ wp_iterator_next (WpIterator *self, GValue *item)
return self->methods->next (self, item);
}
/**
* wp_iterator_fold:
* @self: the iterator
* @func: (scope call): the fold function
* @ret: (inout): the accumulator data
* @data: (closure): the user data
/*!
* @memberof WpIterator
* @param self: the iterator
* @param func: (scope call): the fold function
* @param ret: (inout): the accumulator data
* @param data: (closure): the user data
*
* Iterates over all items of the iterator calling a function.
* @brief Iterates over all items of the iterator calling a function.
*
* @returns TRUE if all the items were processed, FALSE otherwise.
*
* Returns: TRUE if all the items were processed, FALSE otherwise.
*/
gboolean
wp_iterator_fold (WpIterator *self, WpIteratorFoldFunc func, GValue *ret,
gpointer data)
@@ -194,16 +205,18 @@ wp_iterator_fold (WpIterator *self, WpIteratorFoldFunc func, GValue *ret,
return wp_iterator_default_fold (self, func, ret, data);
}
/**
* wp_iterator_foreach:
* @self: the iterator
* @func: (scope call): the foreach function
* @data: (closure): the user data
/*!
* @memberof WpIterator
* @param self: the iterator
* @param func: (scope call): the foreach function
* @param data: (closure): the user data
*
* Fold a function over the items of the iterator.
* @brief Fold a function over the items of the iterator.
*
* @returns TRUE if all the items were processed, FALSE otherwise.
*
* Returns: TRUE if all the items were processed, FALSE otherwise.
*/
gboolean
wp_iterator_foreach (WpIterator *self, WpIteratorForeachFunc func,
gpointer data)
@@ -282,13 +295,14 @@ static const WpIteratorMethods ptr_array_iterator_methods = {
.finalize = ptr_array_iterator_finalize,
};
/**
* wp_iterator_new_ptr_array:
* @items: (transfer full): the items to iterate over
/*!
* @memberof WpIterator
* @items: (element-type utf8) (transfer full): the items to iterate over
* @item_type: the type of each item
*
* Returns: (transfer full): a new iterator that iterates over @items
* @returns (transfer full): a new iterator that iterates over @em items
*/
WpIterator *
wp_iterator_new_ptr_array (GPtrArray * items, GType item_type)
{

41
lib/wp/iterator.h
View File

@@ -14,32 +14,43 @@
G_BEGIN_DECLS
/**
* WpIteratorFoldFunc:
* @item: the item to fold
* @ret: the value collecting the result
* @data: data passed to #wp_iterator_fold
/*!
* @fn WpIteratorFoldFunc:
* @memberof WpIterator
*
* A function to be passed to #wp_iterator_fold.
* @param item: the item to fold
* @param ret: the value collecting the result
* @param data: data passed to @b wp_iterator_fold
*
* Returns: TRUE if the fold should continue, FALSE if it should stop.
* A function to be passed to `wp_iterator_fold()`.
*
* @returns TRUE if the fold should continue, FALSE if it should stop.
*/
typedef gboolean (*WpIteratorFoldFunc) (const GValue *item, GValue *ret,
gpointer data);
/**
* WpIteratorForeachFunc:
* @item: the item
* @data: the data passed to #wp_iterator_foreach
/*!
* @fn WpIteratorForeachFunc:
* @memberof WpIterator
*
* A function that is called by #wp_iterator_foreach for every element.
* @param item: the item
* @param data: the data passed to @b wp_iterator_foreach
*
* A function that is called by `wp_iterator_foreach()`.
*/
typedef void (*WpIteratorForeachFunc) (const GValue *item, gpointer data);
/**
* WP_TYPE_ITERATOR:
/*!
* memberof WpIterator
*
* @brief The [WpIterator](@ref iterator_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_ITERATOR (wp_iterator_get_type ())
* @endcode
*
* The #WpIterator #GType
*/
#define WP_TYPE_ITERATOR (wp_iterator_get_type ())
WP_API

61
lib/wp/link.c
View File

@@ -6,16 +6,18 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: link
* @title: PipeWire Link
/*!
* @file link.c
*/
#define G_LOG_DOMAIN "wp-link"
#include "link.h"
#include "private/pipewire-object-mixin.h"
/*!
* @brief
* @em parent
*/
struct _WpLink
{
WpGlobalProxy parent;
@@ -24,18 +26,21 @@ struct _WpLink
static void wp_link_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpLink:
/*!
* @struct WpLink
*
* The #WpLink class allows accessing the properties and methods of a
* @section link_section Pipewire Link
*
* @brief The [WpLink](@ref link_section) class allows accessing the properties and methods of a
* PipeWire link object (`struct pw_link`).
*
* A #WpLink is constructed internally when a new link appears on the
* PipeWire registry and it is made available through the #WpObjectManager API.
* Alternatively, a #WpLink can also be constructed using
* A [WpLink](@ref link_section) is constructed internally when a new link appears on the
* PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
* Alternatively, a [WpLink](@ref link_section) can also be constructed using
* wp_link_new_from_factory(), which creates a new link object
* on the remote PipeWire server by calling into a factory.
*/
G_DEFINE_TYPE_WITH_CODE (WpLink, wp_link, WP_TYPE_GLOBAL_PROXY,
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
wp_pw_object_mixin_object_interface_init)
@@ -117,14 +122,14 @@ wp_link_pw_object_mixin_priv_interface_init (
wp_pw_object_mixin_priv_interface_info_init_no_params (iface, link, LINK);
}
/**
* wp_link_new_from_factory:
* @core: the wireplumber core
* @factory_name: the pipewire factory name to construct the link
* @properties: (nullable) (transfer full): the properties to pass to the factory
/*!
* @memberof WpLink
* @param core: the wireplumber core
* @param factory_name: the pipewire factory name to construct the link
* @param properties: (nullable) (transfer full): the properties to pass to the factory
*
* Constructs a link on the PipeWire server by asking the remote factory
* @factory_name to create it.
* @brief Constructs a link on the PipeWire server by asking the remote factory
* @em factory_name to create it.
*
* Because of the nature of the PipeWire protocol, this operation completes
* asynchronously at some point in the future. In order to find out when
@@ -133,9 +138,10 @@ wp_link_pw_object_mixin_priv_interface_init (
* use on the server. If the link cannot be created, this activation operation
* will fail.
*
* Returns: (nullable) (transfer full): the new link or %NULL if the core
* @returns (nullable) (transfer full): the new link or %NULL if the core
* is not connected and therefore the link cannot be created
*/
WpLink *
wp_link_new_from_factory (WpCore * core,
const gchar * factory_name, WpProperties * properties)
@@ -148,18 +154,19 @@ wp_link_new_from_factory (WpCore * core,
NULL);
}
/**
* wp_link_get_linked_object_ids:
* @self: the link
* @output_node: (out) (optional): the bound id of the output (source) node
* @output_port: (out) (optional): the bound id of the output (source) port
* @input_node: (out) (optional): the bound id of the input (sink) node
* @input_port: (out) (optional): the bound id of the input (sink) port
/*!
* @memberof WpLink
* @param self: the link
* @param output_node: (out) (optional): the bound id of the output (source) node
* @param output_port: (out) (optional): the bound id of the output (source) port
* @param input_node: (out) (optional): the bound id of the input (sink) node
* @param input_port: (out) (optional): the bound id of the input (sink) port
*
* Retrieves the ids of the objects that are linked by this link
* @brief Retrieves the ids of the objects that are linked by this link
*
* Note: Using this method requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @note Using this method requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*/
void
wp_link_get_linked_object_ids (WpLink * self,
guint32 * output_node, guint32 * output_port,

13
lib/wp/link.h
View File

@@ -13,10 +13,17 @@
G_BEGIN_DECLS
/**
* WP_TYPE_LINK:
/*!
* @memberof WPLink
*
* @brief The [WpLink](@ref link_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_LINK (wp_link_get_type ())
* @endcode
*
* The #WpLink #GType
*/
#define WP_TYPE_LINK (wp_link_get_type ())
WP_API

17
lib/wp/log.c
View File

@@ -6,9 +6,12 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: log
* @title: Debug Logging
/*!
* @file debug.c
*/
/*!
* WpDebug:
*/
#include "log.h"
@@ -289,7 +292,9 @@ wp_log_set_level (const gchar * level_str)
/**
* wp_log_writer_default:
*
* WirePlumber's #GLogWriterFunc
* WirePlumber's
* <a href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#GLogWriterFunc">
* GLogWriterFunc</a>
*
* This is installed automatically when you call wp_init() with
* %WP_INIT_SET_GLIB_LOG set in the flags
@@ -475,7 +480,9 @@ static struct spa_log wp_spa_log = {
* wp_spa_log_get_instance:
*
* Returns: WirePlumber's instance of `spa_log`, which can be used to redirect
* PipeWire's log messages to the currently installed #GLogWriterFunc.
* PipeWire's log messages to the currently installed
* <a href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#GLogWriterFunc">
* GLogWriterFunc</a>.
* This is installed automatically when you call wp_init() with
* %WP_INIT_SET_PW_LOG set in the flags
*/

156
lib/wp/metadata.c
View File

@@ -6,11 +6,9 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: metadata
* @title: PipeWire Metadata
/*!
* @file metadata.c
*/
#define G_LOG_DOMAIN "wp-metadata"
#include "metadata.h"
@@ -22,6 +20,32 @@
#include <pipewire/pipewire.h>
#include <pipewire/extensions/metadata.h>
/*!
* @memberof WpMetadata
*
* @signal @b changed
*
* @code
* changed_callback (WpMetadata * self,
* guint object,
* gchar * p0,
* gchar * p1,
* gchar * p2,
* gpointer user_data)
* @endcode
*
* Parameters:
*
* @arg `self`
* @arg `object`
* @arg `p0`
* @arg `p1`
* @arg `p2`
* @arg `user_data`
*
* Flags: Run Last
*
*/
enum {
SIGNAL_CHANGED,
N_SIGNALS,
@@ -101,7 +125,14 @@ clear_items (struct pw_array * metadata)
pw_array_reset (metadata);
}
/* WpMetadata */
/*!
* @struct WpMetadata
* @section metadata_section Metadata
*
* @brief The [WpMetadata](@ref metadata_section) class allows accessing the properties and methods of
* PipeWire metadata object (`struct pw_metadata`).
*
*/
typedef struct _WpMetadataPrivate WpMetadataPrivate;
struct _WpMetadataPrivate
@@ -111,12 +142,6 @@ struct _WpMetadataPrivate
struct pw_array metadata;
};
/**
* WpMetadata:
*
* The #WpMetadata class allows accessing the properties and methods of
* PipeWire metadata object (`struct pw_metadata`).
*/
G_DEFINE_TYPE_WITH_PRIVATE (WpMetadata, wp_metadata, WP_TYPE_GLOBAL_PROXY)
static void
@@ -364,12 +389,12 @@ static const WpIteratorMethods metadata_iterator_methods = {
.finalize = metadata_iterator_finalize,
};
/**
* wp_metadata_new_iterator:
* @self: a metadata object
* @subject: the metadata subject id, or -1 (PW_ID_ANY)
/*!
* @memberof WpMetadata
* @param self: a metadata object
* @param subject: the metadata subject id, or -1 (PW_ID_ANY)
*
* Iterates over metadata items that matches the given @subject. If no
* @brief Iterates over metadata items that matches the given @em subject. If no
* constraints are specified, the returned iterator iterates over all the
* stored metadata.
*
@@ -377,10 +402,11 @@ static const WpIteratorMethods metadata_iterator_methods = {
* with wp_metadata_set(), this cache will be updated on the next round-trip
* with the pipewire server.
*
* Returns: (transfer full): an iterator that iterates over the found metadata.
* @returns (transfer full): an iterator that iterates over the found metadata.
* Use wp_metadata_iterator_item_extract() to parse the items returned by
* this iterator.
*/
WpIterator *
wp_metadata_new_iterator (WpMetadata * self, guint32 subject)
{
@@ -400,17 +426,23 @@ wp_metadata_new_iterator (WpMetadata * self, guint32 subject)
return g_steal_pointer (&it);
}
/**
* wp_metadata_iterator_item_extract:
* @item: a #GValue that was returned from the #WpIterator of wp_metadata_find()
* @subject: (out)(optional): the subject id of the current item
* @key: (out)(optional)(transfer none): the key of the current item
* @type: (out)(optional)(transfer none): the type of the current item
* @value: (out)(optional)(transfer none): the value of the current item
/*!
* @memberof WpMetadata
* @param item: a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue-struct">
* GValue</a> that was returned from the [WpIterator](@ref iterator_section) of wp_metadata_find()
*
* Extracts the metadata subject, key, type and value out of a #GValue that was
* returned from the #WpIterator of wp_metadata_find()
* @brief
* @param subject: (out)(optional): the subject id of the current item
* @param key: (out)(optional)(transfer none): the key of the current item
* @param type: (out)(optional)(transfer none): the type of the current item
* @param value: (out)(optional)(transfer none): the value of the current item
*
* Extracts the metadata subject, key, type and value out of a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue-struct">
* GValue</a> that was returned from the [WpIterator](@ref iterator_section) of wp_metadata_find()
*/
void
wp_metadata_iterator_item_extract (const GValue * item, guint32 * subject,
const gchar ** key, const gchar ** type, const gchar ** value)
@@ -427,17 +459,18 @@ wp_metadata_iterator_item_extract (const GValue * item, guint32 * subject,
*value = i->value;
}
/**
* wp_metadata_find:
* @self: a metadata object
* @subject: the metadata subject id
* @key: the metadata key name
* @type: (out)(optional): the metadata type name
/*!
* @memberof WpMetadata
* @param self: a metadata object
* @param subject: the metadata subject id
* @param key: the metadata key name
* @param type: (out)(optional): the metadata type name
*
* Finds the metadata value given its @subject and &key.
* @brief Finds the metadata value given its @em subject and &key.
*
* Returns: the metadata string value, or NULL if not found.
* @returns the metadata string value, or NULL if not found.
*/
const gchar *
wp_metadata_find (WpMetadata * self, guint32 subject, const gchar * key,
const gchar ** type)
@@ -457,19 +490,20 @@ wp_metadata_find (WpMetadata * self, guint32 subject, const gchar * key,
return NULL;
}
/**
* wp_metadata_set:
* @self: the metadata object
* @subject: the subject id for which this metadata property is being set
* @key: (nullable): the key to set, or %NULL to remove all metadata for
* @subject
* @type: (nullable): the type of the value; %NULL is synonymous to "string"
* @value: (nullable): the value to set, or %NULL to unset the given @key
/*!
* @memberof WpMetadata
* @param self: the metadata object
* @param subject: the subject id for which this metadata property is being set
* @param key: (nullable): the key to set, or %NULL to remove all metadata for
* @em subject
* @param type: (nullable): the type of the value; %NULL is synonymous to "string"
* @param value: (nullable): the value to set, or %NULL to unset the given @em key
*
* Sets the metadata associated with the given @subject and @key. Use %NULL as
* a value to unset the given @key and use %NULL in both @key and @value to
* remove all metadata associated with the given @subject.
* @brief Sets the metadata associated with the given @em subject and @em key. Use %NULL as
* a value to unset the given @em key and use %NULL in both @em key and @em value to
* remove all metadata associated with the given @em subject.
*/
void
wp_metadata_set (WpMetadata * self, guint32 subject,
const gchar * key, const gchar * type, const gchar * value)
@@ -478,12 +512,13 @@ wp_metadata_set (WpMetadata * self, guint32 subject,
pw_metadata_set_property (priv->iface, subject, key, type, value);
}
/**
* wp_metadata_clear:
* @self: the metadata object
/*!
* @memberof WpMetadata
* @param self: the metadata object
*
* Clears permanently all stored metadata.
* @brief Clears permanently all stored metadata.
*/
void
wp_metadata_clear (WpMetadata * self)
{
@@ -491,8 +526,11 @@ wp_metadata_clear (WpMetadata * self)
pw_metadata_clear (priv->iface);
}
/* WpImplMetadata */
/*!
* @struct WpImplMetadata
* @memberof WpMetadata
* @section impl_metadata_section WpImplMetadata
*/
struct _WpImplMetadata
{
WpMetadata parent;
@@ -501,13 +539,6 @@ struct _WpImplMetadata
struct spa_hook_list hooks;
};
/**
* WpImplMetadata:
*
* The #WpImplMetadata class implements a PipeWire metadata object. It can
* be exported and made available by requesting the %WP_PROXY_FEATURE_BOUND
* feature.
*/
G_DEFINE_TYPE (WpImplMetadata, wp_impl_metadata, WP_TYPE_METADATA)
#define pw_metadata_emit(hooks,method,version,...) \
@@ -677,6 +708,15 @@ wp_impl_metadata_class_init (WpImplMetadataClass * klass)
proxy_class->pw_proxy_destroyed = wp_impl_metadata_pw_proxy_destroyed;
}
/*!
* @memberof WpMetadata
*
* @param core: the core
*
* @returns (transfer full): a new [WpImplMetadata](@ref impl_metadata_section)
*
*/
WpImplMetadata *
wp_impl_metadata_new (WpCore * core)
{

42
lib/wp/metadata.h
View File

@@ -13,26 +13,41 @@
G_BEGIN_DECLS
/**
* WpMetadataFeatures:
* @WP_METADATA_FEATURE_DATA: caches metadata locally
/*!
* @memberof WpMetadata
*
* An extension of #WpProxyFeatures
* @brief
* @em WP_METADATA_FEATURE_DATA: caches metadata locally
*
* An extension of [WpProxyFeatures](@ref proxy_features_section)
*/
typedef enum { /*< flags >*/
WP_METADATA_FEATURE_DATA = (WP_PROXY_FEATURE_CUSTOM_START << 0),
} WpMetadataFeatures;
/**
* WP_TYPE_METADATA:
/*!
* @memberof WpMetadata
*
* @brief The [WpMetadata](@ref metadata_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_METADATA (wp_metadata_get_type ())
* @endcode
*
* The #WpMetadata #GType
*/
#define WP_TYPE_METADATA (wp_metadata_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpMetadata, wp_metadata, WP, METADATA, WpGlobalProxy)
/*!
* @memberof WpMetadata
*
* @brief
* @em parent_class
*/
struct _WpMetadataClass
{
WpGlobalProxyClass parent_class;
@@ -56,10 +71,17 @@ void wp_metadata_set (WpMetadata * self, guint32 subject,
WP_API
void wp_metadata_clear (WpMetadata * self);
/**
* WP_TYPE_IMPL_MEATADATA:
/*!
* @memberof WpMetadata
*
* @brief The [WpImplMetadata](@ref impl_metadata_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_IMPL_METADATA (wp_impl_metadata_get_type ())
* @endcode
*
* The #WpImplMetadata #GType
*/
#define WP_TYPE_IMPL_METADATA (wp_impl_metadata_get_type ())

287
lib/wp/node.c
View File

@@ -6,11 +6,9 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: node
* @title: PipeWire Node
/*!
* @file node.c
*/
#define G_LOG_DOMAIN "wp-node"
#include "node.h"
@@ -22,6 +20,47 @@
#include <pipewire/impl.h>
/*!
* @memberof WpNode
*
* @signal @b ports-changed
*
* @code
* ports_changed_callback (WpNode * self,
* gpointer user_data)
* @endcode
*
* Emitted when the node's ports change. This is only emitted when %WP_NODE_FEATURE_PORTS is enabled.
*
* @b Parameters:
*
* @arg `self` - the node
* @arg `user_data`
*
* Flags: Run Last
*
* @signal @b state-changed
*
* @code
* state_changed_callback (WpNode * self,
* WpNodeState * old_state,
* WpNodeState * new_state,
* gpointer user_data)
* @endcode
*
* Emitted when the node changes state. This is only emitted when
* %WP_PIPEWIRE_OBJECT_FEATURE_INFO is enabled.
*
* @b Parameters:
*
* @arg `self` - the node
* @arg `old_state` - the old state
* @arg `new_state` - the new state
* @arg `user_data`
*
* Flags: Run Last
*
*/
enum {
SIGNAL_STATE_CHANGED,
SIGNAL_PORTS_CHANGED,
@@ -30,6 +69,26 @@ enum {
static guint32 signals[N_SIGNALS] = {0};
/*!
*
* @struct WpNode
* @section node_section Node
*
* @brief The [WpNode](@ref node_section) class allows accessing the properties and methods of a
* PipeWire node object (`struct pw_node`).
*
* A [WpNode](@ref node_section) is constructed internally when a new node appears on the
* PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
* Alternatively, a [WpNode](@ref node_section) can also be constructed using
* wp_node_new_from_factory(), which creates a new node object
* on the remote PipeWire server by calling into a factory.
*
*/
/*!
* @brief
* @em parent
* @em ports_om
*/
struct _WpNode
{
WpGlobalProxy parent;
@@ -39,18 +98,6 @@ struct _WpNode
static void wp_node_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpNode:
*
* The #WpNode class allows accessing the properties and methods of a
* PipeWire node object (`struct pw_node`).
*
* A #WpNode is constructed internally when a new node appears on the
* PipeWire registry and it is made available through the #WpObjectManager API.
* Alternatively, a #WpNode can also be constructed using
* wp_node_new_from_factory(), which creates a new node object
* on the remote PipeWire server by calling into a factory.
*/
G_DEFINE_TYPE_WITH_CODE (WpNode, wp_node, WP_TYPE_GLOBAL_PROXY,
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
wp_pw_object_mixin_object_interface_init)
@@ -198,13 +245,13 @@ wp_node_class_init (WpNodeClass * klass)
wp_pw_object_mixin_class_override_properties (object_class);
/**
/*
* WpNode::state-changed:
* @self: the node
* @old_state: the old state
* @new_state: the new state
*
* Emitted when the node changes state. This is only emitted
* @brief Emitted when the node changes state. This is only emitted
* when %WP_PIPEWIRE_OBJECT_FEATURE_INFO is enabled.
*/
signals[SIGNAL_STATE_CHANGED] = g_signal_new (
@@ -212,11 +259,10 @@ wp_node_class_init (WpNodeClass * klass)
G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 2,
WP_TYPE_NODE_STATE, WP_TYPE_NODE_STATE);
/**
/*
* WpNode::ports-changed:
* @self: the node
*
* Emitted when the node's ports change. This is only emitted
* @brief Emitted when the node's ports change. This is only emitted
* when %WP_NODE_FEATURE_PORTS is enabled.
*/
signals[SIGNAL_PORTS_CHANGED] = g_signal_new (
@@ -265,14 +311,14 @@ wp_node_pw_object_mixin_priv_interface_init (
iface->set_param = wp_node_set_param;
}
/**
* wp_node_new_from_factory:
* @core: the wireplumber core
* @factory_name: the pipewire factory name to construct the node
* @properties: (nullable) (transfer full): the properties to pass to the factory
/*!
* @memberof WpNode
* @param core: the wireplumber core
* @param factory_name: the pipewire factory name to construct the node
* @param properties: (nullable) (transfer full): the properties to pass to the factory
*
* Constructs a node on the PipeWire server by asking the remote factory
* @factory_name to create it.
* @brief Constructs a node on the PipeWire server by asking the remote factory
* @em param factory_name to create it.
*
* Because of the nature of the PipeWire protocol, this operation completes
* asynchronously at some point in the future. In order to find out when
@@ -281,9 +327,10 @@ wp_node_pw_object_mixin_priv_interface_init (
* use on the server. If the node cannot be created, this activation operation
* will fail.
*
* Returns: (nullable) (transfer full): the new node or %NULL if the core
* @returns (nullable) (transfer full): the new node or %NULL if the core
* is not connected and therefore the node cannot be created
*/
WpNode *
wp_node_new_from_factory (WpCore * core,
const gchar * factory_name, WpProperties * properties)
@@ -296,6 +343,14 @@ wp_node_new_from_factory (WpCore * core,
NULL);
}
/*!
* @memberof WpNode
* @param self: the node
* @param error: the error
*
* @returns the current state of the node
*/
WpNodeState
wp_node_get_state (WpNode * self, const gchar ** error)
{
@@ -311,15 +366,16 @@ wp_node_get_state (WpNode * self, const gchar ** error)
return (WpNodeState) info->state;
}
/**
* wp_node_get_n_input_ports:
* @self: the node
* @max: (out) (optional): the maximum supported number of input ports
/*!
* @memberof WpNode
* @param self: the node
* @param max: (out) (optional): the maximum supported number of input ports
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: the number of input ports of this node, as reported by the node info
* @returns the number of input ports of this node, as reported by the node info
*/
guint
wp_node_get_n_input_ports (WpNode * self, guint * max)
{
@@ -335,15 +391,16 @@ wp_node_get_n_input_ports (WpNode * self, guint * max)
return info->n_input_ports;
}
/**
* wp_node_get_n_output_ports:
* @self: the node
* @max: (out) (optional): the maximum supported number of output ports
/*!
* @memberof WpNode
* @param self: the node
* @param max: (out) (optional): the maximum supported number of output ports
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: the number of output ports of this node, as reported by the node info
* @returns the number of output ports of this node, as reported by the node info
*/
guint
wp_node_get_n_output_ports (WpNode * self, guint * max)
{
@@ -359,18 +416,19 @@ wp_node_get_n_output_ports (WpNode * self, guint * max)
return info->n_output_ports;
}
/**
* wp_node_get_n_ports:
* @self: the node
/*!
* @memberof WpNode
* @param self: the node
*
* Requires %WP_NODE_FEATURE_PORTS
* @brief Requires %WP_NODE_FEATURE_PORTS
*
* Returns: the number of ports of this node. Note that this number may not
* @returns the number of ports of this node. Note that this number may not
* add up to wp_node_get_n_input_ports() + wp_node_get_n_output_ports()
* because it is discovered by looking at the number of available ports
* in the registry, however ports may appear there with a delay or may
* not appear at all if this client does not have permission to read them
*/
guint
wp_node_get_n_ports (WpNode * self)
{
@@ -381,15 +439,16 @@ wp_node_get_n_ports (WpNode * self)
return wp_object_manager_get_n_objects (self->ports_om);
}
/**
* wp_node_new_ports_iterator:
* @self: the node
/*!
* @memberof WpNode
* @param self: the node
*
* Requires %WP_NODE_FEATURE_PORTS
* @brief Requires %WP_NODE_FEATURE_PORTS
*
* Returns: (transfer full): a #WpIterator that iterates over all
* @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all
* the ports that belong to this node
*/
WpIterator *
wp_node_new_ports_iterator (WpNode * self)
{
@@ -400,19 +459,20 @@ wp_node_new_ports_iterator (WpNode * self)
return wp_object_manager_new_iterator (self->ports_om);
}
/**
* wp_node_new_ports_filtered_iterator:
* @self: the node
/*!
* @memberof WpNode
* @param self: the node
* @...: a list of constraints, terminated by %NULL
*
* Requires %WP_NODE_FEATURE_PORTS
* @brief Requires %WP_NODE_FEATURE_PORTS
*
* The constraints specified in the variable arguments must follow the rules
* documented in wp_object_interest_new().
*
* Returns: (transfer full): a #WpIterator that iterates over all
* @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all
* the ports that belong to this node and match the constraints
*/
WpIterator *
wp_node_new_ports_filtered_iterator (WpNode * self, ...)
{
@@ -424,16 +484,17 @@ wp_node_new_ports_filtered_iterator (WpNode * self, ...)
return wp_node_new_ports_filtered_iterator_full (self, interest);
}
/**
* wp_node_new_ports_filtered_iterator_full: (rename-to wp_node_new_ports_filtered_iterator)
* @self: the node
* @interest: (transfer full): the interest
/*!
* @memberof WpNode
* @param self: the node
* @param interest: (transfer full): the interest
*
* Requires %WP_NODE_FEATURE_PORTS
* @brief Requires %WP_NODE_FEATURE_PORTS
*
* Returns: (transfer full): a #WpIterator that iterates over all
* the ports that belong to this node and match the @interest
* @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all
* the ports that belong to this node and match the @em interest
*/
WpIterator *
wp_node_new_ports_filtered_iterator_full (WpNode * self,
WpObjectInterest * interest)
@@ -446,19 +507,20 @@ wp_node_new_ports_filtered_iterator_full (WpNode * self,
interest);
}
/**
* wp_node_lookup_port:
* @self: the node
/*!
* @memberof WpNode
* @param self: the node
* @...: a list of constraints, terminated by %NULL
*
* Requires %WP_NODE_FEATURE_PORTS
* @brief Requires %WP_NODE_FEATURE_PORTS
*
* The constraints specified in the variable arguments must follow the rules
* documented in wp_object_interest_new().
*
* Returns: (transfer full) (nullable): the first port that matches the
* @returns (transfer full) (nullable): the first port that matches the
* constraints, or %NULL if there is no such port
*/
WpPort *
wp_node_lookup_port (WpNode * self, ...)
{
@@ -470,16 +532,17 @@ wp_node_lookup_port (WpNode * self, ...)
return wp_node_lookup_port_full (self, interest);
}
/**
* wp_node_lookup_port_full: (rename-to wp_node_lookup_port)
* @self: the node
* @interest: (transfer full): the interest
/*!
* @memberof WpNode
* @param self: the node
* @param interest: (transfer full): the interest
*
* Requires %WP_NODE_FEATURE_PORTS
* @brief Requires %WP_NODE_FEATURE_PORTS
*
* Returns: (transfer full) (nullable): the first port that matches the
* @interest, or %NULL if there is no such port
* @returns (transfer full) (nullable): the first port that matches the
* @em interest, or %NULL if there is no such port
*/
WpPort *
wp_node_lookup_port_full (WpNode * self, WpObjectInterest * interest)
{
@@ -491,13 +554,16 @@ wp_node_lookup_port_full (WpNode * self, WpObjectInterest * interest)
wp_object_manager_lookup_full (self->ports_om, interest);
}
/**
* wp_node_send_command:
* @self: the node
* @command: the command
/*!
* @memberof WpNode
* @param self: the node
* @param command: the command
*
* Sends a command to a node
* returns Void
*
* @brief Sends a command to a node
*/
void wp_node_send_command (WpNode * self, const gchar * command)
{
WpSpaIdValue command_value = wp_spa_id_value_from_short_name (
@@ -511,11 +577,32 @@ void wp_node_send_command (WpNode * self, const gchar * command)
pw_node_send_command (wp_proxy_get_pw_proxy (WP_PROXY (self)), &cmd);
}
/*!
* @memberof WpImplNode
*
* @props @b pw-impl-node
*
* @code
* "pw-impl-node" gpointer
* @endcode
*
* Flags : Read / Write / Construct Only
*/
enum {
PROP_PW_IMPL_NODE = WP_PW_OBJECT_MIXIN_PROP_CUSTOM_START,
};
/*!
* @struct WpImplNode:
* @memberof WpNode
* @section impl_node_section WpImplNode
*
* @brief A [WpImplNode](@ref impl_node_section) allows running a node
* implementation (`struct pw_impl_node`) locally,
* loading the implementation from factory or wrapping a manually
* constructed `pw_impl_node`. This object can then be exported to PipeWire
* by requesting %WP_PROXY_FEATURE_BOUND.
*/
struct _WpImplNode
{
WpProxy parent;
@@ -526,14 +613,6 @@ struct _WpImplNode
static void wp_impl_node_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpImplNode:
*
* A #WpImplNode allows running a node implementation (`struct pw_impl_node`)
* locally, loading the implementation from factory or wrapping a manually
* constructed `pw_impl_node`. This object can then be exported to PipeWire
* by requesting %WP_PROXY_FEATURE_BOUND.
*/
G_DEFINE_TYPE_WITH_CODE (WpImplNode, wp_impl_node, WP_TYPE_PROXY,
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
wp_pw_object_mixin_object_interface_init)
@@ -629,7 +708,7 @@ wp_impl_node_activate_get_next_step (WpObject * object,
WpFeatureActivationTransition * transition, guint step,
WpObjectFeatures missing)
{
/* BOUND is the only feature that can be in @missing */
/* BOUND is the only feature that can be in @em missing */
g_return_val_if_fail (missing == WP_PROXY_FEATURE_BOUND,
WP_TRANSITION_STEP_ERROR);
@@ -727,13 +806,14 @@ wp_impl_node_pw_object_mixin_priv_interface_init (
iface->set_param = wp_impl_node_set_param;
}
/**
* wp_impl_node_new_wrap:
* @core: the wireplumber core
* @node: an existing pw_impl_node to wrap
/*!
* @memberof WpNode
* @param core: the wireplumber core
* @param node: an existing pw_impl_node to wrap
*
* Returns: (transfer full): A new #WpImplNode wrapping @node
* @returns (transfer full): A new [WpImplNode](@ref impl_node_section) wrapping @em node
*/
WpImplNode *
wp_impl_node_new_wrap (WpCore * core, struct pw_impl_node * node)
{
@@ -743,24 +823,25 @@ wp_impl_node_new_wrap (WpCore * core, struct pw_impl_node * node)
NULL);
}
/**
* wp_impl_node_new_from_pw_factory:
* @core: the wireplumber core
* @factory_name: the name of the pipewire factory
* @properties: (nullable) (transfer full): properties to be passed to node
/*!
* @memberof WpNode
* @param core: the wireplumber core
* @param factory_name: the name of the pipewire factory
* @param properties: (nullable) (transfer full): properties to be passed to node
* constructor
*
* Constructs a new node, locally on this process, using the specified
* @factory_name.
* @brief Constructs a new node, locally on this process, using the specified
* @em factory_name.
*
* To export this node to the PipeWire server, you need to call
* wp_object_activate() requesting %WP_PROXY_FEATURE_BOUND and
* wait for the operation to complete.
*
* Returns: (nullable) (transfer full): A new #WpImplNode wrapping the
* @returns (nullable) (transfer full): A new [WpImplNode](@ref impl_node_section) wrapping the
* node that was constructed by the factory, or %NULL if the factory
* does not exist or was unable to construct the node
*/
WpImplNode *
wp_impl_node_new_from_pw_factory (WpCore * core,
const gchar * factory_name, WpProperties * properties)

52
lib/wp/node.h
View File

@@ -18,13 +18,15 @@ G_BEGIN_DECLS
struct pw_impl_node;
/**
* WpNodeState:
* @WP_NODE_STATE_ERROR: error state
* @WP_NODE_STATE_CREATING: the node is being created
* @WP_NODE_STATE_SUSPENDED: the node is suspended, the device might be closed
* @WP_NODE_STATE_IDLE: the node is running but there is no active port
* @WP_NODE_STATE_RUNNING: the node is running
/*!
* @memberof WpNode
*
* @brief
* @arg WP_NODE_STATE_ERROR: error state
* @arg WP_NODE_STATE_CREATING: the node is being created
* @arg WP_NODE_STATE_SUSPENDED: the node is suspended, the device might be closed
* @arg WP_NODE_STATE_IDLE: the node is running but there is no active port
* @arg WP_NODE_STATE_RUNNING: the node is running
*/
typedef enum {
WP_NODE_STATE_ERROR = -1,
@@ -34,22 +36,31 @@ typedef enum {
WP_NODE_STATE_RUNNING = 3,
} WpNodeState;
/**
* WpNodeFeatures:
* @WP_NODE_FEATURE_PORTS: caches information about ports, enabling
/*!
* @memberof WpNode
*
* @brief
* @arg WP_NODE_FEATURE_PORTS: caches information about ports, enabling
* the use of wp_node_get_n_ports(), wp_node_lookup_port(),
* wp_node_new_ports_iterator() and related methods
*
* An extension of #WpProxyFeatures
* An extension of [WpProxyFeatures](@ref proxy_features_section)
*/
typedef enum { /*< flags >*/
WP_NODE_FEATURE_PORTS = (WP_PROXY_FEATURE_CUSTOM_START << 0),
} WpNodeFeatures;
/**
* WP_TYPE_NODE:
/*!
* @memberof WpNode
*
* @brief The [WpNode](@ref node_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_NODE (wp_node_get_type ())
* @endcode
*
* The #WpNode #GType
*/
#define WP_TYPE_NODE (wp_node_get_type ())
WP_API
@@ -91,10 +102,17 @@ WpPort * wp_node_lookup_port_full (WpNode * self, WpObjectInterest * interest);
WP_API
void wp_node_send_command (WpNode * self, const gchar *command);
/**
* WP_TYPE_IMPL_NODE:
/*!
* @memberof WpNode
*
* @brief The [WpImplNode](@ref impl_node_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_IMPL_NODE (wp_impl_node_get_type ())
* @endcode
*
* The #WpImplNode #GType
*/
#define WP_TYPE_IMPL_NODE (wp_impl_node_get_type ())
WP_API

247
lib/wp/object-interest.c
View File

@@ -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,

50
lib/wp/object-interest.h
View File

@@ -15,17 +15,20 @@
G_BEGIN_DECLS
/**
* WpConstraintType:
* @WP_CONSTRAINT_TYPE_NONE: invalid constraint type
* @WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY: constraint applies
/*!
* @memberof WpObjectInterest
*
* @brief
* @arg WP_CONSTRAINT_TYPE_NONE: invalid constraint type
* @arg WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY: constraint applies
* to a PipeWire global property of the object (the ones returned by
* wp_global_proxy_get_global_properties())
* @WP_CONSTRAINT_TYPE_PW_PROPERTY: constraint applies
* @arg WP_CONSTRAINT_TYPE_PW_PROPERTY: constraint applies
* to a PipeWire property of the object (the ones returned by
* wp_pipewire_object_get_properties())
* @WP_CONSTRAINT_TYPE_G_PROPERTY: constraint applies to a #GObject
* property of the object
* @arg WP_CONSTRAINT_TYPE_G_PROPERTY: constraint applies to a
* <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
* GObject</a> property of the object
*/
typedef enum {
WP_CONSTRAINT_TYPE_NONE = 0,
@@ -34,20 +37,22 @@ typedef enum {
WP_CONSTRAINT_TYPE_G_PROPERTY,
} WpConstraintType;
/**
* WpConstraintVerb:
* @WP_CONSTRAINT_VERB_EQUALS: `=` the subject's value must equal the
/*!
* @memberof WpObjectInterest
*
* @brief
* @arg WP_CONSTRAINT_VERB_EQUALS: `=` the subject's value must equal the
* constraint's value
* @WP_CONSTRAINT_VERB_NOT_EQUALS: `!` the subject's value must be different
* @arg WP_CONSTRAINT_VERB_NOT_EQUALS: `!` the subject's value must be different
* from the constraint's value
* @WP_CONSTRAINT_VERB_IN_LIST: `c` the subject's value must equal at least
* @arg WP_CONSTRAINT_VERB_IN_LIST: `c` the subject's value must equal at least
* one of the values in the list given as the constraint's value
* @WP_CONSTRAINT_VERB_IN_RANGE: `~` the subject's value must be a number
* @arg WP_CONSTRAINT_VERB_IN_RANGE: `~` the subject's value must be a number
* in the range defined by the constraint's value
* @WP_CONSTRAINT_VERB_MATCHES: `#` the subject's value must match the
* @arg WP_CONSTRAINT_VERB_MATCHES: `#` the subject's value must match the
* pattern specified in the constraint's value
* @WP_CONSTRAINT_VERB_IS_PRESENT: `+` the subject property must exist
* @WP_CONSTRAINT_VERB_IS_ABSENT: `-` the subject property must not exist
* @arg WP_CONSTRAINT_VERB_IS_PRESENT: `+` the subject property must exist
* @arg WP_CONSTRAINT_VERB_IS_ABSENT: `-` the subject property must not exist
*/
typedef enum {
WP_CONSTRAINT_VERB_EQUALS = '=',
@@ -59,11 +64,18 @@ typedef enum {
WP_CONSTRAINT_VERB_IS_ABSENT = '-',
} WpConstraintVerb;
/**
* WP_TYPE_OBJECT_INTEREST:
/*!
* @memberof WpObjectInterest
*
* The #WpObjectInterest #GType
* @brief The [WpObjectInterest](@ref object_interest_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_OBJECT_INTEREST (wp_object_interest_get_type ())
* @endcode
*/
#define WP_TYPE_OBJECT_INTEREST (wp_object_interest_get_type ())
WP_API
GType wp_object_interest_get_type (void) G_GNUC_CONST;

371
lib/wp/object-manager.c
View File

@@ -6,48 +6,69 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: object-manager
* @title: Object Manager
/*!
* @file object-manager.c
*/
#define G_LOG_DOMAIN "wp-object-manager"
#include "object-manager.h"
/*!
* @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.
* @section object_manager_section Object Manager
*
* There are 4 kinds of objects that can be managed by a #WpObjectManager:
* @brief The [WpObjectManager](@ref object_manager_section) 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](@ref object_manager_section):
* * remote PipeWire global objects that are advertised on the registry;
* these are bound locally to subclasses of #WpGlobalProxy
* these are bound locally to subclasses of [WpGlobalProxy](@ref global_proxy_section)
* * 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
* global objects but it should be noted that the same
* [WpGlobalProxy](@ref global_proxy_section)
* instance that created them appears in the
* [WpObjectManager](@ref object_manager_section) (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
* ([WpImplSession](@ref impl_session_section), WpImplEndpoint [private], etc); these appear in the
* [WpObjectManager](@ref object_manager_section) 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().
* it on the [WpCore](@ref core_section) 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
* Upon installing a [WpObjectManager](@ref object_manager_section) on a
* [WpCore](@ref core_section), any pre-existing objects
* that match the interests of this [WpObjectManager](@ref object_manager_section) 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.
* [WpObjectManager](@ref object_manager_section)
* [object-added](@ref signal_object_added_section) signal will be emitted for all of them.
*
*/
#define G_LOG_DOMAIN "wp-object-manager"
#include "object-manager.h"
#include "log.h"
#include "private/registry.h"
#include <pipewire/pipewire.h>
/* WpObjectManager */
/*!
* @brief
* @em parent
* @em core
* @em interests
* @em features
* @em objects
* @em installed
* @em changed
* @em pending_objects
* @em idle_source
*/
struct _WpObjectManager
{
GObject parent;
@@ -66,11 +87,102 @@ struct _WpObjectManager
GSource *idle_source;
};
/*!
* @memberof WpObjectManager
*
* @props @b core
*
* @code
* "core" WpCore *
* @endcode
*
* Flags : Read
*
*/
enum {
PROP_0,
PROP_CORE,
};
/*!
* @memberof WpObjectManager
*
* @signal @b installed
*
* @code
* installed_callback (WpObjectManager * self,
* gpointer user_data)
* @endcode
*
* 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:
*
* @arg `self` - the object manager
* @arg `user_data`
*
* Flags: Run First
*
* @signal @b object-added
*
* @code
* object_added_callback (WpObjectManager * self,
* gpointer object,
* gpointer user_data)
* @endcode
*
* Emitted when an object that matches the interests of this object manager is made available.
*
* @b Parameters:
*
* @arg `self` - the object manager
* @arg `object` - the managed object that was just added
* @arg `user_data`
*
* Flags: Run First
*
* @signal @b object-removed
*
* @code
* object_removed_callback (WpObjectManager * self,
* gpointer object,
* gpointer user_data)
* @endcode
*
* 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.
*
* @b Parameters:
*
* @arg `self` - the object manager
* @arg `object` - the managed object that is being removed
* @arg `user_data`
*
* Flags: Run First
*
* @signal @b object-changed
*
* @code
* object_changed_callback (WpObjectManager * self,
* gpointer user_data)
* @endcode
*
* 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:
*
* @arg `self` - the object manager
* @arg `user_data`
*
* Flags: Run First
*
*/
enum {
SIGNAL_OBJECT_ADDED,
SIGNAL_OBJECT_REMOVED,
@@ -143,24 +255,28 @@ wp_object_manager_class_init (WpObjectManagerClass * klass)
g_param_spec_object ("core", "core", "The WpCore", WP_TYPE_CORE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
/*
* WpObjectManager::object-added:
* @self: the object manager
* @object: (transfer none): the managed object that was just added
*
* Emitted when an object that matches the interests of this object manager
* @section signal_object_added_section object-added
*
* @brief Emitted when an object that matches the interests of this object manager
* is made available.
*/
signals[SIGNAL_OBJECT_ADDED] = g_signal_new (
"object-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_OBJECT);
/**
/*
* WpObjectManager::object-removed:
* @self: the object manager
* @object: (transfer none): the managed object that is being removed
*
* Emitted when an object that was previously added on this object manager
* @section signal_object_removed_section object-removed
*
* @brief 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.
*/
@@ -168,11 +284,11 @@ wp_object_manager_class_init (WpObjectManagerClass * klass)
"object-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_OBJECT);
/**
/*
* WpObjectManager::objects-changed:
* @self: the object manager
*
* Emitted when one or more objects have been recently added or removed
* @brief 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
@@ -182,11 +298,11 @@ wp_object_manager_class_init (WpObjectManagerClass * klass)
"objects-changed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
0, NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
/*
* WpObjectManager::installed:
* @self: the object manager
*
* This is emitted once after the object manager is installed with
* @brief 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.
@@ -196,26 +312,27 @@ wp_object_manager_class_init (WpObjectManagerClass * klass)
0, NULL, NULL, NULL, G_TYPE_NONE, 0);
}
/**
* wp_object_manager_new:
/*!
* @memberof WpObjectManager
* @brief Constructs a new object manager.
*
* Constructs a new object manager.
*
* Returns: (transfer full): the newly constructed object manager
* @returns (transfer full): the newly constructed object manager
*/
WpObjectManager *
wp_object_manager_new (void)
{
return g_object_new (WP_TYPE_OBJECT_MANAGER, NULL);
}
/**
* wp_object_manager_is_installed:
* @self: the object manager
/*!
* @memberof WpObjectManager
* @param self: the object manager
*
* Returns: %TRUE if the object manager is installed (the
* @returns %TRUE if the object manager is installed (the
* WpObjectManager::installed has been emitted), %FALSE otherwise
*/
gboolean
wp_object_manager_is_installed (WpObjectManager * self)
{
@@ -223,13 +340,16 @@ wp_object_manager_is_installed (WpObjectManager * self)
return self->installed;
}
/**
* wp_object_manager_add_interest:
* @self: the object manager
* @gtype: the #GType of the objects that we are declaring interest in
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param gtype: the
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
* of the objects that we are declaring interest in
* @...: a list of constraints, terminated by %NULL
*
* Equivalent to:
* @brief Equivalent to:
* |[
* WpObjectInterest *i = wp_object_interest_new (gtype, ...);
* wp_object_manager_add_interest_full (self, i);
@@ -238,6 +358,7 @@ wp_object_manager_is_installed (WpObjectManager * self)
* The constraints specified in the variable arguments must follow the rules
* documented in wp_object_interest_new().
*/
void
wp_object_manager_add_interest (WpObjectManager * self, GType gtype, ...)
{
@@ -252,16 +373,19 @@ wp_object_manager_add_interest (WpObjectManager * self, GType gtype, ...)
va_end (args);
}
/**
* wp_object_manager_add_interest_full: (rename-to wp_object_manager_add_interest)
* @self: the object manager
* @interest: (transfer full): the interest
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param interest: (transfer full): the interest
*
* Declares interest in a certain kind of object. Interest consists of a #GType
* @brief Declares interest in a certain kind of object. Interest consists of a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
* 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.
* object. Refer to [WpObjectInterest](@ref object_interest_section) for more details.
*/
void
wp_object_manager_add_interest_full (WpObjectManager *self,
WpObjectInterest * interest)
@@ -297,16 +421,17 @@ store_children_object_features (GHashTable *store, GType object_type,
}
}
/**
* wp_object_manager_request_object_features:
* @self: the object manager
* @object_type: the #WpProxy descendant type
* @wanted_features: the features to enable on this kind of object
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param object_type: the [WpProxy](@ref proxy_section) descendant type
* @param wanted_features: the features to enable on this kind of object
*
* Requests the object manager to automatically prepare the @wanted_features
* on any managed object that is of the specified @object_type. These features
* @brief Requests the object manager to automatically prepare the @em wanted_features
* on any managed object that is of the specified @em object_type. These features
* will always be prepared before the object appears on the object manager.
*/
void
wp_object_manager_request_object_features (WpObjectManager *self,
GType object_type, WpObjectFeatures wanted_features)
@@ -319,12 +444,13 @@ wp_object_manager_request_object_features (WpObjectManager *self,
store_children_object_features (self->features, object_type, wanted_features);
}
/**
* wp_object_manager_get_n_objects:
* @self: the object manager
/*!
* @memberof WpObjectManager
* @param self: the object manager
*
* Returns: the number of objects managed by this #WpObjectManager
* @returns the number of objects managed by this [WpObjectManager](@ref object_manager_section)
*/
guint
wp_object_manager_get_n_objects (WpObjectManager * self)
{
@@ -406,13 +532,14 @@ static const WpIteratorMethods om_iterator_methods = {
.finalize = om_iterator_finalize,
};
/**
* wp_object_manager_new_iterator:
* @self: the object manager
/*!
* @memberof WpObjectManager
* @param self: the object manager
*
* Returns: (transfer full): a #WpIterator that iterates over all the managed
* @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all the managed
* objects of this object manager
*/
WpIterator *
wp_object_manager_new_iterator (WpObjectManager * self)
{
@@ -428,13 +555,15 @@ wp_object_manager_new_iterator (WpObjectManager * self)
return it;
}
/**
* wp_object_manager_new_filtered_iterator:
* @self: the object manager
* @gtype: the #GType of the objects to iterate through
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param gtype: the
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a> of the objects to iterate through
* @...: a list of constraints, terminated by %NULL
*
* Equivalent to:
* @brief Equivalent to:
* |[
* WpObjectInterest *i = wp_object_interest_new (gtype, ...);
* return wp_object_manager_new_filtered_iterator_full (self, i);
@@ -443,9 +572,10 @@ wp_object_manager_new_iterator (WpObjectManager * self)
* The constraints specified in the variable arguments must follow the rules
* documented in wp_object_interest_new().
*
* Returns: (transfer full): a #WpIterator that iterates over all the matching
* @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all the matching
* objects of this object manager
*/
WpIterator *
wp_object_manager_new_filtered_iterator (WpObjectManager * self, GType gtype,
...)
@@ -462,17 +592,18 @@ wp_object_manager_new_filtered_iterator (WpObjectManager * self, GType gtype,
return wp_object_manager_new_filtered_iterator_full (self, interest);
}
/**
* wp_object_manager_new_filtered_iterator_full: (rename-to wp_object_manager_new_filtered_iterator)
* @self: the object manager
* @interest: (transfer full): the interest
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param interest: (transfer full): the interest
*
* Iterates through all the objects managed by this object manager that
* match the specified @interest.
* @brief Iterates through all the objects managed by this object manager that
* match the specified @em interest.
*
* Returns: (transfer full): a #WpIterator that iterates over all the matching
* @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all the matching
* objects of this object manager
*/
WpIterator *
wp_object_manager_new_filtered_iterator_full (WpObjectManager * self,
WpObjectInterest * interest)
@@ -498,13 +629,15 @@ wp_object_manager_new_filtered_iterator_full (WpObjectManager * self,
return it;
}
/**
* wp_object_manager_lookup:
* @self: the object manager
* @gtype: the #GType of the object to lookup
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param gtype: the
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a> of the object to lookup
* @...: a list of constraints, terminated by %NULL
*
* Equivalent to:
* @brief Equivalent to:
* |[
* WpObjectInterest *i = wp_object_interest_new (gtype, ...);
* return wp_object_manager_lookup_full (self, i);
@@ -513,9 +646,10 @@ wp_object_manager_new_filtered_iterator_full (WpObjectManager * self,
* The constraints specified in the variable arguments must follow the rules
* documented in wp_object_interest_new().
*
* Returns: (type GObject)(transfer full)(nullable): the first managed object
* @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 (WpObjectManager * self, GType gtype, ...)
{
@@ -531,19 +665,20 @@ wp_object_manager_lookup (WpObjectManager * self, GType gtype, ...)
return wp_object_manager_lookup_full (self, interest);
}
/**
* wp_object_manager_lookup_full:
* @self: the object manager
* @interest: (transfer full): the interst
/*!
* @memberof WpObjectManager
* @param self: the object manager
* @param interest: (transfer full): the interst
*
* Searches for an object that matches the specified @interest and returns
* @brief Searches for an object that matches the specified @em 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.
*
* Returns: (type GObject)(transfer full)(nullable): the first managed object
* @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)
@@ -735,9 +870,11 @@ wp_object_manager_rm_object (WpObjectManager * self, gpointer object)
}
/*
* WpRegistry
* WpRegistry:
*
* The registry keeps track of registered objects on the wireplumber core.
* @section registry_section WpRegistry
*
* @brief The registry keeps track of registered objects on the wireplumber core.
* There are 3 kinds of registered objects:
*
* 1) PipeWire global objects, which live in another process.
@@ -1044,10 +1181,10 @@ expose_tmp_globals (WpCore *core, GAsyncResult *res, WpRegistry *self)
}
/*
* wp_registry_prepare_new_global:
* @new_global: (out) (transfer full) (optional): the new global
*
* This is normally called up to 2 times in the same sync cycle:
* @param new_global: (out) (transfer full) (optional): the new global
*
* @brief This is normally called up to 2 times in the same sync cycle:
* one from registry_global(), another from the proxy bound event
* Unfortunately the order in which those 2 events happen is specific
* to the implementation of the object, which is why this is implemented
@@ -1121,16 +1258,16 @@ wp_registry_prepare_new_global (WpRegistry * self, guint32 id,
}
/*
* wp_registry_find_object:
* @reg: the registry
* @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
*
* @param reg: the registry
* @param func: (scope call): a function that takes the object being searched
* as the first argument and @em data as the second. it should return TRUE if
* the object is found or FALSE otherwise
* @data: the second argument to @func
* @param data: the second argument to @em func
*
* Finds a registered object
* @brief Finds a registered object
*
* Returns: (transfer full) (type GObject *) (nullable): the registered object
* @returns (transfer full) (type GObject *) (nullable): the registered object
* or NULL if not found
*/
gpointer
@@ -1153,11 +1290,12 @@ wp_registry_find_object (WpRegistry *reg, GEqualFunc func, gconstpointer data)
}
/*
* wp_registry_register_object:
* @reg: the registry
* @obj: (transfer full) (type GObject*): the object to register
*
* Registers @obj with the core, making it appear on #WpObjectManager
* @param reg: the registry
* @param obj: (transfer full) (type GObject*): the object to register
*
* @brief Registers @em obj with the core, making it appear on
* [WpObjectManager](@ref object_manager_section)
* instances as well. The core will also maintain a ref to that object
* until it is removed.
*/
@@ -1179,11 +1317,11 @@ wp_registry_register_object (WpRegistry *reg, gpointer obj)
}
/*
* wp_registry_remove_object:
* @reg: the registry
* @obj: (transfer none) (type GObject*): a pointer to the object to remove
*
* Detaches and unrefs the specified object from this core
* @param reg: the registry
* @param obj: (transfer none) (type GObject*): a pointer to the object to remove
*
* @brief Detaches and unrefs the specified object from this core
*/
void
wp_registry_remove_object (WpRegistry *reg, gpointer obj)
@@ -1200,15 +1338,16 @@ wp_registry_remove_object (WpRegistry *reg, gpointer obj)
g_ptr_array_remove_fast (reg->objects, obj);
}
/**
* wp_core_install_object_manager:
* @self: the core
* @om: (transfer none): a #WpObjectManager
/*!
* @memberof WpObjectManager
* @param self: the core
* @param om: (transfer none): a [WpObjectManager](@ref object_manager_section)
*
* 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.
* @brief Installs the object manager on this core, activating its internal management
* engine. This will immediately emit signals about objects added on @em om
* if objects that the @em om is interested in were in existence already.
*/
void
wp_core_install_object_manager (WpCore * self, WpObjectManager * om)
{

13
lib/wp/object-manager.h
View File

@@ -16,10 +16,17 @@
G_BEGIN_DECLS
/**
* WP_TYPE_OBJECT_MANAGER:
/*!
* @memberof WpObjectManager
*
* @brief The [WpObjectManager](@ref object_manager_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_OBJECT_MANAGER (wp_object_manager_get_type ())
* @endcode
*
* The #WpObjectManager #GType
*/
#define WP_TYPE_OBJECT_MANAGER (wp_object_manager_get_type ())
WP_API

173
lib/wp/object.c
View File

@@ -5,29 +5,34 @@
*
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: object
* @title: Base object type
/*!
* @file object.c
*/
#define G_LOG_DOMAIN "wp-object"
#include "object.h"
#include "log.h"
#include "core.h"
/*!
* @struct WpFeatureActivationTransition
* @memberof WpObject
* @section feature_active_transition_section Feature Activation
*
* @brief A [WpTransition](@ref transition_section) that is used by
* [WpObject](@ref object_section) to implement feature activation.
*/
/*!
* @brief
* @em parent
* @em missing
*/
struct _WpFeatureActivationTransition
{
WpTransition parent;
WpObjectFeatures missing;
};
/**
* WpFeatureActivationTransition:
*
* A #WpTransition that is used by #WpObject to implement feature activation.
*/
G_DEFINE_TYPE (WpFeatureActivationTransition,
wp_feature_activation_transition,
WP_TYPE_TRANSITION)
@@ -107,14 +112,15 @@ wp_feature_activation_transition_class_init (
wp_feature_activation_transition_execute_step;
}
/**
* wp_feature_activation_transition_get_requested_features:
* @self: the transition
/*!
* @memberof WpFeatureActivationTransition
* @param self: the transition
*
* Returns: the features that were requested to be activated in this transition;
* @returns the features that were requested to be activated in this transition;
* this contains the features as they were passed in wp_object_activate() and
* therefore it may contain unsupported or already active features
*/
WpObjectFeatures
wp_feature_activation_transition_get_requested_features (
WpFeatureActivationTransition * self)
@@ -122,7 +128,9 @@ wp_feature_activation_transition_get_requested_features (
return GPOINTER_TO_UINT (wp_transition_get_data (WP_TRANSITION (self)));
}
/*!
* @struct WpObject
*/
typedef struct _WpObjectPrivate WpObjectPrivate;
struct _WpObjectPrivate
{
@@ -135,6 +143,33 @@ struct _WpObjectPrivate
GSource *idle_advnc_source;
};
/*!
* @memberof WpObject
*
* @props @b active-features
*
* @code
* "active-features" guint
* @endcode
*
* Flags : Read
*
* @props @b core
*
* @code
* "core" WpCore *
* @endcode
*
* Flags : Read / Write / Construct Only
*
* @props @b supported-features
*
* @code
* "supported-features" <a href="https://developer.gnome.org/glib/stable/glib-Basic-Types.html#guint">guint</a>
* @endcode
*
* Flags : Read
*/
enum {
PROP_0,
PROP_CORE,
@@ -142,11 +177,6 @@ enum {
PROP_SUPPORTED_FEATURES,
};
/**
* WpObject:
*
* Base class for objects that may have optional activatable features.
*/
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpObject, wp_object, G_TYPE_OBJECT)
static void
@@ -257,12 +287,13 @@ wp_object_class_init (WpObjectClass * klass)
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
}
/**
* wp_object_get_core:
* @self: the object
/*!
* @memberof WpObject
* @param self: the object
*
* Returns: (transfer full): the core associated with this object
* @returns (transfer full): the core associated with this object
*/
WpCore *
wp_object_get_core (WpObject * self)
{
@@ -272,12 +303,13 @@ wp_object_get_core (WpObject * self)
return g_weak_ref_get (&priv->core);
}
/**
* wp_object_get_active_features:
* @self: the object
/*!
* @memberof WpObject
* @param self: the object
*
* Returns: a bitset containing the active features of this object
* @returns a bitset containing the active features of this object
*/
WpObjectFeatures
wp_object_get_active_features (WpObject * self)
{
@@ -287,13 +319,14 @@ wp_object_get_active_features (WpObject * self)
return priv->ft_active;
}
/**
* wp_object_get_supported_features:
* @self: the object
/*!
* @memberof WpObject
* @param self: the object
*
* Returns: a bitset containing the supported features of this object;
* @returns a bitset containing the supported features of this object;
* note that supported features may change at runtime
*/
WpObjectFeatures
wp_object_get_supported_features (WpObject * self)
{
@@ -306,8 +339,8 @@ wp_object_get_supported_features (WpObject * self)
static gboolean
wp_object_advance_transitions (WpObject * self)
{
/* keep @self alive; in rare cases, the last transition may be
holding the last ref on @self and g_queue_peek_head will crash
/* keep @em self alive; in rare cases, the last transition may be
holding the last ref on @em self and g_queue_peek_head will crash
right after droping that last ref */
g_autoptr (WpObject) self_ref = g_object_ref (self);
WpObjectPrivate *priv = wp_object_get_instance_private (self);
@@ -327,16 +360,17 @@ wp_object_advance_transitions (WpObject * self)
return G_SOURCE_REMOVE;
}
/**
* wp_object_activate:
* @self: the object
* @features: the features to enable
* @cancellable: (nullable): a cancellable for the async operation
* @callback: (scope async): a function to call when activation is complete
* @user_data: (closure): data for @callback
/*!
* @memberof WpObject
* @param self: the object
* @param features: the features to enable
* @param cancellable: (nullable): a cancellable for the async operation
* @param callback: (scope async): a function to call when activation is complete
* @param user_data: (closure): data for @em callback
*
* Callback version of wp_object_activate_closure
* @brief Callback version of wp_object_activate_closure
*/
void
wp_object_activate (WpObject * self,
WpObjectFeatures features, GCancellable * cancellable,
@@ -349,23 +383,24 @@ wp_object_activate (WpObject * self,
wp_object_activate_closure (self, features, cancellable, closure);
}
/**
* wp_object_activate_closure:
* @self: the object
* @features: the features to enable
* @cancellable: (nullable): a cancellable for the async operation
* @closure: (transfer full): the closure to use when activation is completed
/*!
* @memberof WpObject
* @param self: the object
* @param features: the features to enable
* @param cancellable: (nullable): a cancellable for the async operation
* @param closure: (transfer full): the closure to use when activation is completed
*
* Activates the requested @features and invokes @closure when this is done.
* @features may contain unsupported or already active features. The operation
* @brief Activates the requested @em features and invokes @em closure when this is done.
* @em features may contain unsupported or already active features. The operation
* will filter them and activate only ones that are supported and inactive.
*
* If multiple calls to this method is done, the operations will be executed
* one after the other to ensure features only get activated once.
*
* Note that @closure may be invoked in sync while this method is being called,
* Note that @em closure may be invoked in sync while this method is being called,
* if there are no features to activate.
*/
void
wp_object_activate_closure (WpObject * self,
WpObjectFeatures features, GCancellable * cancellable,
@@ -391,15 +426,16 @@ wp_object_activate_closure (WpObject * self,
}
}
/**
* wp_object_activate_finish:
* @self: the object
* @res: the async operation result
* @error: (out) (optional): the error of the operation, if any
/*!
* @memberof WpObject
* @param self: the object
* @param res: the async operation result
* @param error: (out) (optional): the error of the operation, if any
*
* Returns: %TRUE if the requested features were activated,
* @returns %TRUE if the requested features were activated,
* %FALSE if there was an error
*/
gboolean
wp_object_activate_finish (WpObject * self, GAsyncResult * res, GError ** error)
{
@@ -409,15 +445,16 @@ wp_object_activate_finish (WpObject * self, GAsyncResult * res, GError ** error)
return wp_transition_finish (res, error);
}
/**
* wp_object_deactivate
* @self: the object
* @features: the features to deactivate
/*!
* @memberof WpObject
* @param self: the object
* @param features: the features to deactivate
*
* Deactivates the given @features, leaving the object in the state it was
* @brief Deactivates the given @em features, leaving the object in the state it was
* before they were enabled. This is seldom needed to call manually, but it
* can be used to save resources if some features are no longer needed.
*/
void
wp_object_deactivate (WpObject * self, WpObjectFeatures features)
{
@@ -428,15 +465,15 @@ wp_object_deactivate (WpObject * self, WpObjectFeatures features)
WP_OBJECT_GET_CLASS (self)->deactivate (self, features & priv->ft_active);
}
/**
* wp_object_update_features:
*
* Private method to be called by subclasses. Allows subclasses to update
* the currently active features. @activated should contain new features and
* @deactivated should contain features that were just deactivated.
/*!
* @memberof WpObject
* @brief Private method to be called by subclasses. Allows subclasses to update
* the currently active features. @em activated should contain new features and
* @em deactivated should contain features that were just deactivated.
*
* Calling this method also advances the activation transitions.
*/
void
wp_object_update_features (WpObject * self, WpObjectFeatures activated,
WpObjectFeatures deactivated)

50
lib/wp/object.h
View File

@@ -6,6 +6,10 @@
* SPDX-License-Identifier: MIT
*/
/*!
* @file object.h
*/
#ifndef __WIREPLUMBER_OBJECT_H__
#define __WIREPLUMBER_OBJECT_H__
@@ -14,10 +18,12 @@
G_BEGIN_DECLS
/**
* WpObjectFeatures:
/*!
* @memberof WpObject
*
* Flags that specify functionality that is available on this class.
* @section object_features_section WpObjectFeatures
*
* @brief Flags that specify functionality that is available on this class.
*
* Use wp_object_activate() to enable more features,
* wp_object_get_supported_features() to see which features are supported and
@@ -30,18 +36,25 @@ G_BEGIN_DECLS
*/
typedef guint WpObjectFeatures;
/**
* WP_OBJECT_FEATURES_ALL:
/*!
* @memberof WpObject
*
* Special value that can be used to activate
* @brief Special value that can be used to activate
* all the supported features in any given object.
*/
static const WpObjectFeatures WP_OBJECT_FEATURES_ALL = 0xffffffff;
/**
* WP_TYPE_FEATURE_ACTIVATION_TRANSITION:
/*!
* @memberof WpFeatureActivationTransition
*
* @brief The [WpFeatureActivationTransition](@ref feature_activation_transition_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_FEATURE_ACTIVATION_TRANSITION (wp_feature_activation_transition_get_type ())
* @endcode
*
* The #WpFeatureActivationTransition #GType
*/
#define WP_TYPE_FEATURE_ACTIVATION_TRANSITION \
(wp_feature_activation_transition_get_type ())
@@ -54,15 +67,28 @@ WP_API
WpObjectFeatures wp_feature_activation_transition_get_requested_features (
WpFeatureActivationTransition * self);
/**
* WP_TYPE_OBJECT:
/*!
* @memberof WpObject
*
* @brief The [WpObject](@ref object_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_OBJECT (wp_object_get_type ())
* @endcode
*
* The #WpObject #GType
*/
#define WP_TYPE_OBJECT (wp_object_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpObject, wp_object, WP, OBJECT, GObject)
/*!
* @memberof WpObject
*
* @brief
* @em parent_class
*/
struct _WpObjectClass
{
GObjectClass parent_class;

98
lib/wp/plugin.c
View File

@@ -6,17 +6,28 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: plugin
* @title: WirePlumber Daemon Plugins
/*!
* @file plugin.c
*/
#define G_LOG_DOMAIN "wp-plugin"
#include "plugin.h"
#include "log.h"
#include "private/registry.h"
/*!
* @memberof WpPlugin
*
* @props @b name
*
* @code
* "name" gchar *
* @endcode
*
* The name of this plugin. Implementations should initialize this in the constructor.
*
* Flags : Read / Write / Construct Only
*/
enum {
PROP_0,
PROP_NAME,
@@ -28,11 +39,12 @@ struct _WpPluginPrivate
GQuark name_quark;
};
/**
* WpPlugin:
/*!
* @struct WpPlugin
* @section plugin_section Plugins
*
* #WpPlugin is a base class for objects that provide functionality to the
* WirePlumber daemon.
* @brief [WpPlugin](@ref plugin_section) is a base class for objects that
* provide functionality to the WirePlumber daemon.
*
* Typically, a plugin is created within a module and then registered to
* make it available for use by the daemon. The daemon is responsible for
@@ -40,13 +52,18 @@ struct _WpPluginPrivate
* the core is connected and the initial discovery of global objects is
* done.
*
* Being a #WpObject subclass, the plugin inherits #WpObject's activation
* system. For most implementations, there is only need for activating one
* Being a [WpObject](@ref object_section) subclass, the plugin inherits
* [WpObject](@ref object_section)'s activation system.
* For most implementations, there is only need for activating one
* feature, %WP_PLUGIN_FEATURE_ENABLED, and this can be done by implementing
* only #WpPluginClass.enable() and #WpPluginClass.disable(). For more advanced
* plugins that need to have more features, you may implement directly the
* functions of #WpObjectClass and ignore the ones of #WpPluginClass.
* only [WpPluginClass](@ref plugin_class_section).[enable](@ref plugin_class_enable_section)() and
* [WpPluginClass](@ref plugin_class_section).[disable](@ref plugin_class_disable_section)().
* For more advanced plugins that need to have more features, you may implement directly the
* functions of [WpObjectClass](@ref object_class_section) and ignore the ones of
* [WpPluginClass](@ref plugin_class_section).
*
*/
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpPlugin, wp_plugin, WP_TYPE_OBJECT)
static void
@@ -104,7 +121,7 @@ wp_plugin_activate_get_next_step (WpObject * object,
WpObjectFeatures missing)
{
/* we only support ENABLED, so this is the only
feature that can be in @missing */
feature that can be in @em missing */
g_return_val_if_fail (missing == WP_PLUGIN_FEATURE_ENABLED,
WP_TRANSITION_STEP_ERROR);
@@ -157,9 +174,9 @@ wp_plugin_class_init (WpPluginClass * klass)
wpobject_class->activate_execute_step = wp_plugin_activate_execute_step;
wpobject_class->deactivate = wp_plugin_deactivate;
/**
/*
* WpPlugin:name:
* The name of this plugin.
* @brief The name of this plugin.
* Implementations should initialize this in the constructor.
*/
g_object_class_install_property (object_class, PROP_NAME,
@@ -168,12 +185,13 @@ wp_plugin_class_init (WpPluginClass * klass)
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
}
/**
* wp_plugin_register:
* @plugin: (transfer full): the plugin
/*!
* @memberof WpPlugin
* @param plugin: (transfer full): the plugin
*
* Registers the plugin to its associated core, making it available for use
* @brief Registers the plugin to its associated core, making it available for use
*/
void
wp_plugin_register (WpPlugin * plugin)
{
@@ -193,13 +211,14 @@ find_plugin_func (gpointer plugin, gpointer name_quark)
return priv->name_quark == GPOINTER_TO_UINT (name_quark);
}
/**
* wp_plugin_find:
* @core: the core
* @plugin_name: the lookup name
/*!
* @memberof WpPlugin
* @param core: the core
* @param plugin_name: the lookup name
*
* Returns: (transfer full) (nullable): the plugin matching the lookup name
* @returns (transfer full) (nullable): the plugin matching the lookup name
*/
WpPlugin *
wp_plugin_find (WpCore * core, const gchar * plugin_name)
{
@@ -213,12 +232,13 @@ wp_plugin_find (WpCore * core, const gchar * plugin_name)
return p ? WP_PLUGIN (p) : NULL;
}
/**
* wp_plugin_get_name:
* @self: the plugin
/*!
* @memberof WpPlugin
* @param self: the plugin
*
* Returns: the name of this plugin
* @returns the name of this plugin
*/
const gchar *
wp_plugin_get_name (WpPlugin * self)
{
@@ -229,21 +249,27 @@ wp_plugin_get_name (WpPlugin * self)
}
/**
* WpPluginClass.enable:
* @self: the plugin
* @transition: the activation transition
* WpPluginClass::enable:
*
* Enables the plugin. The plugin is required to start any operations only
* @section plugin_class_enable_section enable
*
* @param self: the plugin
* @param transition: the activation transition
*
* @brief Enables the plugin. The plugin is required to start any operations only
* when this method is called and not before.
*
* When enabling the plugin is done, you must call wp_object_update_features()
* with %WP_PLUGIN_FEATURE_ENABLED marked as activated, or return an error
* on @transition.
* on @em transition.
*/
/**
* WpPluginClass.disable:
* @self: the plugin
* WpPluginClass::disable:
*
* @section plugin_class_disable_section disable
*
* @param self: the plugin
*
* Disables the plugin. The plugin is required to stop all operations and
* release all resources associated with it.

33
lib/wp/plugin.h
View File

@@ -13,27 +13,42 @@
G_BEGIN_DECLS
/**
* WpPluginFeatures:
* @WP_PLUGIN_FEATURE_ENABLED: enables the plugin
/*!
* @memberof WpPlugin
*
* Flags to be used as #WpObjectFeatures for #WpPlugin subclasses.
* @section plugin_features_section WpPluginFeatures
*
* @brief
* @em WP_PLUGIN_FEATURE_ENABLED: enables the plugin
*
* Flags to be used as [WpObjectFeatures](@ref object_features_section)
* for [WpPlugin](@ref plugin_section) subclasses.
*/
typedef enum { /*< flags >*/
WP_PLUGIN_FEATURE_ENABLED = (1 << 0),
} WpPluginFeatures;
/**
* WP_TYPE_PLUGIN:
/*!
* @memberof WpPlugin
*
* @brief The [WpPlugin](@ref plugin_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_PLUGIN (wp_plugin_get_type ())
* @endcode
*
* The #WpPlugin #GType
*/
#define WP_TYPE_PLUGIN (wp_plugin_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpPlugin, wp_plugin, WP, PLUGIN, WpObject)
/**
* WpPluginClass:
/*!
* @brief
* @em parent_class
* @em enable: See wp_plugin_activate_execute_step()
* @em disable: See wp_plugin_deactivate()
*/
struct _WpPluginClass
{

34
lib/wp/port.c
View File

@@ -5,17 +5,18 @@
*
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: port
* @title: PipeWire Port
/*!
* @file port.c
*/
#define G_LOG_DOMAIN "wp-port"
#include "port.h"
#include "private/pipewire-object-mixin.h"
/*!
* @brief
* @em parent
*/
struct _WpPort
{
WpGlobalProxy parent;
@@ -24,15 +25,19 @@ struct _WpPort
static void wp_port_pw_object_mixin_priv_interface_init (
WpPwObjectMixinPrivInterface * iface);
/**
* WpPort:
/*!
* @struct WpPort
* @section port_section Port
*
* The #WpPort class allows accessing the properties and methods of a
* PipeWire port object (`struct pw_port`).
* @brief The [WpPort](@ref port_section) class allows accessing the properties
* and methods of a PipeWire port object (`struct pw_port`).
*
* A [WpPort](@ref port_section) is constructed internally when a new port appears
* on the PipeWire registry and it is made available through the
* [WpObjectManager](@ref object_manager_section) API.
*
* A #WpPort is constructed internally when a new port appears on the
* PipeWire registry and it is made available through the #WpObjectManager API.
*/
G_DEFINE_TYPE_WITH_CODE (WpPort, wp_port, WP_TYPE_GLOBAL_PROXY,
G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
wp_pw_object_mixin_object_interface_init)
@@ -136,6 +141,13 @@ wp_port_pw_object_mixin_priv_interface_init (
iface->enum_params = wp_port_enum_params;
}
/*!
* @memberof WpPort
* @param self: the port
*
* @returns the current direction of the port
*/
WpDirection
wp_port_get_direction (WpPort * self)
{

23
lib/wp/port.h
View File

@@ -13,10 +13,12 @@
G_BEGIN_DECLS
/**
* WpDirection:
* @WP_DIRECTION_INPUT: a sink, consuming input
* @WP_DIRECTION_OUTPUT: a source, producing output
/*!
* @memberof @WpPort
*
* @brief
* @em WP_DIRECTION_INPUT: a sink, consuming input
* @em WP_DIRECTION_OUTPUT: a source, producing output
*
* The different directions the endpoint can have
*/
@@ -25,10 +27,17 @@ typedef enum {
WP_DIRECTION_OUTPUT,
} WpDirection;
/**
* WP_TYPE_PORT:
/*!
* @memberof @WpPort
*
* @brief The [WpPort](@ref port_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_PORT (wp_port_get_type ())
* @endcode
*
* The #WpPort #GType
*/
#define WP_TYPE_PORT (wp_port_get_type ())
WP_API

8
lib/wp/private/pipewire-object-mixin.h
View File

@@ -131,7 +131,7 @@ struct _WpPwObjectMixinData
GArray *subscribed_ids; /* element-type: guint32 */
};
/* get mixin data (stored as qdata on the @instance) */
/* get mixin data (stored as qdata on the @em instance) */
WpPwObjectMixinData * wp_pw_object_mixin_get_data (gpointer instance);
/****************/
@@ -142,8 +142,8 @@ GPtrArray * wp_pw_object_mixin_get_stored_params (WpPwObjectMixinData * data,
guint32 id);
/* param store manipulation
* @flags: see below
* @param: (transfer full): WpSpaPod* or GPtrArray* */
* @em flags: see below
* @em param: (transfer full): WpSpaPod* or GPtrArray* */
void wp_pw_object_mixin_store_param (WpPwObjectMixinData * data, guint32 id,
guint32 flags, gpointer param);
@@ -151,7 +151,7 @@ void wp_pw_object_mixin_store_param (WpPwObjectMixinData * data, guint32 id,
#define WP_PW_OBJECT_MIXIN_STORE_PARAM_SET(x) ((x) & 0x7fff)
#define WP_PW_OBJECT_MIXIN_STORE_PARAM_APPEND (0xffff)
#define WP_PW_OBJECT_MIXIN_STORE_PARAM_PREPEND (0)
/* @param is a GPtrArray* */
/* @em param is a GPtrArray* */
#define WP_PW_OBJECT_MIXIN_STORE_PARAM_ARRAY (1 << 16)
/* clear the existing array of params before storing */
#define WP_PW_OBJECT_MIXIN_STORE_PARAM_CLEAR (1 << 17)

533
lib/wp/properties.c
View File

@@ -5,37 +5,42 @@
*
* SPDX-License-Identifier: MIT
*/
/*!
* @file properties.c
*/
/**
* SECTION: properties
* @title: PipeWire Properties Dictionary
/*!
* @struct WpProperties
* @section properties_section Properties
*
* #WpProperties is a data structure that contains string key-value pairs,
* which are used to send/receive/attach arbitrary properties to PipeWire
* objects.
* @brief [WpProperties](@ref properties_section) is a data structure that contains
* string key-value pairs, which are used to send/receive/attach arbitrary properties
* to PipeWire objects.
*
* This could be thought of as a hash table with strings as both keys and
* values. However, the reason that this class exists instead of using
* #GHashTable directly is that in reality it wraps the PipeWire native
* <a href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#GHashTable">
* GHashTable</a> directly is that in reality it wraps the PipeWire native
* `struct spa_dict` and `struct pw_properties` and therefore it can be
* easily passed to PipeWire function calls that require a `struct spa_dict *`
* or a `struct pw_properties *` as arguments. Or alternatively, it can easily
* wrap a `struct spa_dict *` or a `struct pw_properties *` that was given
* from the PipeWire API without necessarily doing an expensive copy operation.
*
* #WpProperties normally wraps a `struct pw_properties`, unless it was created
* with wp_properties_new_wrap_dict(), in which case it wraps a
* [WpProperties](@ref properties_section) normally wraps a `struct pw_properties`,
* unless it was created with wp_properties_new_wrap_dict(), in which case it wraps a
* `struct spa_dict` and it is immutable (you cannot add/remove/modify any
* key-value pair).
*
* In most cases, it actually owns the `struct pw_properties`
* internally and manages its lifetime. The exception to that rule is when
* #WpProperties is constructed with wp_properties_new_wrap(), in which case
* the ownership of the `struct pw_properties` remains outside. This must
* [WpProperties](@ref properties_section) is constructed with wp_properties_new_wrap(),
* in which case the ownership of the `struct pw_properties` remains outside. This must
* be used with care, as the `struct pw_properties` may be free'ed externally.
*
* #WpProperties is reference-counted with wp_properties_ref() and
* [WpProperties](@ref properties_section) is reference-counted with wp_properties_ref() and
* wp_properties_unref().
*
*/
#define G_LOG_DOMAIN "wp-properties"
@@ -50,6 +55,11 @@ enum {
FLAG_NO_OWNERSHIP = (1<<2),
};
/*!
* @brief
* @em ref
* @em flags
*/
struct _WpProperties
{
grefcount ref;
@@ -62,13 +72,13 @@ struct _WpProperties
G_DEFINE_BOXED_TYPE(WpProperties, wp_properties, wp_properties_ref, wp_properties_unref)
/**
* wp_properties_new_empty:
/*!
* @memberof WpProperties
* @brief Creates a new empty properties set
*
* Creates a new empty properties set
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_empty (void)
{
@@ -79,16 +89,17 @@ wp_properties_new_empty (void)
return self;
}
/**
* wp_properties_new:
* @key: a property name
/*!
* @memberof WpProperties
* @param key: a property name
* @...: a property value, followed by any number of further property
* key-value pairs, followed by %NULL
*
* Constructs a new properties set that contains the given properties
* @brief Constructs a new properties set that contains the given properties
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new (const gchar * key, ...)
{
@@ -102,15 +113,16 @@ wp_properties_new (const gchar * key, ...)
return self;
}
/**
* wp_properties_new_valist:
* @key: a property name
* @args: the variable arguments passed to wp_properties_new()
/*!
* @memberof WpProperties
* @param key: a property name
* @param args: the variable arguments passed to wp_properties_new()
*
* This is the `va_list` version of wp_properties_new()
* @brief This is the `va_list` version of wp_properties_new()
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_valist (const gchar * key, va_list args)
{
@@ -127,16 +139,17 @@ wp_properties_new_valist (const gchar * key, va_list args)
return self;
}
/**
* wp_properties_new_string:
* @str: a string containing a whitespace separated list of key=value pairs
/*!
* @memberof WpProperties
* @param str: a string containing a whitespace separated list of key=value pairs
* (ex. "key1=value1 key2=value2")
*
* Constructs a new properties set that contains the properties that can
* @brief Constructs a new properties set that contains the properties that can
* be parsed from the given string
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_string (const gchar * str)
{
@@ -151,25 +164,26 @@ wp_properties_new_string (const gchar * str)
return self;
}
/**
* wp_properties_new_wrap:
* @props: a native `pw_properties` structure to wrap
/*!
* @memberof WpProperties
* @param props: a native `pw_properties` structure to wrap
*
* Constructs a new #WpProperties that wraps the given @props structure,
* allowing reading properties on that @props structure through
* the #WpProperties API.
* @brief Constructs a new [WpProperties](@ref properties_section) that wraps the given @em props structure,
* allowing reading properties on that @em props structure through
* the [WpProperties](@ref properties_section) API.
*
* Care must be taken when using this function, since the returned #WpProperties
* object does not own the @props structure. Therefore, if the owner decides
* to free @props, the returned #WpProperties will crash when used. In addition,
* the returned #WpProperties object will not try to free @props when destroyed.
* Care must be taken when using this function, since the returned [WpProperties](@ref properties_section)
* object does not own the @em props structure. Therefore, if the owner decides
* to free @em props, the returned [WpProperties](@ref properties_section) will crash when used. In addition,
* the returned [WpProperties](@ref properties_section) object will not try to free @em props when destroyed.
*
* Furthermore, note that the returned #WpProperties object is immutable. That
* Furthermore, note that the returned [WpProperties](@ref properties_section) object is immutable. That
* means that you cannot add or modify any properties on it, unless you make
* a copy first.
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_wrap (const struct pw_properties * props)
{
@@ -184,19 +198,20 @@ wp_properties_new_wrap (const struct pw_properties * props)
return self;
}
/**
* wp_properties_new_take:
* @props: a native `pw_properties` structure to wrap
/*!
* @memberof WpProperties
* @param props: a native `pw_properties` structure to wrap
*
* Constructs a new #WpProperties that wraps the given @props structure,
* allowing reading & writing properties on that @props structure through
* the #WpProperties API.
* @brief Constructs a new [WpProperties](@ref properties_section) that wraps the given @em props structure,
* allowing reading & writing properties on that @em props structure through
* the [WpProperties](@ref properties_section) API.
*
* In constrast with wp_properties_new_wrap(), this function assumes ownership
* of the @props structure, so it will try to free @props when it is destroyed.
* of the @em props structure, so it will try to free @em props when it is destroyed.
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_take (struct pw_properties * props)
{
@@ -211,15 +226,16 @@ wp_properties_new_take (struct pw_properties * props)
return self;
}
/**
* wp_properties_new_copy:
* @props: a native `pw_properties` structure to copy
/*!
* @memberof WpProperties
* @param props: a native `pw_properties` structure to copy
*
* Constructs a new #WpProperties that contains a copy of all the properties
* contained in the given @props structure.
* @brief Constructs a new [WpProperties](@ref properties_section) that contains a copy of all the properties
* contained in the given @em props structure.
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_copy (const struct pw_properties * props)
{
@@ -234,23 +250,24 @@ wp_properties_new_copy (const struct pw_properties * props)
return self;
}
/**
* wp_properties_new_wrap_dict:
* @dict: a native `spa_dict` structure to wrap
/*!
* @memberof WpProperties
* @param dict: a native `spa_dict` structure to wrap
*
* Constructs a new #WpProperties that wraps the given @dict structure,
* allowing reading properties from that @dict through the #WpProperties API.
* @brief Constructs a new [WpProperties](@ref properties_section) that wraps the given @em dict structure,
* allowing reading properties from that @em dict through the [WpProperties](@ref properties_section) API.
*
* Note that the returned object does not own the @dict, so care must be taken
* not to free it externally while this #WpProperties object is alive.
* Note that the returned object does not own the @em dict, so care must be taken
* not to free it externally while this [WpProperties](@ref properties_section) object is alive.
*
* In addition, note that the returned #WpProperties object is immutable. That
* In addition, note that the returned [WpProperties](@ref properties_section) object is immutable. That
* means that you cannot add or modify any properties on it, since there is
* no defined method for modifying a `struct spa_dict`. If you need to change
* this properties set later, you should make a copy with wp_properties_copy().
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_wrap_dict (const struct spa_dict * dict)
{
@@ -265,15 +282,16 @@ wp_properties_new_wrap_dict (const struct spa_dict * dict)
return self;
}
/**
* wp_properties_new_copy_dict:
* @dict: a native `spa_dict` structure to copy
/*!
* @memberof WpProperties
* @param dict: a native `spa_dict` structure to copy
*
* Constructs a new #WpProperties that contains a copy of all the properties
* contained in the given @dict structure.
* @brief Constructs a new [WpProperties](@ref properties_section) that contains a copy of all the properties
* contained in the given @em dict structure.
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_new_copy_dict (const struct spa_dict * dict)
{
@@ -288,15 +306,16 @@ wp_properties_new_copy_dict (const struct spa_dict * dict)
return self;
}
/**
* wp_properties_copy:
* @other: a properties object
/*!
* @memberof WpProperties
* @param other: a properties object
*
* Constructs and returns a new #WpProperties object that contains a copy
* of all the properties contained in @other.
* @brief Constructs and returns a new [WpProperties](@ref properties_section) object that contains a copy
* of all the properties contained in @em other.
*
* Returns: (transfer full): the newly constructed properties set
* @returns (transfer full): the newly constructed properties set
*/
WpProperties *
wp_properties_copy (WpProperties * other)
{
@@ -311,12 +330,13 @@ wp_properties_free (WpProperties * self)
g_slice_free (WpProperties, self);
}
/**
* wp_properties_ref:
* @self: a properties object
/*!
* @memberof WpProperties
* @param self: a properties object
*
* Returns: (transfer full): @self with an additional reference count on it
* @returns (transfer full): @em self with an additional reference count on it
*/
WpProperties *
wp_properties_ref (WpProperties * self)
{
@@ -324,13 +344,14 @@ wp_properties_ref (WpProperties * self)
return self;
}
/**
* wp_properties_unref:
* @self: (transfer full): a properties object
/*!
* @memberof WpProperties
* @param self: (transfer full): a properties object
*
* 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_properties_unref (WpProperties * self)
{
@@ -338,20 +359,21 @@ wp_properties_unref (WpProperties * self)
wp_properties_free (self);
}
/**
* wp_properties_ensure_unique_owner:
* @self: (transfer full): a properties object
/*!
* @memberof WpProperties
* @param self: (transfer full): a properties object
*
* Ensures that the given properties set is uniquely owned, which means:
* @brief Ensures that the given properties set is uniquely owned, which means:
* - its reference count is 1
* - it is not wrapping a native `spa_dict` or `pw_properties` object
*
* If @self is not uniquely owned already, then it is unrefed and a copy of
* it is returned instead. You should always consider @self as unsafe to use
* If @em self is not uniquely owned already, then it is unrefed and a copy of
* it is returned instead. You should always consider @em self as unsafe to use
* after this call and you should use the returned object instead.
*
* Returns: (transfer full): the uniquely owned properties object
* @returns (transfer full): the uniquely owned properties object
*/
WpProperties *
wp_properties_ensure_unique_owner (WpProperties * self)
{
@@ -365,17 +387,18 @@ wp_properties_ensure_unique_owner (WpProperties * self)
return self;
}
/**
* wp_properties_update:
* @self: a properties object
* @props: a properties set that contains properties to update
/*!
* @memberof WpProperties
* @param self: a properties object
* @param props: a properties set that contains properties to update
*
* Updates (adds new or modifies existing) properties in @self, using the
* given @props as a source. Any properties that are not contained in @props
* @brief Updates (adds new or modifies existing) properties in @em self, using the
* given @em props as a source. Any properties that are not contained in @em props
* are left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_update (WpProperties * self, WpProperties * props)
{
@@ -386,17 +409,18 @@ wp_properties_update (WpProperties * self, WpProperties * props)
return pw_properties_update (self->props, wp_properties_peek_dict (props));
}
/**
* wp_properties_update_from_dict:
* @self: a properties object
* @dict: a `spa_dict` that contains properties to update
/*!
* @memberof WpProperties
* @param self: a properties object
* @param dict: a `spa_dict` that contains properties to update
*
* Updates (adds new or modifies existing) properties in @self, using the
* given @dict as a source. Any properties that are not contained in @dict
* @brief Updates (adds new or modifies existing) properties in @em self, using the
* given @em dict as a source. Any properties that are not contained in @em dict
* are left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_update_from_dict (WpProperties * self,
const struct spa_dict * dict)
@@ -408,18 +432,19 @@ wp_properties_update_from_dict (WpProperties * self,
return pw_properties_update (self->props, dict);
}
/**
* wp_properties_add:
* @self: a properties object
* @props: a properties set that contains properties to add
/*!
* @memberof WpProperties
* @param self: a properties object
* @param props: a properties set that contains properties to add
*
* Adds new properties in @self, using the given @props as a source.
* Properties (keys) from @props that are already contained in @self
* @brief Adds new properties in @em self, using the given @em props as a source.
* Properties (keys) from @em props that are already contained in @em self
* are not modified, unlike what happens with wp_properties_update().
* Properties in @self that are not contained in @props are left untouched.
* Properties in @em self that are not contained in @em props are left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_add (WpProperties * self, WpProperties * props)
{
@@ -430,18 +455,19 @@ wp_properties_add (WpProperties * self, WpProperties * props)
return pw_properties_add (self->props, wp_properties_peek_dict (props));
}
/**
* wp_properties_add_from_dict:
* @self: a properties object
* @dict: a `spa_dict` that contains properties to add
/*!
* @memberof WpProperties
* @param self: a properties object
* @param dict: a `spa_dict` that contains properties to add
*
* Adds new properties in @self, using the given @dict as a source.
* Properties (keys) from @dict that are already contained in @self
* @brief Adds new properties in @em self, using the given @em dict as a source.
* Properties (keys) from @em dict that are already contained in @em self
* are not modified, unlike what happens with wp_properties_update_from_dict().
* Properties in @self that are not contained in @dict are left untouched.
* Properties in @em self that are not contained in @em dict are left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_add_from_dict (WpProperties * self,
const struct spa_dict * dict)
@@ -453,20 +479,21 @@ wp_properties_add_from_dict (WpProperties * self,
return pw_properties_add (self->props, dict);
}
/**
* wp_properties_update_keys:
* @self: a properties set
* @props: a properties set that contains properties to update
* @key1: a property to update
/*!
* @memberof WpProperties
* @param self: a properties set
* @param props: a properties set that contains properties to update
* @param key1: a property to update
* @...: a list of additional properties to update, followed by %NULL
*
* Updates (adds new or modifies existing) properties in @self, using the
* given @props as a source.
* @brief Updates (adds new or modifies existing) properties in @em self, using the
* given @em props as a source.
* Unlike wp_properties_update(), this function only updates properties that
* have one of the specified keys; the rest is left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_update_keys (WpProperties * self, WpProperties * props,
const gchar * key1, ...)
@@ -487,20 +514,21 @@ wp_properties_update_keys (WpProperties * self, WpProperties * props,
return changed;
}
/**
* wp_properties_update_keys_from_dict:
* @self: a properties set
* @dict: a `spa_dict` that contains properties to update
* @key1: a property to update
/*!
* @memberof WpProperties
* @param self: a properties set
* @param dict: a `spa_dict` that contains properties to update
* @param key1: a property to update
* @...: a list of additional properties to update, followed by %NULL
*
* Updates (adds new or modifies existing) properties in @self, using the
* given @dict as a source.
* @brief Updates (adds new or modifies existing) properties in @em self, using the
* given @em dict as a source.
* Unlike wp_properties_update_from_dict(), this function only updates
* properties that have one of the specified keys; the rest is left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_update_keys_from_dict (WpProperties * self,
const struct spa_dict * dict, const gchar * key1, ...)
@@ -521,17 +549,18 @@ wp_properties_update_keys_from_dict (WpProperties * self,
return changed;
}
/**
* wp_properties_update_keys_array:
* @self: a properties set
* @props: a properties set that contains properties to update
* @keys: (array zero-terminated=1): the properties to update
/*!
* @memberof WpProperties
* @param self: a properties set
* @param props: a properties set that contains properties to update
* @param keys: (array zero-terminated=1): the properties to update
*
* The same as wp_properties_update_keys(), using a NULL-terminated array
* @brief The same as wp_properties_update_keys(), using a NULL-terminated array
* for specifying the keys to update
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_update_keys_array (WpProperties * self, WpProperties * props,
const gchar * keys[])
@@ -544,19 +573,20 @@ wp_properties_update_keys_array (WpProperties * self, WpProperties * props,
wp_properties_peek_dict (props), keys);
}
/**
* wp_properties_add_keys:
* @self: a properties set
* @props: a properties set that contains properties to add
* @key1: a property to add
/*!
* @memberof WpProperties
* @param self: a properties set
* @param props: a properties set that contains properties to add
* @param key1: a property to add
* @...: a list of additional properties to add, followed by %NULL
*
* Adds new properties in @self, using the given @props as a source.
* @brief Adds new properties in @em self, using the given @em props as a source.
* Unlike wp_properties_add(), this function only adds properties that
* have one of the specified keys; the rest is left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_add_keys (WpProperties * self, WpProperties * props,
const gchar * key1, ...)
@@ -579,19 +609,20 @@ wp_properties_add_keys (WpProperties * self, WpProperties * props,
return changed;
}
/**
* wp_properties_add_keys_from_dict:
* @self: a properties set
* @dict: a `spa_dict` that contains properties to add
* @key1: a property to add
/*!
* @memberof WpProperties
* @param self: a properties set
* @param dict: a `spa_dict` that contains properties to add
* @param key1: a property to add
* @...: a list of additional properties to add, followed by %NULL
*
* Adds new properties in @self, using the given @dict as a source.
* @brief Adds new properties in @em self, using the given @em dict as a source.
* Unlike wp_properties_add_from_dict(), this function only adds
* properties that have one of the specified keys; the rest is left untouched.
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_add_keys_from_dict (WpProperties * self,
const struct spa_dict * dict, const gchar * key1, ...)
@@ -614,17 +645,18 @@ wp_properties_add_keys_from_dict (WpProperties * self,
return changed;
}
/**
* wp_properties_add_keys_array:
* @self: a properties set
* @props: a properties set that contains properties to add
* @keys: (array zero-terminated=1): the properties to add
/*!
* @memberof WpProperties
* @param self: a properties set
* @param props: a properties set that contains properties to add
* @param keys: (array zero-terminated=1): the properties to add
*
* The same as wp_properties_add_keys(), using a NULL-terminated array
* @brief The same as wp_properties_add_keys(), using a NULL-terminated array
* for specifying the keys to add
*
* Returns: the number of properties that were changed
* @returns the number of properties that were changed
*/
gint
wp_properties_add_keys_array (WpProperties * self, WpProperties * props,
const gchar * keys[])
@@ -637,14 +669,15 @@ wp_properties_add_keys_array (WpProperties * self, WpProperties * props,
wp_properties_peek_dict (props), keys);
}
/**
* wp_properties_get:
* @self: a properties object
* @key: a property key
/*!
* @memberof WpProperties
* @param self: a properties object
* @param key: a property key
*
* Returns: (transfer none) (nullable): the value of the property identified
* with @key, or %NULL if this property is not contained in @self
* @returns (transfer none) (nullable): the value of the property identified
* with @em key, or %NULL if this property is not contained in @em self
*/
const gchar *
wp_properties_get (WpProperties * self, const gchar * key)
{
@@ -654,21 +687,22 @@ wp_properties_get (WpProperties * self, const gchar * key)
return spa_dict_lookup (wp_properties_peek_dict (self), key);
}
/**
* wp_properties_set:
* @self: a properties object
* @key: a property key
* @value: (nullable): a property value
/*!
* @memberof WpProperties
* @param self: a properties object
* @param key: a property key
* @param value: (nullable): a property value
*
* Sets the given property @key - @value pair on @self. If the property
* @brief Sets the given property @em key - @em value pair on @em self. If the property
* already existed, the value is overwritten with the new one.
*
* If the @value is %NULL, then the specified property is removed from @self
* If the @em value is %NULL, then the specified property is removed from @em self
*
* Returns: %1 if the property was changed. %0 if nothing was changed because
* @returns %1 if the property was changed. %0 if nothing was changed because
* the property already existed with the same value or because the key to
* remove did not exist.
*/
gint
wp_properties_set (WpProperties * self, const gchar * key,
const gchar * value)
@@ -680,20 +714,21 @@ wp_properties_set (WpProperties * self, const gchar * key,
return pw_properties_set (self->props, key, value);
}
/**
* wp_properties_setf:
* @self: a properties object
* @key: a property key
* @format: a printf-style format to be formatted and set as a value for
* this property @key
* @...: arguments for @format
/*!
* @memberof WpProperties
* @param self: a properties object
* @param key: a property key
* @param format: a printf-style format to be formatted and set as a value for
* this property @em key
* @...: arguments for @em format
*
* Formats the given @format string with the specified arguments and sets the
* result as a value of the property specified with @key
* @brief Formats the given @em format string with the specified arguments and sets the
* result as a value of the property specified with @em key
*
* Returns: %1 if the property was changed. %0 if nothing was changed because
* @returns %1 if the property was changed. %0 if nothing was changed because
* the property already existed with the same value
*/
gint
wp_properties_setf (WpProperties * self, const gchar * key,
const gchar * format, ...)
@@ -708,19 +743,20 @@ wp_properties_setf (WpProperties * self, const gchar * key,
return res;
}
/**
* wp_properties_setf_valist:
* @self: a properties object
* @key: a property key
* @format: a printf-style format to be formatted and set as a value for
* this property @key
* @args: the variable arguments passed to wp_properties_setf()
/*!
* @memberof WpProperties
* @param self: a properties object
* @param key: a property key
* @param format: a printf-style format to be formatted and set as a value for
* this property @em key
* @param args: the variable arguments passed to wp_properties_setf()
*
* This is the `va_list` version of wp_properties_setf()
* @brief This is the `va_list` version of wp_properties_setf()
*
* Returns: %1 if the property was changed. %0 if nothing was changed because
* @returns %1 if the property was changed. %0 if nothing was changed because
* the property already existed with the same value
*/
gint
wp_properties_setf_valist (WpProperties * self, const gchar * key,
const gchar * format, va_list args)
@@ -793,15 +829,16 @@ static const WpIteratorMethods dict_iterator_methods = {
.finalize = dict_iterator_finalize,
};
/**
* wp_properties_new_iterator:
* @self: a properties object
/*!
* @memberof WpProperties
* @param self: a properties object
*
* Returns: (transfer full): an iterator that iterates over the properties.
* @returns (transfer full): an iterator that iterates over the properties.
* Use wp_properties_iterator_item_get_key() and
* wp_properties_iterator_item_get_value() to parse the items returned by
* this iterator.
*/
WpIterator *
wp_properties_new_iterator (WpProperties * self)
{
@@ -818,13 +855,16 @@ wp_properties_new_iterator (WpProperties * self)
return g_steal_pointer (&it);
}
/**
* wp_properties_iterator_item_get_key:
* @item: a #GValue that was returned from the #WpIterator of
/*!
* @memberof WpProperties
* @param item: a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue">
* GValue</a> that was returned from the [WpProperties](@ref properties_section) of
* wp_properties_new_iterator()
*
* Returns: (transfer none): the property key of the @item
* @returns (transfer none): the property key of the @em item
*/
const gchar *
wp_properties_iterator_item_get_key (const GValue * item)
{
@@ -833,13 +873,17 @@ wp_properties_iterator_item_get_key (const GValue * item)
return dict_item->key;
}
/**
* wp_properties_iterator_item_get_value:
* @item: a #GValue that was returned from the #WpIterator of
/*!
* @memberof WpProperties
*
* @param item: a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue">
* GValue</a> that was returned from the [WpProperties](@ref properties_section) of
* wp_properties_new_iterator()
*
* Returns: (transfer none): the property value of the @item
* @returns (transfer none): the property value of the @em item
*/
const gchar *
wp_properties_iterator_item_get_value (const GValue * item)
{
@@ -848,6 +892,11 @@ wp_properties_iterator_item_get_value (const GValue * item)
return dict_item->value;
}
/*!
* @memberof WpProperties
* @param self: a properties object
*
*/
void
wp_properties_sort (WpProperties * self)
{
@@ -858,12 +907,13 @@ wp_properties_sort (WpProperties * self)
return spa_dict_qsort (&self->props->dict);
}
/**
* wp_properties_peek_dict:
* @self: a properties object
/*!
* @memberof WpProperties
* @param self: a properties object
*
* Returns: (transfer none): the internal properties set as a `struct spa_dict *`
* @returns (transfer none): the internal properties set as a `struct spa_dict *`
*/
const struct spa_dict *
wp_properties_peek_dict (WpProperties * self)
{
@@ -872,13 +922,14 @@ wp_properties_peek_dict (WpProperties * self)
return (self->flags & FLAG_IS_DICT) ? self->dict : &self->props->dict;
}
/**
* wp_properties_to_pw_properties:
* @self: a properties object
/*!
* @memberof WpProperties
* @param self: a properties object
*
* Returns: (transfer full): a copy of the properties in @self
* @returns (transfer full): a copy of the properties in @em self
* as a `struct pw_properties`
*/
struct pw_properties *
wp_properties_to_pw_properties (WpProperties * self)
{
@@ -887,48 +938,50 @@ wp_properties_to_pw_properties (WpProperties * self)
return pw_properties_new_dict (wp_properties_peek_dict (self));
}
/**
* wp_properties_unref_and_take_pw_properties:
* @self: (transfer full): a properties object
/*!
* @memberof WpProperties
* @param self: (transfer full): a properties object
*
* Similar to wp_properties_to_pw_properties(), but this method avoids making
* @brief Similar to wp_properties_to_pw_properties(), but this method avoids making
* a copy of the properties by returning the `struct pw_properties` that is
* stored internally and then freeing the #WpProperties wrapper.
* stored internally and then freeing the [WpProperties](@ref properties_section) wrapper.
*
* If @self is not uniquely owned (see wp_properties_ensure_unique_owner()),
* If @em self is not uniquely owned (see wp_properties_ensure_unique_owner()),
* then this method does make a copy and is the same as
* wp_properties_to_pw_properties(), performance-wise.
*
* Returns: (transfer full): the properties in @self as a `struct pw_properties`
* @returns (transfer full): the properties in @em self as a `struct pw_properties`
*/
struct pw_properties *
wp_properties_unref_and_take_pw_properties (WpProperties * self)
{
g_return_val_if_fail (self != NULL, NULL);
g_autoptr (WpProperties) unique = wp_properties_ensure_unique_owner (self);
/* set the flag so that unref-ing @unique will not destroy unique->props */
/* set the flag so that unref-ing @em unique will not destroy unique->props */
unique->flags = FLAG_NO_OWNERSHIP;
return unique->props;
}
/**
* wp_properties_matches:
* @self: a properties object
* @other: a set of properties to match
/*!
* @memberof WpProperties
* @param self: a properties object
* @param other: a set of properties to match
*
* Checks if all property values contained in @other are matching with the
* values in @self.
* @brief Checks if all property values contained in @em other are matching with the
* values in @em self.
*
* If a property is contained in @other and not in @self, the result is not
* If a property is contained in @em other and not in @em self, the result is not
* matched. If a property is contained in both sets, then the value of the
* property in @other is interpreted as a glob-style pattern
* (using g_pattern_match_simple()) and the value in @self is checked to
* property in @em other is interpreted as a glob-style pattern
* (using g_pattern_match_simple()) and the value in @em self is checked to
* see if it matches with this pattern.
*
* Returns: %TRUE if all matches were successfull, %FALSE if at least one
* @returns %TRUE if all matches were successfull, %FALSE if at least one
* property value did not match
*/
gboolean
wp_properties_matches (WpProperties * self, WpProperties *other)
{

13
lib/wp/properties.h
View File

@@ -18,10 +18,17 @@ G_BEGIN_DECLS
struct pw_properties;
struct spa_dict;
/**
* WP_TYPE_PROPERTIES:
/*!
* @memberof WpProperties
*
* @brief The [WpProperties](@ref properties_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_PROPERTIES (wp_properties_get_type ())
* @endcode
*
* The #WpProperties #GType
*/
#define WP_TYPE_PROPERTIES (wp_properties_get_type ())
WP_API

209
lib/wp/proxy-interfaces.c
View File

@@ -5,26 +5,78 @@
*
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: proxy-interfaces
* @title: PipeWire Object Proxy Interfaces
/*!
* @file proxy-interfaces.c
*/
#define G_LOG_DOMAIN "wp-proxy-ifaces"
#include "proxy-interfaces.h"
#include "properties.h"
/**
* WpPipewireObject:
/*!
* @section proxy_interfaces_section PipeWire Object Proxy Interfaces
*
* An interface for standard PipeWire objects. The common characteristic
* @struct WpPipewireObject
* @section pipewire_object_section PipeWire Object
*
* @brief An interface for standard PipeWire objects. The common characteristic
* of all objects that implement this interface is the presence of
* an "info" structure that contains additional properties for this object
* (in the form of a spa_dict / pw_properties) and optionally also
* some parameters that can be enumerated and set on the object.
*
* @section pipewire_object_signals_section Signals
*
* @b params-changed
*
* @code
* params_changed_callback (WpPipewireObject * self,
* guint id,
* gpointer user_data)
* @endcode
*
* Emitted when the params for id have changed. On proxies that cache params from a remote object,
* this is emitted after the cached values have changed.
*
* You can expect this to be emitted only when the relevant WP_PIPEWIRE_OBJECT_FEATURE_PARAM_*
* has been activated.
*
* @b Parameters:
*
* @arg `self` - the pipewire object
* @arg `is` - the parameter id
* @arg `user_data`
*
* Flags: Run First
*
* @section plugin_props_section Properties
*
* @b native-info
*
* @code
* "native-info" gpointer
* @endcode
*
* Flags : Read
*
* @b param-info
*
* @code
* "param-info" GVariant *
* @endcode
*
* Flags : Read
*
* @b properties
*
* @code
* "properties" WpProperties *
* @endcode
*
* Flags : Read
*
*/
G_DEFINE_INTERFACE (WpPipewireObject, wp_pipewire_object, WP_TYPE_PROXY)
static void
@@ -45,12 +97,12 @@ wp_pipewire_object_default_init (WpPipewireObjectInterface * iface)
"The param info of the object", G_VARIANT_TYPE ("a{ss}"), NULL,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
/*
* WpPipewireObject::params-changed:
* @self: the pipewire object
* @id: the parameter id
*
* Emitted when the params for @id have changed. On proxies that cache
* @brief Emitted when the params for @em id have changed. On proxies that cache
* params from a remote object, this is emitted after the cached values
* have changed.
*
@@ -61,15 +113,16 @@ wp_pipewire_object_default_init (WpPipewireObjectInterface * iface)
G_SIGNAL_RUN_FIRST, 0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_UINT);
}
/**
* wp_pipewire_object_get_native_info:
* @self: the pipewire object
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: (nullable): the native pipewire info structure of this object
* @returns (nullable): the native pipewire info structure of this object
* (pw_node_info, pw_port_info, etc...)
*/
gconstpointer
wp_pipewire_object_get_native_info (WpPipewireObject * self)
{
@@ -80,15 +133,16 @@ wp_pipewire_object_get_native_info (WpPipewireObject * self)
return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_native_info (self);
}
/**
* wp_pipewire_object_get_properties:
* @self: the pipewire object
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: (transfer full): the pipewire properties of this object;
* @returns (transfer full): the pipewire properties of this object;
* normally these are the properties that are part of the info structure
*/
WpProperties *
wp_pipewire_object_get_properties (WpPipewireObject * self)
{
@@ -99,17 +153,18 @@ wp_pipewire_object_get_properties (WpPipewireObject * self)
return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_properties (self);
}
/**
* wp_pipewire_object_new_properties_iterator:
* @self: the pipewire object
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
* @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: (transfer full): an iterator that iterates over the pipewire
* @returns (transfer full): an iterator that iterates over the pipewire
* properties of this object. Use wp_properties_iterator_item_get_key() and
* wp_properties_iterator_item_get_value() to parse the items returned by
* this iterator.
*/
WpIterator *
wp_pipewire_object_new_properties_iterator (WpPipewireObject * self)
{
@@ -118,24 +173,26 @@ wp_pipewire_object_new_properties_iterator (WpPipewireObject * self)
return properties ? wp_properties_new_iterator (properties) : NULL;
}
/**
* wp_pipewire_object_get_property:
* @self: the pipewire object
* @key: the property name
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
* @param key: the property name
*
* Returns the value of a single pipewire property. This is the same as getting
* @brief Returns the value of a single pipewire property. This is the same as getting
* the whole properties structure with wp_pipewire_object_get_properties() and
* accessing a single property with wp_properties_get(), but saves one call
* and having to clean up the #WpProperties reference count afterwards.
* and having to clean up the [WpProperties](@ref properties_section)
* reference count afterwards.
*
* The value is owned by the proxy, but it is guaranteed to stay alive
* until execution returns back to the event loop.
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: (transfer none) (nullable): the value of the pipewire property @key
* @returns (transfer none) (nullable): the value of the pipewire property @em key
* or %NULL if the property doesn't exist
*/
const gchar *
wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
{
@@ -144,11 +201,11 @@ wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
return properties ? wp_properties_get (properties, key) : NULL;
}
/**
* wp_pipewire_object_get_param_info:
* @self: the pipewire object
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
*
* Returns the available parameters of this pipewire object. The return value
* @brief Returns the available parameters of this pipewire object. The return value
* is a variant of type `a{ss}`, where the key of each map entry is a spa param
* type id (the same ids that you can pass in wp_pipewire_object_enum_params())
* and the value is a string that can contain the following letters,
@@ -163,9 +220,10 @@ wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
*
* Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
*
* Returns: (transfer full) (nullable): a variant of type `a{ss}` or %NULL
* @returns (transfer full) (nullable): a variant of type `a{ss}` or %NULL
* if the object does not support params at all
*/
GVariant *
wp_pipewire_object_get_param_info (WpPipewireObject * self)
{
@@ -176,20 +234,22 @@ wp_pipewire_object_get_param_info (WpPipewireObject * self)
return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_param_info (self);
}
/**
* wp_pipewire_object_enum_params:
* @self: the pipewire object
* @id: (nullable): the parameter id to enumerate or %NULL for all parameters
* @filter: (nullable): a param filter or %NULL
* @cancellable: (nullable): a cancellable for the async operation
* @callback: (scope async): a callback to call with the result
* @user_data: (closure): data to pass to @callback
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
* @param id: (nullable): the parameter id to enumerate or %NULL for all parameters
* @param filter: (nullable): a param filter or %NULL
* @param cancellable: (nullable): a cancellable for the async operation
* @param callback: (scope async): a callback to call with the result
* @param user_data: (closure): data to pass to @em callback
*
* Enumerate object parameters. This will asynchronously return the result,
* or an error, by calling the given @callback. The result is going to
* be a #WpIterator containing #WpSpaPod objects, which can be retrieved
* @brief Enumerate object parameters. This will asynchronously return the result,
* or an error, by calling the given @em callback. The result is going to
* be a [WpIterator](@ref iterator_section) containing
* [WpSpaPod](@ref spa_pod_section) objects, which can be retrieved
* with wp_pipewire_object_enum_params_finish().
*/
void
wp_pipewire_object_enum_params (WpPipewireObject * self, const gchar * id,
WpSpaPod *filter, GCancellable * cancellable,
@@ -202,16 +262,17 @@ wp_pipewire_object_enum_params (WpPipewireObject * self, const gchar * id,
cancellable, callback, user_data);
}
/**
* wp_pipewire_object_enum_params_finish:
* @self: the pipewire object
* @res: the async result
* @error: (out) (optional): the reported error of the operation, if any
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
* @param res: the async result
* @param error: (out) (optional): the reported error of the operation, if any
*
* Returns: (transfer full) (nullable): an iterator to iterate over the
* @returns (transfer full) (nullable): an iterator to iterate over the
* collected params, or %NULL if the operation resulted in error;
* the items in the iterator are #WpSpaPod
* the items in the iterator are [WpSpaPod](@ref spa_pod_section)
*/
WpIterator *
wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
GAsyncResult * res, GError ** error)
@@ -224,16 +285,16 @@ wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
error);
}
/**
* wp_pipewire_object_enum_cached_params
* @self: the pipewire object
* @id: the parameter id to enumerate
* @filter: (nullable): a param filter or %NULL
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
* @param id: the parameter id to enumerate
* @param filter: (nullable): a param filter or %NULL
*
* This method can be used to retrieve object parameters in a synchronous way
* @brief This method can be used to retrieve object parameters in a synchronous way
* (in contrast with wp_pipewire_object_enum_params(), which is async),
* provided that the `WP_PIPEWIRE_OBJECT_FEATURE_PARAM_<something>` feature
* that corresponds to the specified @id has been activated earlier.
* that corresponds to the specified @em id has been activated earlier.
* These features enable monitoring and caching of params underneath, so that
* they are always available for retrieval with this method.
*
@@ -242,10 +303,11 @@ wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
* able to update them yet, so if you really need up-to-date information you
* should only rely on wp_pipewire_object_enum_params() instead.
*
* Returns: (transfer full) (nullable): an iterator to iterate over cached
* parameters, or %NULL if paramteres for this @id are not cached;
* the items in the iterator are #WpSpaPod
* @returns (transfer full) (nullable): an iterator to iterate over cached
* parameters, or %NULL if paramteres for this @em id are not cached;
* the items in the iterator are [WpSpaPod](@ref spa_pod_section)
*/
WpIterator *
wp_pipewire_object_enum_params_sync (WpPipewireObject * self,
const gchar * id, WpSpaPod * filter)
@@ -258,17 +320,18 @@ wp_pipewire_object_enum_params_sync (WpPipewireObject * self,
filter);
}
/**
* wp_pipewire_object_set_param:
* @self: the pipewire object
* @id: the parameter id to set
* @flags: optional flags or 0
* @param: (transfer full): the parameter to set
/*!
* @memberof WpPipewireObject
* @param self: the pipewire object
* @param id: the parameter id to set
* @param flags: optional flags or 0
* @param param: (transfer full): the parameter to set
*
* Sets a parameter on the object.
* @brief Sets a parameter on the object.
*
* Returns: %TRUE on success, %FALSE if setting the param failed
* @returns %TRUE on success, %FALSE if setting the param failed
*/
gboolean
wp_pipewire_object_set_param (WpPipewireObject * self, const gchar * id,
guint32 flags, WpSpaPod * param)

17
lib/wp/proxy-interfaces.h
View File

@@ -15,16 +15,27 @@
G_BEGIN_DECLS
/**
* WP_TYPE_PIPEWIRE_OBJECT:
/*!
* @memberof WpPipewireObject
*
* @brief The [WpPipewireObject](@ref pipewire_object_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_PIPEWIRE_OBJECT (wp_pipewire_object_get_type ())
* @endcode
*
* The #WpPipewireObject #GType
*/
#define WP_TYPE_PIPEWIRE_OBJECT (wp_pipewire_object_get_type ())
WP_API
G_DECLARE_INTERFACE (WpPipewireObject, wp_pipewire_object,
WP, PIPEWIRE_OBJECT, WpProxy)
/*!
* @brief
* @em parent_iface
*/
struct _WpPipewireObjectInterface
{
GTypeInterface parent_iface;

125
lib/wp/proxy.c
View File

@@ -5,12 +5,9 @@
*
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: proxy
* @title: PipeWire Object Proxy
/*!
* @file proxy.c
*/
#define G_LOG_DOMAIN "wp-proxy"
#include "proxy.h"
@@ -28,12 +25,82 @@ struct _WpProxyPrivate
struct spa_hook listener;
};
/*!
* @memberof WpProxy
*
* @props @b bound-id
*
* @code
* "bound-id" guint
* @endcode
*
* Flags : Read
*
* @props @b pw-proxy
*
* @code
* "pw-proxy" gpointer
* @endcode
*
* Flags : Read
*
*/
enum {
PROP_0,
PROP_BOUND_ID,
PROP_PW_PROXY,
};
/*!
* @memberof WpProxy
*
* @signal @b bound
*
* @code
* bound_callback (WpProxy * self,
* guint object,
* gpointer user_data)
* @endcode
*
* @b Parameters:
*
* @arg `self`
* @arg `object`
* @arg `user_data`
*
* Flags: Run First
*
* @signal @b pw-proxy-created
*
* @code
* pw_proxy_created_callback (WpProxy * self,
* gpointer object,
* gpointer user_data)
* @endcode
*
* @b Parameters:
*
* @arg `self`
* @arg `object`
* @arg `user_data`
*
* Flags: Run First
*
* @signal @b pw-proxy-destroyed
*
* @code
* pw_proxy_destroyed_callback (WpProxy * self,
* gpointer user_data)
* @endcode
*
* @b Parameters:
*
* @arg `self`
* @arg `user_data`
*
* Flags: Run First
*
*/
enum
{
SIGNAL_PW_PROXY_CREATED,
@@ -45,15 +112,18 @@ enum
static guint signals[LAST_SIGNAL] = { 0 };
/**
* WpProxy:
/*!
* @struct WpProxy
* @section proxy_section Pipewire Object Proxy
*
* Base class for all objects that expose PipeWire objects using `pw_proxy`
* @brief Base class for all objects that expose PipeWire objects using `pw_proxy`
* underneath.
*
* This base class cannot be instantiated. It provides handling of
* pw_proxy's events and exposes common functionality.
*
*/
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpProxy, wp_proxy, WP_TYPE_OBJECT)
static void
@@ -184,16 +254,17 @@ wp_proxy_class_init (WpProxyClass * klass)
G_TYPE_NONE, 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_STRING);
}
/**
* wp_proxy_get_bound_id:
* @self: the proxy
/*!
* @memberof WpProxy
* @param self: the proxy
*
* Returns the bound id, which is the id that this object has on the
* @brief Returns the bound id, which is the id that this object has on the
* pipewire registry (a.k.a. the global id). The object must have the
* %WP_PROXY_FEATURE_BOUND feature before this method can be called.
*
* Returns: the bound id of this object
* @returns the bound id of this object
*/
guint32
wp_proxy_get_bound_id (WpProxy * self)
{
@@ -205,13 +276,14 @@ wp_proxy_get_bound_id (WpProxy * self)
return priv->pw_proxy ? pw_proxy_get_bound_id (priv->pw_proxy) : SPA_ID_INVALID;
}
/**
* wp_proxy_get_interface_type:
* @self: the proxy
* @version: (out) (optional): the version of the interface
/*!
* @memberof WpProxy
* @param self: the proxy
* @param version: (out) (optional): the version of the interface
*
* Returns: the PipeWire type of the interface that is being proxied
* @returns the PipeWire type of the interface that is being proxied
*/
const gchar *
wp_proxy_get_interface_type (WpProxy * self, guint32 * version)
{
@@ -228,11 +300,13 @@ wp_proxy_get_interface_type (WpProxy * self, guint32 * version)
}
}
/**
* wp_proxy_get_pw_proxy:
/*!
* @memberof WpProxy
*
* Returns: a pointer to the underlying `pw_proxy` object
* @param self: the proxy
* @returns a pointer to the underlying `pw_proxy` object
*/
struct pw_proxy *
wp_proxy_get_pw_proxy (WpProxy * self)
{
@@ -242,13 +316,14 @@ wp_proxy_get_pw_proxy (WpProxy * self)
return priv->pw_proxy;
}
/**
* wp_proxy_set_pw_proxy:
/*!
* @memberof WpProxy
*
* Private method to be used by subclasses to set the `pw_proxy` pointer
* @brief Private method to be used by subclasses to set the `pw_proxy` pointer
* when it is available. This can be called only if there is no `pw_proxy`
* already set. Takes ownership of @proxy.
* already set. Takes ownership of @em proxy.
*/
void
wp_proxy_set_pw_proxy (WpProxy * self, struct pw_proxy * proxy)
{

46
lib/wp/proxy.h
View File

@@ -15,10 +15,13 @@ G_BEGIN_DECLS
struct pw_proxy;
/**
* WpProxyFeatures:
/*!
* @memberof WpProxy
*
* Flags to be used as #WpObjectFeatures for #WpProxy subclasses.
* @section proxy_features_section WpProxyFeatures
*
* @brief Flags to be used as [WpObjectFeatures](@ref object_features_section) for
* [WpProxy](@ref proxy_section) subclasses.
*/
typedef enum { /*< flags >*/
/* standard features */
@@ -35,20 +38,22 @@ typedef enum { /*< flags >*/
WP_PROXY_FEATURE_CUSTOM_START = (1 << 16), /*< skip >*/
} WpProxyFeatures;
/**
/*!
* @memberof WpProxy
* WP_PIPEWIRE_OBJECT_FEATURES_MINIMAL:
*
* The minimal feature set for proxies implementing #WpPipewireObject.
* This is a subset of #WP_PIPEWIRE_OBJECT_FEATURES_ALL
* @brief The minimal feature set for proxies implementing [WpPipewireObject](@ref pipewire_object_section).
* This is a subset of @em WP_PIPEWIRE_OBJECT_FEATURES_ALL
*/
static const WpObjectFeatures WP_PIPEWIRE_OBJECT_FEATURES_MINIMAL =
(WP_PROXY_FEATURE_BOUND | WP_PIPEWIRE_OBJECT_FEATURE_INFO);
/**
/*!
* @memberof WpProxy
* WP_PIPEWIRE_OBJECT_FEATURES_ALL:
*
* The complete common feature set for proxies implementing #WpPipewireObject.
* This is a subset of #WP_OBJECT_FEATURES_ALL
* @brief The complete common feature set for proxies implementing [WpPipewireObject](@ref pipewire_object_section).
* This is a subset of @em WP_OBJECT_FEATURES_ALL
*/
static const WpObjectFeatures WP_PIPEWIRE_OBJECT_FEATURES_ALL =
(WP_PIPEWIRE_OBJECT_FEATURES_MINIMAL |
@@ -58,20 +63,27 @@ static const WpObjectFeatures WP_PIPEWIRE_OBJECT_FEATURES_ALL =
WP_PIPEWIRE_OBJECT_FEATURE_PARAM_PORT_CONFIG |
WP_PIPEWIRE_OBJECT_FEATURE_PARAM_ROUTE);
/**
* WP_TYPE_PROXY:
/*!
* @memberof WpProxy
*
* @brief The [WpProxy](@ref proxy_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_PROXY (wp_proxy_get_type ())
* @endcode
*
* The #WpProxy #GType
*/
#define WP_TYPE_PROXY (wp_proxy_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpProxy, wp_proxy, WP, PROXY, WpObject)
/**
* WpProxyClass:
* @pw_iface_type: the PipeWire type of the interface that is being proxied by
* this class (ex. `PW_TYPE_INTERFACE_Node` for #WpNode)
* @pw_iface_version: the PipeWire version of the interface that is being
/*!
* @brief
* @em pw_iface_type: the PipeWire type of the interface that is being proxied by
* this class (ex. `PW_TYPE_INTERFACE_Node` for [WpNode](@ref node_section))
* @em pw_iface_version: the PipeWire version of the interface that is being
* proxied by this class
*/
struct _WpProxyClass

171
lib/wp/session-item.c
View File

@@ -5,12 +5,9 @@
*
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: session-item
* @title: Session Items
/*!
* @file session-item.c
*/
#define G_LOG_DOMAIN "wp-si"
#include "session-item.h"
@@ -30,15 +27,38 @@ struct _WpSessionItemPrivate
WpProperties *properties;
};
/*!
* @memberof WpSessionItem
*
* @props @b id
*
* @code
* "id" guint
* @endcode
*
* Flags : Read
*
* @props @b properties
*
* @code
* "properties" WpProperties *
* @endcode
*
* Flags : Read
*
*/
enum {
PROP_0,
PROP_ID,
PROP_PROPERTIES,
};
/**
* WpSessionItem:
/*!
* @struct WpSessionItem
* @section session_item_section Sessio Item
*
*/
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpSessionItem, wp_session_item,
WP_TYPE_OBJECT)
@@ -216,12 +236,13 @@ wp_session_item_class_init (WpSessionItemClass * klass)
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
}
/**
* wp_session_item_get_id:
* @self: the session item
/*!
* @memberof WpSessionItem
* @param self: the session item
*
* Gets the unique Id of the session item
* @brief Gets the unique Id of the session item
*/
guint
wp_session_item_get_id (WpSessionItem * self)
{
@@ -233,13 +254,14 @@ wp_session_item_get_id (WpSessionItem * self)
return priv->id;
}
/**
* wp_session_item_reset: (virtual reset)
* @self: the session item
/*!
* @memberof WpSessionItem
* @param self: the session item
*
* Resets the session item. This essentially removes the configuration and
* @brief Resets the session item. This essentially removes the configuration and
* and deactivates all active features.
*/
void
wp_session_item_reset (WpSessionItem * self)
{
@@ -249,13 +271,14 @@ wp_session_item_reset (WpSessionItem * self)
return WP_SESSION_ITEM_GET_CLASS (self)->reset (self);
}
/**
* wp_session_item_configure: (virtual configure)
* @self: the session item
* @props: (transfer full): the properties used to configure the item
/*!
* @memberof WpSessionItem
* @param self: the session item
* @param props: (transfer full): the properties used to configure the item
*
* Returns: %TRUE on success, %FALSE if the item could not be configured
* @returns %TRUE on success, %FALSE if the item could not be configured
*/
gboolean
wp_session_item_configure (WpSessionItem * self, WpProperties * props)
{
@@ -266,12 +289,13 @@ wp_session_item_configure (WpSessionItem * self, WpProperties * props)
return WP_SESSION_ITEM_GET_CLASS (self)->configure (self, props);
}
/**
* wp_session_item_is_configured:
* @self: the session item
/*!
* @memberof WpSessionItem
* @param self: the session item
*
* Returns: %TRUE if the item is configured, %FALSE otherwise
* @returns %TRUE if the item is configured, %FALSE otherwise
*/
gboolean
wp_session_item_is_configured (WpSessionItem * self)
{
@@ -283,23 +307,26 @@ wp_session_item_is_configured (WpSessionItem * self)
return priv->properties != NULL;
}
/**
* wp_session_item_get_associated_proxy: (virtual get_associated_proxy)
* @self: the session item
* @proxy_type: a #WpProxy subclass #GType
/*!
* @memberof WpSessionItem
* @param self: the session item
* @param proxy_type: a [WpProxy](@ref proxy_section) subclass
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* An associated proxy is a #WpProxy subclass instance that is somehow related
* to this item. For example:
* - An exported #WpSiEndpoint should have at least:
* - an associated #WpEndpoint
* - an associated #WpSession
* @brief An associated proxy is a [WpProxy](@ref proxy_section) subclass instance that
* is somehow related to this item. For example:
* - An exported [WpSiEndpoint](@ref si_endpoint_section) should have at least:
* - an associated [WpSiEndpoint](@ref si_endpoint_section)
* - an associated [WpSession](@ref session_section)
* - In cases where the item wraps a single PipeWire node, it should also
* have an associated #WpNode
* have an associated [WpNode](@ref node_section)
*
* Returns: (nullable) (transfer full) (type WpProxy): the associated proxy
* of the specified @proxy_type, or %NULL if there is no association to
* @returns (nullable) (transfer full) (type WpProxy): the associated proxy
* of the specified @em proxy_type, or %NULL if there is no association to
* such a proxy
*/
gpointer
wp_session_item_get_associated_proxy (WpSessionItem * self, GType proxy_type)
{
@@ -311,14 +338,17 @@ wp_session_item_get_associated_proxy (WpSessionItem * self, GType proxy_type)
return WP_SESSION_ITEM_GET_CLASS (self)->get_associated_proxy (self, proxy_type);
}
/**
* wp_session_item_get_associated_proxy_id:
* @self: the session item
* @proxy_type: a #WpProxy subclass #GType
/*!
* @memberof WpSessionItem
* @param self: the session item
* @param proxy_type: a [WpProxy](@ref proxy_section) subclass
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* Returns: the bound id of the associated proxy of the specified @proxy_type,
* @returns the bound id of the associated proxy of the specified @em proxy_type,
* or `SPA_ID_INVALID` if there is no association to such a proxy
*/
guint32
wp_session_item_get_associated_proxy_id (WpSessionItem * self, GType proxy_type)
{
@@ -330,12 +360,13 @@ wp_session_item_get_associated_proxy_id (WpSessionItem * self, GType proxy_type)
return wp_proxy_get_bound_id (proxy);
}
/**
* wp_session_item_register:
* @self: (transfer full): the session item
/*!
* @memberof WpSessionItem
* @param self: (transfer full): the session item
*
* Registers the session item to its associated core
* @brief Registers the session item to its associated core
*/
void
wp_session_item_register (WpSessionItem * self)
{
@@ -347,12 +378,13 @@ wp_session_item_register (WpSessionItem * self)
wp_registry_register_object (wp_core_get_registry (core), self);
}
/**
* wp_session_item_remove:
* @self: (transfer none): the session item
/*!
* @memberof WpSessionItem
* @param self: (transfer none): the session item
*
* Removes the session item from the registry
* @brief Removes the session item from the registry
*/
void
wp_session_item_remove (WpSessionItem * self)
{
@@ -364,12 +396,13 @@ wp_session_item_remove (WpSessionItem * self)
wp_registry_remove_object (wp_core_get_registry (core), self);
}
/**
* wp_session_item_get_properties:
* @self: the session item
/*!
* @memberof WpSessionItem
* @param self: the session item
*
* Returns: (transfer full): the item's properties.
* @returns (transfer full): the item's properties.
*/
WpProperties *
wp_session_item_get_properties (WpSessionItem * self)
{
@@ -381,12 +414,12 @@ wp_session_item_get_properties (WpSessionItem * self)
return priv->properties ? wp_properties_ref (priv->properties) : NULL;
}
/**
* wp_session_item_get_property:
* @self: the session item
* @key: the property key
/*!
* @memberof WpSessionItem
* @param self: the session item
* @param key: the property key
*
* Returns: the item property value for the given key.
* @returns the item property value for the given key.
*/
const gchar *
wp_session_item_get_property (WpSessionItem * self, const gchar *key)
@@ -399,14 +432,15 @@ wp_session_item_get_property (WpSessionItem * self, const gchar *key)
return priv->properties ? wp_properties_get (priv->properties, key) : NULL;
}
/**
* wp_session_item_set_properties:
* @self: the session item
* @props: (transfer full): the new properties to set
/*!
* @memberof WpSessionItem
* @param self: the session item
* @param props: (transfer full): the new properties to set
*
* Sets the item's properties. This should only be done by sub-classes after
* @brief Sets the item's properties. This should only be done by sub-classes after
* the configuration has been done.
*/
void
wp_session_item_set_properties (WpSessionItem * self,
WpProperties *props)
@@ -428,14 +462,15 @@ on_session_item_proxy_destroyed_deferred (WpSessionItem * item)
return G_SOURCE_REMOVE;
}
/**
* wp_session_item_handle_proxy_destroyed:
* @proxy: the proxy that was destroyed by the server
* @item: the associated session item
/*!
* @memberof WpSessionItem
* @param proxy: the proxy that was destroyed by the server
* @param item: the associated session item
*
* Helper callback for sub-classes that deffers and unexports the session item.
* @brief Helper callback for sub-classes that deffers and unexports the session item.
* Only meant to be used when the pipewire proxy destroyed signal is triggered.
*/
void
wp_session_item_handle_proxy_destroyed (WpProxy * proxy, WpSessionItem * item)
{

38
lib/wp/session-item.h
View File

@@ -14,10 +14,11 @@
G_BEGIN_DECLS
/**
* WpSessionItemFeatures:
/*!
* @memberof WpSessionItem
*
* Flags to be used as #WpObjectFeatures for #WpSessionItem subclasses.
* @brief Flags to be used as [WpObjectFeatures](@ref object_features_section) for
* [WpSessionItem](@ref session_item_section) subclasses.
*/
typedef enum { /*< flags >*/
/* main features */
@@ -27,25 +28,32 @@ typedef enum { /*< flags >*/
WP_SESSION_ITEM_FEATURE_CUSTOM_START = (1 << 16), /*< skip >*/
} WpSessionItemFeatures;
/**
* WP_TYPE_SESSION_ITEM:
/*!
* @memberof WpSessionItem
*
* @brief The [WpSessionItem](@ref session_item_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SESSION_ITEM (wp_session_item_get_type ())
* @endcode
*
* The #WpSessionItem #GType
*/
#define WP_TYPE_SESSION_ITEM (wp_session_item_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpSessionItem, wp_session_item,
WP, SESSION_ITEM, WpObject)
/**
* WpSessionItemClass:
* @reset: See wp_session_item_reset()
* @configure: See wp_session_item_configure()
* @get_associated_proxy: See wp_session_item_get_associated_proxy()
* @disable_active: disables the active feature of the session item
* @disable_exported: disables the exported feature of the session item
* @enable_active: enables the active feature of the session item
* @enable_exported: enables the exported feature of the session item
/*!
* @brief
* @em reset: See wp_session_item_reset()
* @em configure: See wp_session_item_configure()
* @em get_associated_proxy: See wp_session_item_get_associated_proxy()
* @em disable_active: disables the active feature of the session item
* @em disable_exported: disables the exported feature of the session item
* @em enable_active: enables the active feature of the session item
* @em enable_exported: enables the exported feature of the session item
*/
struct _WpSessionItemClass
{

95
lib/wp/si-factory.c
View File

@@ -6,9 +6,8 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: si-factory
* @title: Session Items Factory
/*!
* @file si-factory.c
*/
#define G_LOG_DOMAIN "wp-si-factory"
@@ -16,6 +15,18 @@
#include "si-factory.h"
#include "private/registry.h"
/*!
* @memberof WpSiFactory
*
* @props @b name
*
* @code
* "name" gchar *
* @endcode
*
* Flags : Read / Write / Construct Only
*
*/
enum {
PROP_0,
PROP_NAME,
@@ -27,10 +38,11 @@ struct _WpSiFactoryPrivate
GQuark name_quark;
};
/**
* WpSiFactory:
/*!
* @struct WpSiFactory
* @section si_factory_section Session Items Factory
*
* A factory for session items.
* @brief A factory for session items.
*
* The most simple way to register a new item implementation would be:
* |[
@@ -44,7 +56,9 @@ struct _WpSiFactoryPrivate
* |[
* item = wp_session_item_make (core, "foobar");
* ]|
*
*/
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpSiFactory, wp_si_factory, G_TYPE_OBJECT)
static void
@@ -99,12 +113,13 @@ wp_si_factory_class_init (WpSiFactoryClass * klass)
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
}
/**
* wp_si_factory_get_name:
* @self: the factory
/*!
* @memberof WpSiFactory
* @param self: the factory
*
* Returns: the factory name
* @returns the factory name
*/
const gchar *
wp_si_factory_get_name (WpSiFactory * self)
{
@@ -114,15 +129,17 @@ wp_si_factory_get_name (WpSiFactory * self)
return g_quark_to_string (priv->name_quark);
}
/**
* wp_si_factory_construct:
* @self: the factory
/*!
* @memberof WpSiFactory
* @param self: the factory
* @param core: the core
*
* Creates a new instance of the session item that is constructed
* @brief Creates a new instance of the session item that is constructed
* by this factory
*
* Returns: (transfer full): a new session item instance
* @returns (transfer full): a new session item instance
*/
WpSessionItem *
wp_si_factory_construct (WpSiFactory * self, WpCore * core)
{
@@ -132,13 +149,14 @@ wp_si_factory_construct (WpSiFactory * self, WpCore * core)
return WP_SI_FACTORY_GET_CLASS (self)->construct (self, core);
}
/**
* wp_si_factory_register:
* @core: the core
* @factory: (transfer full): the factory to register
/*!
* @memberof WpSiFactory
* @param core: the core
* @param factory: (transfer full): the factory to register
*
* Registers the @factory on the @core.
* @brief Registers the @em factory on the @em core.
*/
void
wp_si_factory_register (WpCore * core, WpSiFactory * factory)
{
@@ -159,13 +177,14 @@ find_factory_func (gpointer factory, gpointer name_quark)
return priv->name_quark == GPOINTER_TO_UINT (name_quark);
}
/**
* wp_si_factory_find:
* @core: the core
* @factory_name: the lookup name
/*!
* @memberof WpSiFactory
* @param core: the core
* @param factory_name: the lookup name
*
* Returns: (transfer full) (nullable): the factory matching the lookup name
* @returns (transfer full) (nullable): the factory matching the lookup name
*/
WpSiFactory *
wp_si_factory_find (WpCore * core, const gchar * factory_name)
{
@@ -179,16 +198,17 @@ wp_si_factory_find (WpCore * core, const gchar * factory_name)
return f ? WP_SI_FACTORY (f) : NULL;
}
/**
* wp_session_item_make:
* @core: the #WpCore
* @factory_name: the name of the factory to be used for constructing the object
/*!
* @memberof WpSiFactory
* @param core: the [WpCore](@ref core_section)
* @param factory_name: the name of the factory to be used for constructing the object
*
* Finds the factory associated with the given @name from the @core and
* uses it to construct a new #WpSessionItem.
* @brief Finds the factory associated with the given @em name from the @em core and
* uses it to construct a new [WpSessionItem](@ref session_item_section).
*
* Returns: (transfer full) (nullable): the new session item
* @returns (transfer full) (nullable): the new session item
*/
WpSessionItem *
wp_session_item_make (WpCore * core, const gchar * factory_name)
{
@@ -227,14 +247,15 @@ wp_simple_si_factory_class_init (WpSimpleSiFactoryClass * klass)
factory_class->construct = wp_simple_si_factory_construct;
}
/**
* wp_si_factory_new_simple:
* @factory_name: the factory name; must be a static string!
* @si_type: the #WpSessionItem subclass type to instantiate for
/*!
* @memberof WpSiFactory
* @param factory_name: the factory name; must be a static string!
* @param si_type: the [WpSessionItem](@ref session_item_section) subclass type to instantiate for
* constructing items
*
* Returns: (transfer full): the new factory
* @returns (transfer full): the new factory
*/
WpSiFactory *
wp_si_factory_new_simple (const gchar * factory_name, GType si_type)
{

19
lib/wp/si-factory.h
View File

@@ -14,15 +14,28 @@
G_BEGIN_DECLS
/**
* WP_TYPE_SI_FACTORY:
/*!
* @memberof WpSiFactory
*
* @brief The [WpSiFactory](@ref si_factory_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SI_FACTORY (wp_si_factory_get_type ())
* @endcode
*
* The #WpSiFactory #GType
*/
#define WP_TYPE_SI_FACTORY (wp_si_factory_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpSiFactory, wp_si_factory, WP, SI_FACTORY, GObject)
/*!
* @memberof WpSiFactory
*
* @brief
* @em parent_class
*/
struct _WpSiFactoryClass
{
GObjectClass parent_class;

250
lib/wp/si-interfaces.c
View File

@@ -5,10 +5,79 @@
*
* SPDX-License-Identifier: MIT
*/
/*!
* @file si-interfaces.c
*/
/**
* SECTION: si-interfaces
* @title: Session Item Interfaces
/*!
* @section si_interfaces_section Session Item Interfaces
*
* @struct WpSiAcquisition
* @section si_acquisition_section WpSiAcquisition
*
* @brief 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](@ref si_acquisition_section) is associated directly
* with a [WpSiLinkable](@ref si_linkable_section) 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 WpSiEndpoint
* @section si_endpoint_section WpSiEndpoint
*
* @brief An interface for session items that implement a PipeWire endpoint.
*
* @section si_endpoint_signals_section Signals
*
* @b endpoint-properties-changed
*
* @code
* endpoint_properties_changed_callback (WpSiEndpoint * self,
* gpointer user_data)
* @endcode
*
* Parameters:
*
* @arg `self` - the session
* @arg `user_data`
*
* Flags: Run Last
*
* @struct WpSiLink
* @section si_link_section WpSiLink
*
* @brief An interface for session items that provide a PipeWire endpoint link.
*
* @section si_link_signals_section Signals
*
* @b link-properties-changed
*
* @code
* link_properties_changed_callback (WpSiLink * self,
* gpointer user_data)
* @endcode
*
* Parameters:
*
* @arg `self` - the session
* @arg `user_data`
*
* Flags: Run Last
*
* WpSiLinkable:
*
* @struct WpSiLinkable
* @section si_linkable_section WpSiLinkable
*
* @brief 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](@ref si_endpoint_section). The standard link implementation expects to be able to cast
* a [WpSiEndpoint](@ref si_endpoint_section) into a [WpSiLinkable](@ref si_linkable_section).
*
*/
#define G_LOG_DOMAIN "wp-si-interfaces"
@@ -16,11 +85,6 @@
#include "si-interfaces.h"
#include "wpenums.h"
/**
* WpSiEndpoint:
*
* An interface for session items that implement a PipeWire endpoint.
*/
G_DEFINE_INTERFACE (WpSiEndpoint, wp_si_endpoint, WP_TYPE_SESSION_ITEM)
static WpProperties *
@@ -38,19 +102,20 @@ wp_si_endpoint_default_init (WpSiEndpointInterface * iface)
G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
}
/**
* wp_si_endpoint_get_registration_info: (virtual get_registration_info)
* @self: the session item
/*!
* @memberof WpSiEndpoint
* @param self: the session item
*
* This should return information that is used for registering the endpoint,
* @brief This should return information that is used for registering the endpoint,
* as 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
*
* Returns: (transfer full): registration info for the endpoint
* @returns (transfer full): registration info for the endpoint
*/
GVariant *
wp_si_endpoint_get_registration_info (WpSiEndpoint * self)
{
@@ -60,12 +125,13 @@ wp_si_endpoint_get_registration_info (WpSiEndpoint * self)
return WP_SI_ENDPOINT_GET_IFACE (self)->get_registration_info (self);
}
/**
* wp_si_endpoint_get_properties: (virtual get_properties)
* @self: the session item
/*!
* @memberof WpSiEndpoint
* @param self: the session item
*
* Returns: (transfer full) (nullable): the properties of the endpoint
* @returns (transfer full) (nullable): the properties of the endpoint
*/
WpProperties *
wp_si_endpoint_get_properties (WpSiEndpoint * self)
{
@@ -75,11 +141,7 @@ wp_si_endpoint_get_properties (WpSiEndpoint * self)
return WP_SI_ENDPOINT_GET_IFACE (self)->get_properties (self);
}
/**
* WpSiAdapter:
*
* An interface for setting and getting the session item format.
*/
G_DEFINE_INTERFACE (WpSiAdapter, wp_si_adapter, WP_TYPE_SESSION_ITEM)
static void
@@ -154,12 +216,7 @@ wp_si_adapter_set_ports_format_finish (WpSiAdapter * self, GAsyncResult * res,
error);
}
/**
* WpSiLinkable:
*
* An interface for retrieving PipeWire port information from a session item.
* This information is used to create links in the nodes graph.
*/
G_DEFINE_INTERFACE (WpSiLinkable, wp_si_linkable, WP_TYPE_SESSION_ITEM)
static WpSiAcquisition *
@@ -174,12 +231,12 @@ wp_si_linkable_default_init (WpSiLinkableInterface * iface)
iface->get_acquisition = wp_si_linkable_default_get_acquisition;
}
/**
* wp_si_linkable_get_ports: (virtual get_ports)
* @self: the session item
* @context: (nullable): an optional context for the ports
/*!
* @memberof WpSiLinkable
* @param self: the session item
* @param context: (nullable): an optional context for the ports
*
* This method returns a variant of type "a(uuu)", where each tuple in the
* @brief 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)
@@ -191,7 +248,7 @@ wp_si_linkable_default_init (WpSiLinkableInterface * iface)
* 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 @em 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
@@ -201,20 +258,25 @@ wp_si_linkable_default_init (WpSiLinkableInterface * iface)
*
* 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
* [WpSessionItem](@ref session_item_section) that is in control of an
* input (sink) adapter node may implement [WpSiLinkable](@ref si_linkable_section)
* 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
* [WpSessionItem](@ref session_item_section) that implements the "monitor" item.
* That secondary item may implement [WpSiLinkable](@ref si_linkable_section),
* chaining calls to the [WpSiLinkable](@ref si_linkable_section)
* 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.
* [WpSessionItem](@ref session_item_section) does not need to share control of the
* underlying node; it only proxies calls to satisfy the API.
*
* Returns: (transfer full): a #GVariant containing information about the
* @returns (transfer full): a
* <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
* GVariant</a> containing information about the
* ports of this item
*/
GVariant *
wp_si_linkable_get_ports (WpSiLinkable * self, const gchar * context)
{
@@ -224,14 +286,15 @@ wp_si_linkable_get_ports (WpSiLinkable * self, const gchar * context)
return WP_SI_LINKABLE_GET_IFACE (self)->get_ports (self, context);
}
/**
* wp_si_linkable_get_acquisition: (virtual get_acquisition)
* @self: the session item
/*!
* @memberof WpSiLinkable
* @param self: the session item
*
* Returns: (transfer none) (nullable): the acquisition interface associated
* @returns (transfer none) (nullable): the acquisition interface associated
* with this item, or %NULL if this item does not require acquiring items
* before linking them
*/
WpSiAcquisition *
wp_si_linkable_get_acquisition (WpSiLinkable * self)
{
@@ -242,11 +305,6 @@ wp_si_linkable_get_acquisition (WpSiLinkable * self)
return WP_SI_LINKABLE_GET_IFACE (self)->get_acquisition (self);
}
/**
* WpSiLink:
*
* An interface for session items that provide a PipeWire endpoint link.
*/
G_DEFINE_INTERFACE (WpSiLink, wp_si_link, WP_TYPE_SESSION_ITEM)
static WpProperties *
@@ -264,16 +322,17 @@ wp_si_link_default_init (WpSiLinkInterface * iface)
G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
}
/**
* wp_si_link_get_registration_info: (virtual get_registration_info)
* @self: the session item
/*!
* @memberof WpSiLink
* @param self: the session item
*
* This should return information that is used for registering the link,
* @brief 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
*
* Returns: (transfer full): registration info for the link
* @returns (transfer full): registration info for the link
*/
GVariant *
wp_si_link_get_registration_info (WpSiLink * self)
{
@@ -283,12 +342,13 @@ wp_si_link_get_registration_info (WpSiLink * self)
return WP_SI_LINK_GET_IFACE (self)->get_registration_info (self);
}
/**
* wp_si_link_get_properties: (virtual get_properties)
* @self: the session item
/*!
* @memberof WpSiLink
* @param self: the session item
*
* Returns: (transfer full) (nullable): the properties of the link
* @returns (transfer full) (nullable): the properties of the link
*/
WpProperties *
wp_si_link_get_properties (WpSiLink * self)
{
@@ -298,11 +358,11 @@ wp_si_link_get_properties (WpSiLink * self)
return WP_SI_LINK_GET_IFACE (self)->get_properties (self);
}
/**
* wp_si_link_get_out_item: (virtual get_out_item)
* @self: the session item
/*!
* @memberof WpSiLink
* @param self: the session item
*
* Returns: (transfer none): the output item that is linked by this link
* @returns (transfer none): the output item that is linked by this link
*/
WpSiLinkable *
wp_si_link_get_out_item (WpSiLink * self)
@@ -313,11 +373,11 @@ wp_si_link_get_out_item (WpSiLink * self)
return WP_SI_LINK_GET_IFACE (self)->get_out_item (self);
}
/**
* wp_si_link_get_in_item: (virtual get_in_item)
* @self: the session item
/*!
* @memberof WpSiLink
* @param self: the session item
*
* Returns: (transfer none): the input item that is linked by this link
* @returns (transfer none): the input item that is linked by this link
*/
WpSiLinkable *
wp_si_link_get_in_item (WpSiLink * self)
@@ -328,17 +388,6 @@ wp_si_link_get_in_item (WpSiLink * self)
return WP_SI_LINK_GET_IFACE (self)->get_in_item (self);
}
/**
* 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.
*/
G_DEFINE_INTERFACE (WpSiAcquisition, wp_si_acquisition, WP_TYPE_SESSION_ITEM)
static void
@@ -346,15 +395,15 @@ wp_si_acquisition_default_init (WpSiAcquisitionInterface * iface)
{
}
/**
* wp_si_acquisition_acquire: (virtual acquire)
* @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
/*!
* @memberof WpSiAcquisition
* @param self: the session item
* @param acquisitor: the link that is trying to acquire a port info item
* @param item: the item that is being acquired
* @param callback: (scope async): the callback to call when the operation is done
* @param data: (closure): user data for @em callback
*
* Acquires the @item for linking by @acquisitor.
* @brief Acquires the @em item for linking by @em acquisitor.
*
* When a link is not allowed by policy, this operation should return
* an error.
@@ -364,6 +413,7 @@ wp_si_acquisition_default_init (WpSiAcquisitionInterface * iface)
* delay. It is safe to assume that after this operation completes,
* the item will be linked immediately.
*/
void
wp_si_acquisition_acquire (WpSiAcquisition * self, WpSiLink * acquisitor,
WpSiLinkable * item, GAsyncReadyCallback callback, gpointer data)
@@ -375,17 +425,18 @@ wp_si_acquisition_acquire (WpSiAcquisition * self, WpSiLink * acquisitor,
data);
}
/**
* wp_si_acquisition_acquire_finish: (virtual acquire_finish)
* @self: the session item
* @res: the async result
* @error: (out) (optional): the operation's error, if it occurred
/*!
* @memberof WpSiAcquisition
* @param self: the session item
* @param res: the async result
* @param error: (out) (optional): the operation's error, if it occurred
*
* Finishes the operation started by wp_si_acquisition_acquire().
* @brief Finishes the operation started by wp_si_acquisition_acquire().
* This is meant to be called in the callback that was passed to that method.
*
* Returns: %TRUE on success, %FALSE if there was an error
* @returns %TRUE on success, %FALSE if there was an error
*/
gboolean
wp_si_acquisition_acquire_finish (WpSiAcquisition * self, GAsyncResult * res,
GError ** error)
@@ -397,14 +448,15 @@ wp_si_acquisition_acquire_finish (WpSiAcquisition * self, GAsyncResult * res,
return WP_SI_ACQUISITION_GET_IFACE (self)->acquire_finish (self, res, error);
}
/**
* wp_si_acquisition_release: (virtual release)
* @self: the session item
* @acquisitor: the link that had previously acquired the item
* @item: the port info item that is being released
/*!
* @memberof WpSiAcquisition
* @param self: the session item
* @param acquisitor: the link that had previously acquired the item
* @param item: the port info that is being released
*
* Releases the @item, which means that it is being unlinked.
* @brief Releases the @em item, which means that it is being unlinked.
*/
void
wp_si_acquisition_release (WpSiAcquisition * self, WpSiLink * acquisitor,
WpSiLinkable * item)

91
lib/wp/si-interfaces.h
View File

@@ -17,16 +17,29 @@ G_BEGIN_DECLS
typedef struct _WpSiAcquisition WpSiAcquisition;
/**
* WP_TYPE_SI_ENDPOINT:
/*!
* @memberof WpSiEndpoint
*
* @brief The [WpSiEndpoint](@ref si_endpoint_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SI_ENDPOINT (wp_si_endpoint_get_type ())
* @endcode
*
* The #WpSiEndpoint #GType
*/
#define WP_TYPE_SI_ENDPOINT (wp_si_endpoint_get_type ())
WP_API
G_DECLARE_INTERFACE (WpSiEndpoint, wp_si_endpoint,
WP, SI_ENDPOINT, WpSessionItem)
/*!
* @memberof WpSiEndpoint
*
* @brief
* @em interface
*/
struct _WpSiEndpointInterface
{
GTypeInterface interface;
@@ -41,16 +54,31 @@ GVariant * wp_si_endpoint_get_registration_info (WpSiEndpoint * self);
WP_API
WpProperties * wp_si_endpoint_get_properties (WpSiEndpoint * self);
/**
/*!
* @memberof WpSiAdapter
*
* WP_TYPE_SI_ADAPTER:
*
* The #WpSiAdapter #GType
* @brief The [WpSiAdapter](@ref si_adapter_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SI_ADAPTER (wp_si_adapter_get_type ())
* @endcode
*/
#define WP_TYPE_SI_ADAPTER (wp_si_adapter_get_type ())
WP_API
G_DECLARE_INTERFACE (WpSiAdapter, wp_si_adapter,
WP, SI_ADAPTER, WpSessionItem)
/*!
* @memberof WpSiAdapter
*
* @brief
* @em interface
*/
struct _WpSiAdapterInterface
{
GTypeInterface interface;
@@ -74,16 +102,31 @@ WP_API
gboolean wp_si_adapter_set_ports_format_finish (WpSiAdapter * self,
GAsyncResult * res, GError ** error);
/**
/*!
* @memberof WpSiLinkable
*
* WP_TYPE_SI_LINKABLE:
*
* The #WpSiLinkable #GType
* @brief The [WpSiLinkable](@ref si_linkable_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SI_LINKABLE (wp_si_linkable_get_type ())
* @endcode
*/
#define WP_TYPE_SI_LINKABLE (wp_si_linkable_get_type ())
WP_API
G_DECLARE_INTERFACE (WpSiLinkable, wp_si_linkable,
WP, SI_LINKABLE, WpSessionItem)
/*!
* @memberof WpSiLinkable
*
* @brief
* @em interface
*/
struct _WpSiLinkableInterface
{
GTypeInterface interface;
@@ -99,16 +142,31 @@ GVariant * wp_si_linkable_get_ports (WpSiLinkable * self,
WP_API
WpSiAcquisition * wp_si_linkable_get_acquisition (WpSiLinkable * self);
/**
/*!
* @memberof WpSiLink
*
* WP_TYPE_SI_LINK:
*
* The #WpSiLink #GType
* @brief The [WpSiLink](@ref si_link_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SI_LINK (wp_si_link_get_type ())
* @endcode
*
*/
#define WP_TYPE_SI_LINK (wp_si_link_get_type ())
WP_API
G_DECLARE_INTERFACE (WpSiLink, wp_si_link,
WP, SI_LINK, WpSessionItem)
/*!
* @memberof WpSiLink
*
* @brief
* @em interface
*/
struct _WpSiLinkInterface
{
GTypeInterface interface;
@@ -132,16 +190,31 @@ WpSiLinkable * wp_si_link_get_out_item (WpSiLink * self);
WP_API
WpSiLinkable * wp_si_link_get_in_item (WpSiLink * self);
/**
/*!
* @memberof WpSiAcquisition
*
* WP_TYPE_SI_ACQUISITION:
*
* The #WpSiAcquisition #GType
* The [WpSiAcquisition](@ref si_acquisition_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SI_ACQUISITION (wp_si_acquisition_get_type ())
* @endcode
*
*/
#define WP_TYPE_SI_ACQUISITION (wp_si_acquisition_get_type ())
WP_API
G_DECLARE_INTERFACE (WpSiAcquisition, wp_si_acquisition,
WP, SI_ACQUISITION, WpSessionItem)
/*!
* @memberof WpSiAcquisition
*
* @brief
* @em interface
*/
struct _WpSiAcquisitionInterface
{
GTypeInterface interface;

1577
lib/wp/spa-pod.c
View File

File diff suppressed because it is too large Load Diff

43
lib/wp/spa-pod.h
View File

@@ -19,10 +19,17 @@ G_BEGIN_DECLS
struct spa_pod;
/**
* WP_TYPE_SPA_POD:
/*!
* @memberof WpSpaPod
*
* @brief The [WpSpaPod](@ref spa_pod_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SPA_POD (wp_spa_pod_get_type ())
* @endcode
*
* The #WpSpaPod #GType
*/
#define WP_TYPE_SPA_POD (wp_spa_pod_get_type ())
WP_API
@@ -290,10 +297,19 @@ WpIterator *wp_spa_pod_new_iterator (WpSpaPod *pod);
G_DEFINE_AUTOPTR_CLEANUP_FUNC (WpSpaPod, wp_spa_pod_unref)
/**
* WP_TYPE_SPA_POD_BUILDER:
/*!
* @memberof WpSpaPod
*
* @section spa_pod_builder_section WP_TYPE_SPA_POD_BUILDER
*
* @brief The [WpSpaPodBuilder](@ref spa_pod_builder_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SPA_POD_BUILDER (wp_spa_pod_builder_get_type ())
* @endcode
*
* The #WpSpaPodBuilder #GType
*/
#define WP_TYPE_SPA_POD_BUILDER (wp_spa_pod_builder_get_type ())
WP_API
@@ -391,10 +407,19 @@ WpSpaPod *wp_spa_pod_builder_end (WpSpaPodBuilder *self);
G_DEFINE_AUTOPTR_CLEANUP_FUNC (WpSpaPodBuilder, wp_spa_pod_builder_unref)
/**
* WP_TYPE_SPA_POD_PARSER:
/*!
* @memberof WpSpaPod
*
* @section spa_pod_parser_section WP_TYPE_SPA_POD_PARSER
*
* @brief The [WpSpaPodBuilder](@ref spa_pod_parser_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_SPA_POD_PARSER (wp_spa_pod_parser_get_type ())
* @endcode
*
* The #WpSpaPodParser #GType
*/
#define WP_TYPE_SPA_POD_PARSER (wp_spa_pod_parser_get_type ())
WP_API

325
lib/wp/spa-type.c
View File

@@ -6,9 +6,13 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: spa-type
* @title: Spa Type Information
/*!
* @file spa-type
*/
/*!
* @struct WpSpaType
* @section spa_type_section Spa Type Information
*
* Spa has a type system that is represented by a set of arrays that contain
* `spa_type_info` structures. This type system is simple, yet complex to
@@ -19,16 +23,21 @@
* API is that it makes it easy to work with string representations of the
* types, allowing easier access from script bindings.
*
* ### Type hierarchy
* @section spa_type_hierarchy_section Type hierarchy
*
* @subsection spa_type_subsection WpSpaType
*
* On the top level, there is a list of types like Int, Bool, String, Id, Object.
* These are called fundamental types (terms borrowed from #GType).
* These are called fundamental types (terms borrowed from
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>).
* Fundamental types can be derived and therefore we can have other types
* that represent specific objects, for instance.
*
* Enum and flag types are all represented with `SPA_TYPE_Id`. These types
* may have a list of possible values that one can select from (enums)
* or combine (flags). These values are accessed with the #WpSpaIdTable API.
* or combine (flags). These values are accessed with the
* [WpSpaIdTable](@ref spa_id_table_section) API.
*
* Object types can have fields. All objects always have a special "id" field,
* which is an enum. Its possible values can be given by
@@ -36,7 +45,8 @@
* other object-specific fields, which can be accessed with
* wp_spa_type_get_values_table().
*
* Every object field or enum value is represented by a #WpSpaIdValue. In the
* Every object field or enum value is represented by a
* [WpSpaIdValue](@ref spa_id_value_section). In the
* case of object fields, each field can be of a specific type, which is
* returned by wp_spa_id_value_get_value_type().
*/
@@ -80,9 +90,6 @@ static const WpSpaIdTableInfo static_id_tables[] = {
{ NULL, NULL }
};
/**
* WpSpaType:
*/
GType wp_spa_type_get_type (void)
{
static volatile gsize id__volatile = 0;
@@ -95,12 +102,12 @@ GType wp_spa_type_get_type (void)
return id__volatile;
}
/**
/*
* WpSpaIdTable:
*/
G_DEFINE_POINTER_TYPE (WpSpaIdTable, wp_spa_id_table)
/**
/*
* WpSpaIdValue:
*/
G_DEFINE_POINTER_TYPE (WpSpaIdValue, wp_spa_id_value)
@@ -158,15 +165,16 @@ wp_spa_type_info_find_by_name (const gchar *name)
return info;
}
/**
* wp_spa_type_from_name:
* @name: the name to look up
/*!
* @memberof WpSpaType
* @param name: the name to look up
*
* Looks up the type id from a given type name
* @brief Looks up the type id from a given type name
*
* Returns: (transfer none): the corresponding type id or %WP_SPA_TYPE_INVALID
* @returns (transfer none): the corresponding type id or %WP_SPA_TYPE_INVALID
* if not found
*/
WpSpaType
wp_spa_type_from_name (const gchar *name)
{
@@ -174,14 +182,15 @@ wp_spa_type_from_name (const gchar *name)
return info ? info->type : WP_SPA_TYPE_INVALID;
}
/**
* wp_spa_type_parent:
* @type: a type id
/*!
* @memberof WpSpaType
* @param type: a type id
*
* Returns: (transfer none): the direct parent type of the given @type; if the
* @returns (transfer none): the direct parent type of the given @em type; if the
* type is fundamental (i.e. has no parent), the returned type is the same
* as @type
* as @em type
*/
WpSpaType
wp_spa_type_parent (WpSpaType type)
{
@@ -189,12 +198,13 @@ wp_spa_type_parent (WpSpaType type)
return info ? info->parent : WP_SPA_TYPE_INVALID;
}
/**
* wp_spa_type_name:
* @type: a type id
/*!
* @memberof WpSpaType
* @param type: a type id
*
* Returns: the complete name of the given @type or %NULL if @type is invalid
* @returns the complete name of the given @em type or %NULL if @em type is invalid
*/
const gchar *
wp_spa_type_name (WpSpaType type)
{
@@ -202,12 +212,13 @@ wp_spa_type_name (WpSpaType type)
return info ? info->name : NULL;
}
/**
* wp_spa_type_is_fundamental:
* @type: a type id
/*!
* @memberof WpSpaType
* @param type: a type id
*
* Returns: %TRUE if the @type has no parent, %FALSE otherwise
* @returns %TRUE if the @em type has no parent, %FALSE otherwise
*/
gboolean
wp_spa_type_is_fundamental (WpSpaType type)
{
@@ -215,12 +226,13 @@ wp_spa_type_is_fundamental (WpSpaType type)
return info ? (info->type == info->parent) : FALSE;
}
/**
* wp_spa_type_is_id:
* @type: a type id
/*!
* @memberof WpSpaType
* @param type: a type id
*
* Returns: %TRUE if the @type is a SPA_TYPE_Id, %FALSE otherwise
* @returns %TRUE if the @em type is a SPA_TYPE_Id, %FALSE otherwise
*/
gboolean
wp_spa_type_is_id (WpSpaType type)
{
@@ -228,12 +240,13 @@ wp_spa_type_is_id (WpSpaType type)
return info ? (info->parent == SPA_TYPE_Id) : FALSE;
}
/**
* wp_spa_type_is_object:
* @type: a type id
/*!
* @memberof WpSpaType
* @param type: a type id
*
* Returns: %TRUE if the @type is a SPA_TYPE_Object, %FALSE otherwise
* @returns %TRUE if the @em type is a SPA_TYPE_Object, %FALSE otherwise
*/
gboolean
wp_spa_type_is_object (WpSpaType type)
{
@@ -241,18 +254,19 @@ wp_spa_type_is_object (WpSpaType type)
return info ? (info->parent == SPA_TYPE_Object) : FALSE;
}
/**
* wp_spa_type_get_object_id_values_table:
* @type: the type id of an object type
/*!
* @memberof WpSpaType
* @param type: the type id of an object type
*
* Object pods (see #WpSpaPod) always have a special "id" field along with
* @brief Object pods (see [WpSpaPod](@ref spa_pod_section)) always have a special "id" field along with
* other fields that can be defined. This "id" field can only store values
* of a specific `SPA_TYPE_Id` type. This function returns the table that
* contains the possible values for that field.
*
* Returns: the table with the values that can be stored in the special "id"
* field of an object of the given @type
* @returns the table with the values that can be stored in the special "id"
* field of an object of the given @em type
*/
WpSpaIdTable
wp_spa_type_get_object_id_values_table (WpSpaType type)
{
@@ -267,13 +281,14 @@ wp_spa_type_get_object_id_values_table (WpSpaType type)
return info->values->values;
}
/**
* wp_spa_type_get_values_table:
* @type: a type id
/*!
* @memberof WpSpaType
* @param type: a type id
*
* Returns: the associated #WpSpaIdTable that contains possible
* @returns the associated [WpSpaIdTable](@ref spa_id_table_section) that contains possible
* values or object fields for this type, or %NULL
*/
WpSpaIdTable
wp_spa_type_get_values_table (WpSpaType type)
{
@@ -283,7 +298,6 @@ wp_spa_type_get_values_table (WpSpaType type)
return info->values;
}
struct spa_type_info_iterator_data
{
const struct spa_type_info *base;
@@ -338,18 +352,20 @@ static const WpIteratorMethods spa_type_info_iterator_methods = {
.fold = spa_type_info_iterator_fold,
};
/**
* wp_spa_id_table_from_name:
* @name: the full name of an id table
/*!
* @memberof WpSpaType
* @param name: the full name of an id table
*
* Finds a #WpSpaIdTable given its name. This name can either be the full type
* @brief Finds a [WpSpaIdTable](@ref spa_id_table_section) given its name.
* This name can either be the full type
* name of an object type, or the name of an enum (which is not(!!) a type).
*
* For example, "Spa:Pod:Object:Param:Format" and "Spa:Enum:ParamId" are
* both valid table names.
*
* Returns: (nullable): the associated table, or %NULL
* @returns (nullable): the associated table, or %NULL
*/
WpSpaIdTable
wp_spa_id_table_from_name (const gchar *name)
{
@@ -379,16 +395,18 @@ wp_spa_id_table_from_name (const gchar *name)
return tinfo ? tinfo->values : NULL;
}
/**
* wp_spa_id_table_new_iterator:
* @table: the id table
/*!
* @memberof WpSpaType
* @param table: the id table
*
* This function returns an iterator that allows you to iterate through the
* @brief This function returns an iterator that allows you to iterate through the
* values associated with this table.
* The items in the iterator are of type #WpSpaIdValue.
* The items in the iterator are of type [WpSpaIdValue](@ref spa_id_value_section).
*
* Returns: a #WpIterator that iterates over #WpSpaIdValue items
* @returns a [WpIterator](@ref iterator_section) that iterates over
* [WpSpaIdValue](@ref spa_id_value_section) items
*/
WpIterator *
wp_spa_id_table_new_iterator (WpSpaIdTable table)
{
@@ -402,13 +420,15 @@ wp_spa_id_table_new_iterator (WpSpaIdTable table)
return it;
}
/**
* wp_spa_id_table_find_value:
* @table: the id table
* @value: a numeric value that is contained in the table
/*!
* @memberof WpSpaType
* @param table: the id table
* @param value: a numeric value that is contained in the table
*
* Returns: (nullable): the #WpSpaIdValue associated with @value, or %NULL
* @returns (nullable): the [WpSpaIdValue](@ref spa_id_value_section)
* associated with @em value, or %NULL
*/
WpSpaIdValue
wp_spa_id_table_find_value (WpSpaIdTable table, guint value)
{
@@ -423,13 +443,15 @@ wp_spa_id_table_find_value (WpSpaIdTable table, guint value)
return NULL;
}
/**
* wp_spa_id_table_find_value_from_name:
* @table: the id table
* @name: the full name of a value that is contained in the table
/*!
* @memberof WpSpaType
* @param table: the id table
* @param name: the full name of a value that is contained in the table
*
* Returns: (nullable): the #WpSpaIdValue associated with @name, or %NULL
* @returns (nullable): the [WpSpaIdValue](@ref spa_id_value_section)
* associated with @em name, or %NULL
*/
WpSpaIdValue
wp_spa_id_table_find_value_from_name (WpSpaIdTable table, const gchar * name)
{
@@ -444,13 +466,15 @@ wp_spa_id_table_find_value_from_name (WpSpaIdTable table, const gchar * name)
return NULL;
}
/**
* wp_spa_id_table_find_value_from_short_name:
* @table: the id table
* @short_name: the short name of a value that is contained in the table
/*!
* @memberof WpSpaType
* @param table: the id table
* @param short_name: the short name of a value that is contained in the table
*
* Returns: (nullable): the #WpSpaIdValue associated with @short_name, or %NULL
* @returns (nullable): the [WpSpaIdValue](@ref spa_id_value_section)
* associated with @em short_name, or %NULL
*/
WpSpaIdValue
wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
const gchar * short_name)
@@ -466,7 +490,6 @@ wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
return NULL;
}
static WpSpaIdTable
wp_spa_id_name_find_id_table (const gchar * name)
{
@@ -490,16 +513,17 @@ wp_spa_id_name_find_id_table (const gchar * name)
return table;
}
/**
* wp_spa_id_value_from_name:
* @name: the full name of an id value
/*!
* @memberof WpSpaType
* @param name: the full name of an id value
*
* Looks up an id value (enum, flag or object field) directly from its full
* @brief Looks up an id value (enum, flag or object field) directly from its full
* name. For instance, "Spa:Enum:Direction:Input" will resolve to the
* id value that represents "Input" in the "Spa:Enum:Direction" enum.
*
* Returns: the id value for @name, or %NULL if no such id value was found
* @returns the id value for @em name, or %NULL if no such id value was found
*/
WpSpaIdValue
wp_spa_id_value_from_name (const gchar * name)
{
@@ -509,15 +533,16 @@ wp_spa_id_value_from_name (const gchar * name)
return wp_spa_id_table_find_value_from_name (table, name);
}
/**
* wp_spa_id_value_from_short_name:
* @table_name: the name of the #WpSpaIdTable to look up the value in
* @short_name: the short name of the value to look up
/*!
* @memberof WpSpaType
* @param table_name: the name of the [WpSpaIdTable](@ref spa_id_table_section) to look up the value in
* @param short_name: the short name of the value to look up
*
* Looks up an id value given its container @table_name and its @short_name
* @brief Looks up an id value given its container @em table_name and its @em short_name
*
* Returns: the id value or %NULL if it was not found
* @returns the id value or %NULL if it was not found
*/
WpSpaIdValue
wp_spa_id_value_from_short_name (const gchar * table_name,
const gchar * short_name)
@@ -529,16 +554,17 @@ wp_spa_id_value_from_short_name (const gchar * table_name,
return wp_spa_id_table_find_value_from_short_name (table, short_name);
}
/**
* wp_spa_id_value_from_number:
* @table_name: the name of the #WpSpaIdTable to look up the value in
* @id: the numeric representation of the value to look up
/*!
* @memberof WpSpaType
* @param table_name: the name of the [WpSpaIdTable](@ref spa_id_table_section) to look up the value in
* @param id: the numeric representation of the value to look up
*
* Looks up an id value given its container @table_name and its numeric
* representation, @id
* @brief Looks up an id value given its container @em table_name and its numeric
* representation, @em id
*
* Returns: the id value or %NULL if it was not found
* @returns the id value or %NULL if it was not found
*/
WpSpaIdValue
wp_spa_id_value_from_number (const gchar * table_name, guint id)
{
@@ -548,12 +574,13 @@ wp_spa_id_value_from_number (const gchar * table_name, guint id)
return wp_spa_id_table_find_value (table, id);
}
/**
* wp_spa_id_value_number:
* @id: an id value
/*!
* @memberof WpSpaType
* @param id: an id value
*
* Returns: the numeric representation of this id value
* @returns the numeric representation of this id value
*/
guint
wp_spa_id_value_number (WpSpaIdValue id)
{
@@ -563,12 +590,13 @@ wp_spa_id_value_number (WpSpaIdValue id)
return info->type;
}
/**
* wp_spa_id_value_name:
* @id: an id value
/*!
* @memberof WpSpaType
* @param id: an id value
*
* Returns: the full name of this id value
* @returns the full name of this id value
*/
const gchar *
wp_spa_id_value_name (WpSpaIdValue id)
{
@@ -578,12 +606,13 @@ wp_spa_id_value_name (WpSpaIdValue id)
return info->name;
}
/**
* wp_spa_id_value_short_name:
* @id: an id value
/*!
* @memberof WpSpaType
* @param id: an id value
*
* Returns: the short name of this id value
* @returns the short name of this id value
*/
const gchar *
wp_spa_id_value_short_name (WpSpaIdValue id)
{
@@ -593,21 +622,22 @@ wp_spa_id_value_short_name (WpSpaIdValue id)
return spa_debug_type_short_name (info->name);
}
/**
* wp_spa_id_value_get_value_type
* @id: an id value
* @table: (out) (optional): the associated #WpSpaIdTable
/*!
* @memberof WpSpaType
* @param id: an id value
* @param table: (out) (optional): the associated [WpSpaIdTable](@ref spa_id_table_section)
*
* Returns the value type associated with this #WpSpaIdValue. This information
* is useful when @id represents an object field, which can take a value
* @brief Returns the value type associated with this [WpSpaIdValue](@ref spa_id_value_section).
* This information is useful when @em id represents an object field, which can take a value
* of an arbitrary type.
*
* When the returned type is (or is derived from) `SPA_TYPE_Id` or
* `SPA_TYPE_Object`, @table is set to point to the #WpSpaIdTable that contains
* the possible Id values / object fields.
* `SPA_TYPE_Object`, @em table is set to point to the [WpSpaIdTable](@ref spa_id_table_section)
* that contains the possible Id values / object fields.
*
* Returns: (transfer none): the value type associated with @id
* @returns (transfer none): the value type associated with @em id
*/
WpSpaType
wp_spa_id_value_get_value_type (WpSpaIdValue id, WpSpaIdTable * table)
{
@@ -631,21 +661,22 @@ wp_spa_id_value_get_value_type (WpSpaIdValue id, WpSpaIdTable * table)
return info->parent;
}
/**
* wp_spa_id_value_array_get_item_type:
* @id: an id value
* @table: (out) (optional): the associated #WpSpaIdTable
/*!
* @memberof WpSpaType
* @param id: an id value
* @param table: (out) (optional): the associated [WpSpaIdTable](@ref spa_id_table_section)
*
* If the value type of @id is `SPA_TYPE_Array`, this function returns the
* @brief If the value type of @em id is `SPA_TYPE_Array`, this function returns the
* type that is allowed to be contained inside the array.
*
* When the returned type is (or is derived from) `SPA_TYPE_Id` or
* `SPA_TYPE_Object`, @table is set to point to the #WpSpaIdTable that contains
* the possible Id values / object fields.
* `SPA_TYPE_Object`, @em table is set to point to the [WpSpaIdTable](@ref spa_id_table_section)
* that contains the possible Id values / object fields.
*
* Returns: (transfer none): the type that is allowed in the array, if @id
* @returns (transfer none): the type that is allowed in the array, if @em id
* represents an object field that takes an array as value
*/
WpSpaType
wp_spa_id_value_array_get_item_type (WpSpaIdValue id, WpSpaIdTable * table)
{
@@ -659,16 +690,15 @@ wp_spa_id_value_array_get_item_type (WpSpaIdValue id, WpSpaIdTable * table)
WP_SPA_TYPE_INVALID;
}
/**
* wp_spa_dynamic_type_init:
*
* Initializes the spa dynamic type registry.
/*!
* @memberof WpSpaType
* @brief Initializes the spa dynamic type registry.
* This allows registering new spa types at runtime. The spa type system
* still works if this function is not called.
*
* Normally called by wp_init() when %WP_INIT_SPA_TYPES is passed in its flags.
*/
void
wp_spa_dynamic_type_init (void)
{
@@ -682,14 +712,15 @@ wp_spa_dynamic_type_init (void)
g_array_append_val (extra_types, info);
}
/**
* wp_spa_dynamic_type_deinit:
/*!
* @memberof WpSpaType
*
* Deinitializes the spa type registry.
* @brief Deinitializes the spa type registry.
* You do not need to ever call this, unless you want to free memory at the
* end of the execution of a test, so that it doesn't show as leaked in
* the memory profiler.
*/
void
wp_spa_dynamic_type_deinit (void)
{
@@ -697,22 +728,23 @@ wp_spa_dynamic_type_deinit (void)
g_clear_pointer (&extra_id_tables, g_array_unref);
}
/**
* wp_spa_dynamic_type_register:
* @name: the name of the type
* @parent: the parent type
* @values: an array of `spa_type_info` that contains the values of the type,
/*!
* @memberof WpSpaType
* @param name: the name of the type
* @param parent: the parent type
* @param values: an array of `spa_type_info` that contains the values of the type,
* used only for Object types
*
* Registers an additional type in the spa type system.
* @brief Registers an additional type in the spa type system.
* This is useful to add a custom pod object type.
*
* Note that both @name and @values must be statically allocated, or
* Note that both @em name and @em values must be statically allocated, or
* otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit()
* is called. No memory copy is done by this function.
*
* Returns: (transfer none): the new type
* @returns (transfer none): the new type
*/
WpSpaType
wp_spa_dynamic_type_register (const gchar *name, WpSpaType parent,
const struct spa_type_info * values)
@@ -726,20 +758,21 @@ wp_spa_dynamic_type_register (const gchar *name, WpSpaType parent,
return info.type;
}
/**
* wp_spa_dynamic_id_table_register:
* @name: the name of the id table
* @values: an array of `spa_type_info` that contains the values of the table
/*!
* @memberof WpSpaType
* @param name: the name of the id table
* @param values: an array of `spa_type_info` that contains the values of the table
*
* Registers an additional #WpSpaIdTable in the spa type system.
* @brief Registers an additional [WpSpaIdTable](@ref spa_id_table_section) in the spa type system.
* This is useful to add custom enumeration types.
*
* Note that both @name and @values must be statically allocated, or
* Note that both @em name and @em values must be statically allocated, or
* otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit()
* is called. No memory copy is done by this function.
*
* Returns: the new table
* @returns the new table
*/
WpSpaIdTable
wp_spa_dynamic_id_table_register (const gchar *name,
const struct spa_type_info * values)

28
lib/wp/spa-type.h
View File

@@ -20,7 +20,13 @@ typedef gconstpointer WpSpaIdValue;
struct spa_type_info;
/* WpSpaType */
/*!
* @memberof WpSpaType
*
* @code
* #define WP_TYPE_SPA_TYPE (wp_spa_type_get_type ())
* @endcode
*/
#define WP_TYPE_SPA_TYPE (wp_spa_type_get_type ())
WP_API
GType wp_spa_type_get_type (void);
@@ -51,9 +57,13 @@ WpSpaIdTable wp_spa_type_get_object_id_values_table (WpSpaType type);
WP_API
WpSpaIdTable wp_spa_type_get_values_table (WpSpaType type);
/* WpSpaIdTable */
/*!
* @memberof WpSpaType
*
* @code
* #define WP_TYPE_SPA_ID_TABLE (wp_spa_id_table_get_type ())
* @endcode
*/
#define WP_TYPE_SPA_ID_TABLE (wp_spa_id_table_get_type ())
WP_API
GType wp_spa_id_table_get_type (void);
@@ -75,9 +85,13 @@ WP_API
WpSpaIdValue wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
const gchar * short_name);
/* WpSpaIdValue */
/*!
* @memberof WpSpaType
*
* @code
* #define WP_TYPE_SPA_ID_VALUE (wp_spa_id_value_get_type ())
* @endcode
*/
#define WP_TYPE_SPA_ID_VALUE (wp_spa_id_value_get_type ())
WP_API
GType wp_spa_id_value_get_type (void);

98
lib/wp/state.c
View File

@@ -6,11 +6,16 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: state
* @title: State Storage
/*!
* @file state.c
*/
/*!
* @struct WpState
* @section state_section State Storage
*
* The [WpState](@ref state_section) class saves and loads properties from a file
*
* The #WpState class saves and loads properties from a file
*/
#define G_LOG_DOMAIN "wp-state"
@@ -26,11 +31,32 @@
#include "log.h"
#include "state.h"
/*!
* @memberof WpState
*
* @props @b name
*
* @code
* "name" gchar *
* @endcode
*
* @brief The file name where the state will be stored.
*
* Flags : Read / Write / Construct Only
*
*/
enum {
PROP_0,
PROP_NAME,
};
/*!
* @brief
* @em parent
* @em name
* @em location
* @em keyfile
*/
struct _WpState
{
GObject parent;
@@ -135,7 +161,7 @@ wp_state_class_init (WpStateClass * klass)
object_class->set_property = wp_state_set_property;
object_class->get_property = wp_state_get_property;
/**
/*
* WpState:name:
* The file name where the state will be stored.
*/
@@ -145,12 +171,13 @@ wp_state_class_init (WpStateClass * klass)
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
}
/**
* wp_state_new:
* @name: the state name
/*!
* @memberof WpState
* @param name: the state name
*
* Returns: (transfer full): the new #WpState
* @returns (transfer full): the new [WpState](@ref state_section)
*/
WpState *
wp_state_new (const gchar *name)
{
@@ -160,12 +187,13 @@ wp_state_new (const gchar *name)
NULL);
}
/**
* wp_state_get_name:
* @self: the state
/*!
* @memberof WpState
* @param self: the state
*
* Returns: the name of this state
* @returns the name of this state
*/
const gchar *
wp_state_get_name (WpState *self)
{
@@ -174,12 +202,13 @@ wp_state_get_name (WpState *self)
return self->name;
}
/**
* wp_state_get_location:
* @self: the state
/*!
* @memberof WpState
* @param self: the state
*
* Returns: the location of this state
* @returns the location of this state
*/
const gchar *
wp_state_get_location (WpState *self)
{
@@ -189,12 +218,13 @@ wp_state_get_location (WpState *self)
return self->location;
}
/**
* wp_state_clear:
* @self: the state
/*!
* @memberof WpState
* @param self: the state
*
* Clears the state removing its file
*/
void
wp_state_clear (WpState *self)
{
@@ -205,16 +235,17 @@ wp_state_clear (WpState *self)
remove (self->location);
}
/**
* wp_state_save:
* @self: the state
* @group: the group name where the properties will be save
* @props: (transfer none): the properties to save
/*!
* @memberof WpState
* @param self: the state
* @param group: the group name where the properties will be save
* @param props: (transfer none): the properties to save
*
* Saves new properties in the state, overwriting all previous data.
* @brief Saves new properties in the state, overwriting all previous data.
*
* Returns: TRUE if the properties could be saved, FALSE otherwise
* @returns TRUE if the properties could be saved, FALSE otherwise
*/
gboolean
wp_state_save (WpState *self, const gchar *group, WpProperties *props)
{
@@ -246,15 +277,16 @@ wp_state_save (WpState *self, const gchar *group, WpProperties *props)
return TRUE;
}
/**
* wp_state_load:
* @self: the state
* @group: the group which the properties will be loaded from
/*!
* @memberof WpState
* @param self: the state
* @param group: the group which the properties will be loaded from
*
* Loads the state data into new properties.
* @brief Loads the state data into new properties.
*
* Returns (transfer full): the new properties with the state data
* @returns (transfer full): the new properties with the state data
*/
WpProperties *
wp_state_load (WpState *self, const gchar *group)
{

13
lib/wp/state.h
View File

@@ -15,10 +15,17 @@ G_BEGIN_DECLS
/* WpState */
/**
* WP_TYPE_STATE:
/*!
* @memberof WpState
*
* @brief The [WpState](@ref state_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_STATE (wp_state_get_type ())
* @endcode
*
* The #WpState #GType
*/
#define WP_TYPE_STATE (wp_state_get_type ())
WP_API

276
lib/wp/transition.c
View File

@@ -6,17 +6,22 @@
* SPDX-License-Identifier: MIT
*/
/**
* SECTION: transition
* @title: Transitions
/*!
* @file transition.c
*/
/*!
* @struct WpTransition
* @section transition_section Transitions
*
* A transition is an asynchronous operation, like #GTask, that contains
* an internal state machine, where a series of 'steps' are executed in order
* to complete the operation.
* A transition is an asynchronous operation, like
* <a href="https://developer.gnome.org/gio/stable/GTask.html">
* GTask</a>, that contains an internal state machine,
* where a series of 'steps' are executed in order to complete the operation.
*
* For every step, #WpTransitionClass.get_next_step() is called in order to
* determine the next step to execute. Afterwards,
* #WpTransitionClass.execute_step() is called
* For every step, [WpTransitionClass](@ref transition_class_section).get_next_step()
* is called in order to determine the next step to execute. Afterwards,
* [WpTransitionClass](@ref transition_class_section).execute_step() is called
* to perform any actions necessary to complete this step. When execution
* of the step is done, the operation's code must call wp_transition_advance()
* in order to continue to the next step. If an error occurs, the operation's
@@ -24,11 +29,13 @@
* transition completes immediately and wp_transition_had_error() returns %TRUE.
*
* Typically, every step will start an asynchronous operation. Although is is
* possible, the #WpTransition base class does not expect
* #WpTransitionClass.execute_step() to call wp_transition_advance() directly.
* possible, the [WpTransition](@ref transition_section) base class does not expect
* [WpTransitionClass](@ref transition_class_section).execute_step()
* to call wp_transition_advance() directly.
* Instead, it is expected that wp_transition_advance() will be called from
* the callback that the step's asyncrhonous operation will call when it is
* completed.
*
*/
#define G_LOG_DOMAIN "wp-transition"
@@ -57,6 +64,18 @@ struct _WpTransitionPrivate
GError *error;
};
/*!
* @memberof WpTransition
*
* @props @b completed
*
* @code
* "completed" gboolean
* @endcode
*
* Flags : Read
*
*/
enum {
PROP_0,
PROP_COMPLETED,
@@ -114,10 +133,10 @@ wp_transition_class_init (WpTransitionClass * klass)
object_class->finalize = wp_transition_finalize;
object_class->get_property = wp_transition_get_property;
/**
/*
* WpTransition::completed:
*
* Whether the transition has completed, meaning its callback (if set)
* @brief Whether the transition has completed, meaning its callback (if set)
* has been invoked. This can only happen after the final step has been
* reached or wp_transition_return_error() has been called.
*
@@ -150,27 +169,37 @@ wp_transition_async_result_init (GAsyncResultIface * iface)
(gboolean (*)(GAsyncResult *, gpointer)) wp_transition_is_tagged;
}
/**
* wp_transition_new:
* @type: the #GType of the #WpTransition subclass to instantiate
* @source_object: (nullable) (type GObject): the #GObject that owns this task,
* or %NULL
* @cancellable: (nullable): optional #GCancellable
* @callback: (scope async): a #GAsyncReadyCallback
* @callback_data: (closure): user data passed to @callback
/*!
*
* Creates a #WpTransition acting on @source_object. When the transition is
* done, @callback will be invoked.
* @memberof WpTransition
*
* @param type: the
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a> of the [WpTransition](@ref transition_section) subclass to instantiate
* @param source_object: (nullable) (type GObject): the
* <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject">
* GObject</a> that owns this task, or %NULL
* @param cancellable: (nullable): optional
* <a href="https://developer.gnome.org/gio/stable/GCancellable.html">
* GCancellable</a>
* @param callback: (scope async): a
* <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
* GAsyncReadyCallback</a>
* @param callback_data: (closure): user data passed to @em callback
*
* @brief Creates a [WpTransition](@ref transition_section) acting on @em source_object. When the transition is
* done, @em callback will be invoked.
*
* The transition does not automatically start executing steps. You must
* call wp_transition_advance() after creating it in order to start it.
*
* Note that the transition is automatically unref'ed after the @callback
* Note that the transition is automatically unref'ed after the @em callback
* has been executed. If you wish to keep an additional reference on it,
* you need to ref it explicitly.
*
* Returns: (transfer none): the new transition
* @returns (transfer none): the new transition
*/
WpTransition *
wp_transition_new (GType type,
gpointer source_object, GCancellable * cancellable,
@@ -180,26 +209,37 @@ wp_transition_new (GType type,
g_cclosure_new (G_CALLBACK (callback), callback_data, NULL));
}
/**
* wp_transition_new_closure:
* @type: the #GType of the #WpTransition subclass to instantiate
* @source_object: (nullable) (type GObject): the #GObject that owns this task,
* or %NULL
* @cancellable: (nullable): optional #GCancellable
* @closure: (nullable): a #GAsyncReadyCallback wrapped in a #GClosure
/*!
* @memberof WpTransition
* @param type: the
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
* of the [WpTransition](@ref transition_section) subclass to instantiate
* @param source_object: (nullable) (type GObject): the
* <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject">
* GObject</a> that owns this task, or %NULL
* @param cancellable: (nullable): optional
* <a href="https://developer.gnome.org/gio/stable/GCancellable.html">
* GCancellable</a>
* @param closure: (nullable): a
* <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
* GAsyncReadyCallback</a> wrapped in a
* <a href="https://developer.gnome.org/gobject/stable/gobject-Closures.html#GClosure">
* GClosure</a>
*
* Creates a #WpTransition acting on @source_object. When the transition is
* done, @closure will be invoked.
* @brief Creates a [WpTransition](@ref transition_section) acting on @em source_object.
* When the transition is done, @em closure will be invoked.
*
* The transition does not automatically start executing steps. You must
* call wp_transition_advance() after creating it in order to start it.
*
* Note that the transition is automatically unref'ed after the @closure
* Note that the transition is automatically unref'ed after the @em closure
* has been executed. If you wish to keep an additional reference on it,
* you need to ref it explicitly.
*
* Returns: (transfer none): the new transition
* @returns (transfer none): the new transition
*/
WpTransition *
wp_transition_new_closure (GType type, gpointer source_object,
GCancellable * cancellable, GClosure * closure)
@@ -223,15 +263,16 @@ wp_transition_new_closure (GType type, gpointer source_object,
return self;
}
/**
* wp_transition_get_source_object:
* @self: the transition
/*!
* @memberof WpTransition
* @param self: the transition
*
* Gets the source object from the transition.
* @brief Gets the source object from the transition.
* Like g_async_result_get_source_object(), but does not ref the object.
*
* Returns: (transfer none) (type GObject): the source object
* @returns (transfer none) (type GObject): the source object
*/
gpointer
wp_transition_get_source_object (WpTransition * self)
{
@@ -241,16 +282,17 @@ wp_transition_get_source_object (WpTransition * self)
return priv->source_object;
}
/**
* wp_transition_is_tagged:
* @self: the transition
* @tag: a tag
/*!
* @memberof WpTransition
* @param self: the transition
* @param tag: a tag
*
* Checks if @self has the given @tag (generally a function pointer
* indicating the function @self was created by).
* @brief Checks if @em self has the given @em tag (generally a function pointer
* indicating the function @em self was created by).
*
* Returns: TRUE if @self has the indicated @tag , FALSE if not.
* @returns TRUE if @em self has the indicated @em tag , FALSE if not.
*/
gboolean
wp_transition_is_tagged (WpTransition * self, gpointer tag)
{
@@ -260,14 +302,15 @@ wp_transition_is_tagged (WpTransition * self, gpointer tag)
return (priv->tag == tag);
}
/**
* wp_transition_get_source_tag:
* @self: the transition
/*!
* @memberof WpTransition
* @param self: the transition
*
* Gets @self 's source tag. See wp_transition_set_source_tag().
* @brief Gets @em self 's source tag. See wp_transition_set_source_tag().
*
* Returns: (transfer none): the transition's source tag
* @returns (transfer none): the transition's source tag
*/
gpointer
wp_transition_get_source_tag (WpTransition * self)
{
@@ -277,17 +320,18 @@ wp_transition_get_source_tag (WpTransition * self)
return priv->tag;
}
/**
* wp_transition_set_source_tag:
* @self: the transition
* @tag: an opaque pointer indicating the source of this transition
/*!
* @memberof WpTransition
* @param self: the transition
* @param tag: an opaque pointer indicating the source of this transition
*
* Sets @self 's source tag. You can use this to tag a transition's return
* @brief Sets @em self 's source tag. You can use this to tag a transition's return
* value with a particular pointer (usually a pointer to the function doing
* the tagging) and then later check it using wp_transition_get_source_tag()
* (or g_async_result_is_tagged()) in the transition's "finish" function,
* to figure out if the response came from a particular place.
*/
void
wp_transition_set_source_tag (WpTransition * self, gpointer tag)
{
@@ -297,14 +341,15 @@ wp_transition_set_source_tag (WpTransition * self, gpointer tag)
priv->tag = tag;
}
/**
* wp_transition_get_data:
* @self: the transition
/*!
* @memberof WpTransition
* @param self: the transition
*
* Gets @self 's data. See wp_transition_set_data().
* @brief Gets @em self 's data. See wp_transition_set_data().
*
* Returns: (transfer none): the transition's data
* @returns (transfer none): the transition's data
*/
gpointer
wp_transition_get_data (WpTransition * self)
{
@@ -314,15 +359,19 @@ wp_transition_get_data (WpTransition * self)
return priv->data;
}
/**
* wp_transition_set_data:
* @self: the transition
* @data: (nullable): transition-specific user data
* @data_destroy: (nullable): #GDestroyNotify for @data
/*!
* @memberof WpTransition
* @param self: the transition
* @param data: (nullable): transition-specific user data
* @param data_destroy: (nullable):
* <a href="https://developer.gnome.org/glib/stable/glib-Datasets.html#GDestroyNotify">
* GDestroyNotify</a>
* for @em data
*
* Sets @self 's data (freeing the existing data, if any). This can be an
* @brief Sets @em self 's data (freeing the existing data, if any). This can be an
* arbitrary user structure that holds data associated with this transition.
*/
void
wp_transition_set_data (WpTransition * self, gpointer data,
GDestroyNotify data_destroy)
@@ -336,13 +385,14 @@ wp_transition_set_data (WpTransition * self, gpointer data,
priv->data_destroy = data_destroy;
}
/**
* wp_transition_get_completed:
* @self: the transition
/*!
* @memberof WpTransition
* @param self: the transition
*
* Returns: %TRUE if the transition has completed (with or without an error),
* @returns %TRUE if the transition has completed (with or without an error),
* %FALSE otherwise
*/
gboolean
wp_transition_get_completed (WpTransition * self)
{
@@ -353,12 +403,13 @@ wp_transition_get_completed (WpTransition * self)
priv->step == WP_TRANSITION_STEP_ERROR;
}
/**
* wp_transition_had_error:
* @self: the transition
/*!
* @memberof WpTransition
* @param self: the transition
*
* Returns: %TRUE if the transition completed with an error, %FALSE otherwise
* @returns %TRUE if the transition completed with an error, %FALSE otherwise
*/
gboolean
wp_transition_had_error (WpTransition * self)
{
@@ -388,32 +439,35 @@ wp_transition_return (WpTransition * self, WpTransitionPrivate *priv)
g_object_unref (self);
}
/**
* wp_transition_advance:
* @self: the transition
/*!
* @memberof WpTransition
* @param self: the transition
*
* Advances the transition to the next step.
* @brief Advances the transition to the next step.
*
* This initially calls #WpTransitionClass.get_next_step() in order to determine
* what the next step is. If #WpTransitionClass.get_next_step() returns a step
* different than the previous one, it calls #WpTransitionClass.execute_step()
* to execute it.
* This initially calls [WpTransitionClass](@ref transition_class_section).get_next_step()
* in order to determine what the next step is.
* If [WpTransitionClass](@ref transition_class_section).get_next_step() returns a step
* different than the previous one, it calls
* [WpTransitionClass](@ref transition_class_section).execute_step() to execute it.
*
* The very first time that #WpTransitionClass.get_next_step() is called, its
* @step parameter equals %WP_TRANSITION_STEP_NONE.
* The very first time that [WpTransitionClass](@ref transition_class_section).get_next_step()
* is called, its @em step parameter equals %WP_TRANSITION_STEP_NONE.
*
* When #WpTransitionClass.get_next_step() returns %WP_TRANSITION_STEP_NONE,
* this function completes the transition, calling the transition's callback
* and then unref-ing the transition.
* When [WpTransitionClass](@ref transition_class_section).get_next_step() returns
* %WP_TRANSITION_STEP_NONE this function completes the transition, calling the transition's
* callback and then unref-ing the transition.
*
* When #WpTransitionClass.get_next_step() returns %WP_TRANSITION_STEP_ERROR,
* this function calls wp_transition_return_error(), unless it has already been
* called directly by #WpTransitionClass.get_next_step().
* When [WpTransitionClass](@ref transition_class_section).get_next_step() returns
* %WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error(),
* unless it has already been called directly by
* [WpTransitionClass](@ref transition_class_section).get_next_step().
*
* In error conditions, #WpTransitionClass.execute_step() is called once with
* @step being %WP_TRANSITION_STEP_ERROR, allowing the implementation to
* In error conditions, [WpTransitionClass](@ref transition_class_section).execute_step()
* is called once with @em step being %WP_TRANSITION_STEP_ERROR, allowing the implementation to
* rollback any changes or cancel underlying jobs, if necessary.
*/
void
wp_transition_advance (WpTransition * self)
{
@@ -465,17 +519,20 @@ wp_transition_advance (WpTransition * self)
WP_TRANSITION_GET_CLASS (self)->execute_step (self, priv->step);
}
/**
* wp_transition_return_error:
* @self: the transition
* @error: (transfer full): a #GError
/*!
* @memberof WpTransition
* @param self: the transition
* @param error: (transfer full): a
* <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a>
*
* Completes the transition with an error. This can be called anytime
* @brief Completes the transition with an error. This can be called anytime
* from within any virtual function or an async job handler.
*
* Note that in most cases this will also unref the transition, so it is
* not safe to access it after this function has been called.
*/
void
wp_transition_return_error (WpTransition * self, GError * error)
{
@@ -499,18 +556,23 @@ wp_transition_return_error (WpTransition * self, GError * error)
wp_transition_return (self, priv);
}
/**
* wp_transition_finish:
* @res: a transition, as a #GAsyncResult
* @error: (out) (optional): a location to return the transition's error, if any
/*!
* @memberof WpTransition
* @param res: a transition, as a
* <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncResult-struct">
* GAsyncResult</a>
* @param error: (out) (optional): a location to return the transition's error, if any
*
* This is meant to be called from within the #GAsyncReadyCallback that was
* specified in wp_transition_new(). It returns the final return status
* @brief This is meant to be called from within the
* <a herf="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
* GAsyncReadyCallback</a>
* that was specified in wp_transition_new(). It returns the final return status
* of the transition and its error, if there was one.
*
* Returns: %TRUE if the transition completed successfully, %FALSE if there
* @returns %TRUE if the transition completed successfully, %FALSE if there
* was an error
*/
gboolean
wp_transition_finish (GAsyncResult * res, GError ** error)
{

36
lib/wp/transition.h
View File

@@ -14,21 +14,33 @@
G_BEGIN_DECLS
/**
* WP_TYPE_TRANSITION:
/*!
* @memberof WpTransition
*
* @brief The [WpTransition](@ref transition_section)
* <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
* GType</a>
*
* @code
* #define WP_TYPE_TRANSITION (wp_transition_get_type ())
* @endcode
*
* The #WpTransition #GType
*/
#define WP_TYPE_TRANSITION (wp_transition_get_type ())
WP_API
G_DECLARE_DERIVABLE_TYPE (WpTransition, wp_transition, WP, TRANSITION, GObject)
/**
* WpTransitionStep:
* @WP_TRANSITION_STEP_NONE: the initial and final step of the transition
* @WP_TRANSITION_STEP_ERROR: returned by #WpTransitionClass.get_next_step() in
/*!
* @memberof WpTransition
*
* @section transition_step_section WpTransitionStep
*
* @brief
* @em WP_TRANSITION_STEP_NONE: the initial and final step of the transition
* @em WP_TRANSITION_STEP_ERROR: returned by
* [WpTransitionClass](@ref transition_class_section).get_next_step() in
* case of an error
* @WP_TRANSITION_STEP_CUSTOM_START: starting value for steps defined in
* @em WP_TRANSITION_STEP_CUSTOM_START: starting value for steps defined in
* subclasses
*/
typedef enum {
@@ -37,10 +49,10 @@ typedef enum {
WP_TRANSITION_STEP_CUSTOM_START = 0x10
} WpTransitionStep;
/**
* WpTransitionClass:
* @get_next_step: See wp_transition_advance()
* @execute_step: See wp_transition_advance()
/*!
* @brief
* @em get_next_step: See wp_transition_advance()
* @em execute_step: See wp_transition_advance()
*/
struct _WpTransitionClass
{

61
lib/wp/wp.c
View File

@@ -6,41 +6,30 @@
* SPDX-License-Identifier: MIT
*/
/*!
* @file wp.c
*/
#define G_LOG_DOMAIN "wp"
#include "wp.h"
#include <pipewire/pipewire.h>
/**
* SECTION: wp
* @title: Library Initialization
/*!
* @struct Wp
*
* @section wp_section Wp
*
*/
/**
* WpInitFlags:
* @WP_INIT_PIPEWIRE: Initializes libpipewire by calling `pw_init()`
* @WP_INIT_SPA_TYPES: Initializes WirePlumber's SPA types integration,
* required for using #WpSpaPod among other things
* @WP_INIT_SET_PW_LOG: Enables redirecting debug log messages from
* libpipewire to GLib's logging system, by installing WirePlumber's
* implementation of `struct spa_log` (see wp_spa_log_get_instance())
* with `pw_log_set()`
* @WP_INIT_SET_GLIB_LOG: Installs WirePlumber's debug log handler,
* wp_log_writer_default(), on GLib with g_log_set_writer_func()
* @WP_INIT_ALL: Enables all of the above
/*!
* @memberof Wp
* @param flags: initialization flags
*
* See wp_init()
*/
/**
* wp_init:
* @flags: initialization flags
*
* Initializes WirePlumber and PipeWire underneath. @flags can modify
* @brief Initializes WirePlumber and PipeWire underneath. @em flags can modify
* which parts are initialized, in cases where you want to handle part
* of this initialization externally.
*/
void
wp_init (WpInitFlags flags)
{
@@ -78,6 +67,14 @@ wp_init (WpInitFlags flags)
g_type_ensure (WP_TYPE_PORT);
}
/*!
* @memberof Wp
*
* @param Void
*
* @returns The Wireplumber module directory
*/
const gchar *
wp_get_module_dir (void)
{
@@ -90,6 +87,14 @@ wp_get_module_dir (void)
return module_dir;
}
/*!
* @memberof Wp
*
* @param Void
*
* @returns The Wireplumber config directory
*/
const gchar *
wp_get_config_dir (void)
{
@@ -102,6 +107,14 @@ wp_get_config_dir (void)
return config_dir;
}
/*!
* @memberof Wp
*
* @param Void
*
* @returns The Wireplumber data directory
*/
const gchar *
wp_get_data_dir (void)
{

10
lib/wp/wp.h
View File

@@ -41,6 +41,16 @@
G_BEGIN_DECLS
/*!
* @memberof Wp
*
* @brief
* @arg WP_INIT_PIPEWIRE
* @arg WP_INIT_SPA_TYPES
* @arg WP_INIT_SET_PW_LOG
* @arg WP_INIT_SET_GLIB_LOG
* @arg WP_INIT_ALL
*/
typedef enum {
WP_INIT_PIPEWIRE = (1<<0),
WP_INIT_SPA_TYPES = (1<<1),

2
lib/wplua/closure.c
View File

@@ -119,7 +119,7 @@ _wplua_closure_finalize (lua_State *L, WpLuaClosure *c)
/**
* wplua_function_to_closure:
*
* Make a GClosure out of a Lua function at index @idx
* Make a GClosure out of a Lua function at index @em idx
*
* Returns: (transfer floating): the new closure
*/

14
lib/wplua/wplua.h
View File

@@ -20,7 +20,8 @@ G_BEGIN_DECLS
/**
* WP_DOMAIN_LUA:
*
* A #GError domain for errors that occurred within the context of the
* @brief A <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a> domain for errors that occurred within the context of the
* WirePlumber lua library.
*/
#define WP_DOMAIN_LUA (wp_domain_lua_quark ())
@@ -28,11 +29,14 @@ GQuark wp_domain_lua_quark (void);
/**
* WpLuaError:
* @WP_LUA_ERROR_COMPILATION: a compilation error, i.e. invalid Lua code
* @WP_LUA_ERROR_RUNTIME: a runtime error, i.e. misbehaving Lua code
*
* Error codes that can appear in a #GError when the error domain
* is %WP_DOMAIN_LUA
* @brief
* @em WP_LUA_ERROR_COMPILATION: a compilation error, i.e. invalid Lua code
* @em WP_LUA_ERROR_RUNTIME: a runtime error, i.e. misbehaving Lua code
*
* Error codes that can appear in a
* <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
* GError</a> when the error domain is %WP_DOMAIN_LUA
*/
typedef enum {
WP_LUA_ERROR_COMPILATION,

26
modules/module-portal-permissionstore/plugin.c
View File

@@ -252,8 +252,10 @@ wp_portal_permissionstore_plugin_class_init (
/**
* WpPortalPermissionStorePlugin::lookup:
* @table: the table name
* @id: the Id name
*
* @brief
* @em table: the table name
* @em id: the Id name
*
* Returns: (transfer full): the GVariant with permissions
*/
@@ -266,10 +268,12 @@ wp_portal_permissionstore_plugin_class_init (
/**
* WpPortalPermissionStorePlugin::set:
* @table: the table name
* @create: whether to create the table if it does not exist
* @id: the Id name
* @permissions: the permissions
*
* @brief
* @em table: the table name
* @em create: whether to create the table if it does not exist
* @em id: the Id name
* @em permissions: the permissions
*
* Sets the permissions in the permission store
*/
@@ -282,10 +286,12 @@ wp_portal_permissionstore_plugin_class_init (
/**
* WpPortalPermissionStorePlugin::changed:
* @table: the table name
* @id: the Id name
* @deleted: whether the permission was deleted or not
* @permissions: the GVariant with permissions
*
* @brief
* @em table: the table name
* @em id: the Id name
* @em deleted: whether the permission was deleted or not
* @em permissions: the GVariant with permissions
*
* Signaled when the permissions changed
*/

20
modules/module-reserve-device/plugin.c
View File

@@ -165,7 +165,7 @@ wp_reserve_device_plugin_create_reservation (WpReserveDevicePlugin *self,
"priority", priority,
NULL);
/* use rd->name to avoid copying @name again */
/* use rd->name to avoid copying @em name again */
g_hash_table_insert (self->reserve_devices, rd->name, rd);
return g_object_ref (rd);
@@ -230,10 +230,12 @@ wp_reserve_device_plugin_class_init (WpReserveDevicePluginClass * klass)
/**
* WpReserveDevicePlugin::create-reservation:
* @name:
* @app_name:
* @app_dev_name:
* @priority:
*
* @brief
* @em name:
* @em app_name:
* @em app_dev_name:
* @em priority:
*
* Returns: (transfer full): the reservation object
*/
@@ -246,7 +248,9 @@ wp_reserve_device_plugin_class_init (WpReserveDevicePluginClass * klass)
/**
* WpReserveDevicePlugin::destroy-reservation:
* @name:
*
* @brief
* @em name:
*
*/
signals[ACTION_DESTROY_RESERVATION] = g_signal_new_class_handler (
@@ -258,7 +262,9 @@ wp_reserve_device_plugin_class_init (WpReserveDevicePluginClass * klass)
/**
* WpReserveDevicePlugin::get-reservation:
* @name:
*
* @brief
* @em name:
*
* Returns: (transfer full): the reservation object
*/

31
modules/module-reserve-device/reserve-device.c
View File

@@ -12,6 +12,9 @@
#include "reserve-device-interface.h"
#include "reserve-device-enums.h"
/*
* WpReserveDevice:
*/
G_DEFINE_TYPE (WpReserveDevice, wp_reserve_device, G_TYPE_OBJECT)
enum
@@ -311,6 +314,11 @@ wp_reserve_device_set_property (GObject * object,
}
}
/**
* wp_reserve_device_class_init
*
* @param klass: the reserve device class
*/
static void
wp_reserve_device_class_init (WpReserveDeviceClass * klass)
{
@@ -357,8 +365,9 @@ wp_reserve_device_class_init (WpReserveDeviceClass * klass)
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
* WpReserveDevice::acquire:
* WpReserveDevice acquire:
*
* @section signal_acquire_section acquire
*/
signals[ACTION_ACQUIRE] = g_signal_new_class_handler (
"acquire", G_TYPE_FROM_CLASS (klass),
@@ -367,8 +376,9 @@ wp_reserve_device_class_init (WpReserveDeviceClass * klass)
NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
* WpReserveDevice::release:
* WpReserveDevice release:
*
* @section signal_release_section release
*/
signals[ACTION_RELEASE] = g_signal_new_class_handler (
"release", G_TYPE_FROM_CLASS (klass),
@@ -377,8 +387,9 @@ wp_reserve_device_class_init (WpReserveDeviceClass * klass)
NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
* WpReserveDevice::deny-release:
* WpReserveDevice deny-release:
*
* @section signal_deny_release_section deny-release
*/
signals[ACTION_DENY_RELEASE] = g_signal_new_class_handler (
"deny-release", G_TYPE_FROM_CLASS (klass),
@@ -387,13 +398,17 @@ wp_reserve_device_class_init (WpReserveDeviceClass * klass)
NULL, NULL, NULL, G_TYPE_NONE, 0);
/**
* WpReserveDevice::release-requested:
* @forced: %TRUE if the name was forcibly taken from us,
* WpReserveDevice release-requested:
*
* @section signal_release_requested_section release-requested
*
* @em forced: %TRUE if the name was forcibly taken from us,
* %FALSE if the `RequestRelease()` d-bus method was called
*
* Signaled when the device needs to be released. If @forced is %FALSE,
* call #WpReserveDevice::release to release or #WpReserveDevice::deny-release
* to refuse and return %FALSE from the `RequestRelease()` d-bus method
* @brief Signaled when the device needs to be released. If @em forced is %FALSE,
* call [release](@ref signal_release_section) to release or
* [deny-release](@ref signal_deny_release_section)
* to refuse and return %FALSE from the `RequestRelease()` d-bus method.
*/
signals[SIGNAL_RELEASE_REQUESTED] = g_signal_new (
"release-requested", G_TYPE_FROM_CLASS (klass),