docs: api: Replace hotdoc specific commands with Doxygen specific commands
This commit is contained in:
Raghavendra
committed by
George Kiagiadakis
George Kiagiadakis
parent
89549247f8
commit
d692f06f0d
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user