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

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)