Debian Codegraph @

lib/wp/si-interfaces.c

raw
1 /* WirePlumber
2 *
3 * Copyright © 2020 Collabora Ltd.
4 * @author George Kiagiadakis <[email protected]>
5 *
6 * SPDX-License-Identifier: MIT
7 */
8
9 #include "si-interfaces.h"
10 #include "wpenums.h"
11 #include "log.h"
12
13 WP_DEFINE_LOCAL_LOG_TOPIC ("wp-si-interfaces")
14
15 /*! \defgroup wpsiinterfaces Session Item Interfaces */
16
17 /*!
18 * \struct WpSiAdapter
19 * An interface for port adapters
20 *
21 * \gsignals
22 *
23 * \par adapter-ports-state-changed
24 * \parblock
25 * \code
26 * void
27 * adapter_ports_state_changed_callback (WpSiAdapter * self,
28 * gpointer user_data)
29 * \endcode
30 * Emitted when the ports state changes
31 *
32 * Flags: G_SIGNAL_RUN_LAST
33 * \endparblock
34 */
35
36 G_DEFINE_INTERFACE (WpSiAdapter, wp_si_adapter, WP_TYPE_SESSION_ITEM)
37
38 static void
39 wp_si_adapter_default_init (WpSiAdapterInterface * iface)
40 {
41 g_signal_new ("adapter-ports-state-changed", G_TYPE_FROM_INTERFACE (iface),
42 G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE,
43 2, WP_TYPE_SI_ADAPTER_PORTS_STATE, WP_TYPE_SI_ADAPTER_PORTS_STATE);
44 }
45
46 /**
47 * \brief Gets the ports state
48 *
49 * \ingroup wpsiinterfaces
50 * \param self the session item
51 * \returns The state of the ports
52 * \since 0.4.10
53 */
54 WpSiAdapterPortsState
55 wp_si_adapter_get_ports_state (WpSiAdapter * self)
56 {
57 g_return_val_if_fail (WP_IS_SI_ADAPTER (self), WP_SI_ADAPTER_PORTS_STATE_NONE);
58 g_return_val_if_fail (WP_SI_ADAPTER_GET_IFACE (self)->get_ports_state,
59 WP_SI_ADAPTER_PORTS_STATE_NONE);
60
61 return WP_SI_ADAPTER_GET_IFACE (self)->get_ports_state (self);
62 }
63
64 /**
65 * \brief Gets the format used to configure the adapter session item's ports
66 *
67 * \ingroup wpsiinterfaces
68 * \param self the session item
69 * \param mode (out) (nullable): the mode
70 * \returns (transfer full): The format used to configure the ports of the
71 * adapter session item. Some items automatically choose a format when being
72 * activated, others never set a format on activation and the user needs to
73 * manually set it externally with wp_si_adapter_set_ports_format().
74 */
75 WpSpaPod *
76 wp_si_adapter_get_ports_format (WpSiAdapter * self, const gchar **mode)
77 {
78 g_return_val_if_fail (WP_IS_SI_ADAPTER (self), NULL);
79 g_return_val_if_fail (WP_SI_ADAPTER_GET_IFACE (self)->get_ports_format, NULL);
80
81 return WP_SI_ADAPTER_GET_IFACE (self)->get_ports_format (self, mode);
82 }
83
84 /*!
85 * \brief Sets the format and configures the adapter session item ports using
86 * the given format.
87 *
88 * The result of the operation can be checked using the
89 * wp_si_adapter_set_ports_format_finish() API. If format is NULL, the adapter
90 * will be configured with the default format. If mode is NULL, the adapter
91 * will use "dsp" mode.
92 *
93 * \ingroup wpsiinterfaces
94 * \param self the session item
95 * \param format (transfer full) (nullable): the format to be set
96 * \param mode (nullable): the mode
97 * \param callback (scope async)(closure data): the callback to call when the operation is done
98 * \param data user data for \a callback
99 */
100 void
101 wp_si_adapter_set_ports_format (WpSiAdapter * self, WpSpaPod *format,
102 const gchar *mode, GAsyncReadyCallback callback, gpointer data)
103 {
104 g_return_if_fail (WP_IS_SI_ADAPTER (self));
105 g_return_if_fail (WP_SI_ADAPTER_GET_IFACE (self)->set_ports_format);
106
107 WP_SI_ADAPTER_GET_IFACE (self)->set_ports_format (self, format, mode,
108 callback, data);
109 }
110
111 /*!
112 * \brief Finishes the operation started by wp_si_adapter_set_format().
113 * This is meant to be called in the callback that was passed to that method.
114 *
115 * \ingroup wpsiinterfaces
116 * \param self the session item
117 * \param res the async result
118 * \param error (out) (optional): the operation's error, if it occurred
119 * \returns TRUE on success, FALSE if there was an error
120 */
121 gboolean
122 wp_si_adapter_set_ports_format_finish (WpSiAdapter * self, GAsyncResult * res,
123 GError ** error)
124 {
125 g_return_val_if_fail (WP_IS_SI_ADAPTER (self), FALSE);
126 g_return_val_if_fail (WP_SI_ADAPTER_GET_IFACE (self)->set_ports_format_finish,
127 FALSE);
128
129 return WP_SI_ADAPTER_GET_IFACE (self)->set_ports_format_finish (self, res,
130 error);
131 }
132
133 /*!
134 * \struct WpSiLinkable
135 *
136 * An interface for retrieving PipeWire port information from a session item.
137 * This information is used to create links in the nodes graph.
138 */
139
140 G_DEFINE_INTERFACE (WpSiLinkable, wp_si_linkable, WP_TYPE_SESSION_ITEM)
141
142 static WpSiAcquisition *
143 wp_si_linkable_default_get_acquisition (WpSiLinkable * self)
144 {
145 return NULL;
146 }
147
148 static void
149 wp_si_linkable_default_init (WpSiLinkableInterface * iface)
150 {
151 iface->get_acquisition = wp_si_linkable_default_get_acquisition;
152 }
153
154 /*!
155 * \brief This method returns a variant of type "a(uuu)", where each tuple in
156 * the array contains the following information:
157 * - u: (guint32) node id
158 * - u: (guint32) port id (the port must belong on the node specified above)
159 * - u: (guint32) the audio channel (enum spa_audio_channel) that this port
160 * makes available, or 0 for non-audio content
161 *
162 * The order in which ports appear in this array is important when no channel
163 * information is available. The link implementation should link the ports
164 * in the order they appear. This is normally a good enough substitute for
165 * channel matching.
166 *
167 * The \a context argument can be used to get different sets of ports from
168 * the item. The following well-known contexts are defined:
169 * - NULL: get the standard ports to be linked
170 * - "monitor": get the monitor ports
171 * - "control": get the control port
172 * - "reverse": get the reverse direction ports, if this item controls a
173 * filter node, which would have ports on both directions
174 *
175 * Contexts other than NULL may only be used internally to ease the
176 * implementation of more complex item relationships. For example, a
177 * WpSessionItem that is in control of an input (sink) adapter node may
178 * implement WpSiLinkable where the NULL context will return the standard
179 * input ports and the "monitor" context will return the adapter's monitor
180 * ports. When linking this item to another item, the NULL context
181 * will always be used, but the item may internally spawn a secondary
182 * WpSessionItem that implements the "monitor" item. That secondary item
183 * may implement WpSiLinkable, chaining calls to the WpSiLinkable
184 * of the original item using the "monitor" context. This way, the monitor
185 * WpSessionItem does not need to share control of the
186 * underlying node; it only proxies calls to satisfy the API.
187 *
188 * \ingroup wpsiinterfaces
189 * \param self the session item
190 * \param context (nullable): an optional context for the ports
191 * \returns (transfer full): a GVariant containing information about the
192 * ports of this item
193 */
194 GVariant *
195 wp_si_linkable_get_ports (WpSiLinkable * self, const gchar * context)
196 {
197 g_return_val_if_fail (WP_IS_SI_LINKABLE (self), NULL);
198 g_return_val_if_fail (WP_SI_LINKABLE_GET_IFACE (self)->get_ports, NULL);
199
200 return WP_SI_LINKABLE_GET_IFACE (self)->get_ports (self, context);
201 }
202
203 /*!
204 * \brief Gets the acquisition interface associated with the item
205 *
206 * \ingroup wpsiinterfaces
207 * \param self the session item
208 *
209 * \returns (transfer none) (nullable): the acquisition interface associated
210 * with this item, or NULL if this item does not require acquiring items
211 * before linking them
212 */
213 WpSiAcquisition *
214 wp_si_linkable_get_acquisition (WpSiLinkable * self)
215 {
216 g_return_val_if_fail (WP_IS_SI_LINKABLE (self), NULL);
217 g_return_val_if_fail (
218 WP_SI_LINKABLE_GET_IFACE (self)->get_acquisition, NULL);
219
220 return WP_SI_LINKABLE_GET_IFACE (self)->get_acquisition (self);
221 }
222
223
224 /*!
225 * \struct WpSiLink
226 *
227 * An interface for session items that provide a PipeWire link.
228 *
229 * \gsignals
230 *
231 * \par link-properties-changed
232 * \parblock
233 * \code
234 * void
235 * link_properties_changed_callback (WpSiLink * self,
236 * gpointer user_data)
237 * \endcode
238 * Emitted when the properties of the link change
239 *
240 * Flags: G_SIGNAL_RUN_LAST
241 * \endparblock
242 */
243
244 G_DEFINE_INTERFACE (WpSiLink, wp_si_link, WP_TYPE_SESSION_ITEM)
245
246 static WpProperties *
247 wp_si_link_default_get_properties (WpSiLink * self)
248 {
249 return NULL;
250 }
251
252 static void
253 wp_si_link_default_init (WpSiLinkInterface * iface)
254 {
255 iface->get_properties = wp_si_link_default_get_properties;
256
257 g_signal_new ("link-properties-changed", G_TYPE_FROM_INTERFACE (iface),
258 G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
259 }
260
261 /*!
262 * \brief This should return information that is used for registering the link,
263 * as a GVariant of type a{ss} that contains additional properties to be
264 * added to the list of global properties
265 *
266 * \ingroup wpsiinterfaces
267 * \param self the session item
268 * \returns (transfer full): registration info for the link
269 */
270 GVariant *
271 wp_si_link_get_registration_info (WpSiLink * self)
272 {
273 g_return_val_if_fail (WP_IS_SI_LINK (self), NULL);
274 g_return_val_if_fail (WP_SI_LINK_GET_IFACE (self)->get_registration_info, NULL);
275
276 return WP_SI_LINK_GET_IFACE (self)->get_registration_info (self);
277 }
278
279 /*!
280 * \brief Gets the properties of the link
281 *
282 * \ingroup wpsiinterfaces
283 * \param self the session item
284 * \returns (transfer full) (nullable): the properties of the link
285 */
286 WpProperties *
287 wp_si_link_get_properties (WpSiLink * self)
288 {
289 g_return_val_if_fail (WP_IS_SI_LINK (self), NULL);
290 g_return_val_if_fail (WP_SI_LINK_GET_IFACE (self)->get_properties, NULL);
291
292 return WP_SI_LINK_GET_IFACE (self)->get_properties (self);
293 }
294
295 /*!
296 * \brief Gets the output item linked by the link
297 *
298 * \ingroup wpsiinterfaces
299 * \param self the session item
300 * \returns (transfer none): the output item that is linked by this link
301 */
302 WpSiLinkable *
303 wp_si_link_get_out_item (WpSiLink * self)
304 {
305 g_return_val_if_fail (WP_IS_SI_LINK (self), NULL);
306 g_return_val_if_fail (WP_SI_LINK_GET_IFACE (self)->get_out_item, NULL);
307
308 return WP_SI_LINK_GET_IFACE (self)->get_out_item (self);
309 }
310
311 /*!
312 * \brief Gets the input item linked by the link
313 *
314 * \ingroup wpsiinterfaces
315 * \param self the session item
316 * \returns (transfer none): the input item that is linked by this link
317 */
318 WpSiLinkable *
319 wp_si_link_get_in_item (WpSiLink * self)
320 {
321 g_return_val_if_fail (WP_IS_SI_LINK (self), NULL);
322 g_return_val_if_fail (WP_SI_LINK_GET_IFACE (self)->get_in_item, NULL);
323
324 return WP_SI_LINK_GET_IFACE (self)->get_in_item (self);
325 }
326
327 /*!
328 * \struct WpSiAcquisition
329 *
330 * This interface provides a way to request an item for linking before doing
331 * so. This allows item implementations to apply internal policy rules.
332 *
333 * A WpSiAcquisition is associated directly with a WpSiLinkable via
334 * wp_si_linkable_get_acquisition(). In order to allow switching
335 * policies, it is recommended that port info implementations use a separate
336 * session item to implement this interface and allow replacing it.
337 */
338
339 G_DEFINE_INTERFACE (WpSiAcquisition, wp_si_acquisition, WP_TYPE_SESSION_ITEM)
340
341 static void
342 wp_si_acquisition_default_init (WpSiAcquisitionInterface * iface)
343 {
344 }
345
346 /*!
347 * \brief Acquires the \a item for linking by \a acquisitor.
348 *
349 * When a link is not allowed by policy, this operation should return
350 * an error.
351 *
352 * When a link needs to be delayed for a short amount of time (ex. to apply
353 * a fade out effect on another item), this operation should finish with a
354 * delay. It is safe to assume that after this operation completes,
355 * the item will be linked immediately.
356 *
357 * \ingroup wpsiinterfaces
358 * \param self the session item
359 * \param acquisitor the link that is trying to acquire a port info item
360 * \param item the item that is being acquired
361 * \param callback (scope async)(closure data): the callback to call when the operation is done
362 * \param data user data for \a callback
363 */
364 void
365 wp_si_acquisition_acquire (WpSiAcquisition * self, WpSiLink * acquisitor,
366 WpSiLinkable * item, GAsyncReadyCallback callback, gpointer data)
367 {
368 g_return_if_fail (WP_IS_SI_ACQUISITION (self));
369 g_return_if_fail (WP_SI_ACQUISITION_GET_IFACE (self)->acquire);
370
371 WP_SI_ACQUISITION_GET_IFACE (self)->acquire (self, acquisitor, item, callback,
372 data);
373 }
374
375 /*!
376 * \brief Finishes the operation started by wp_si_acquisition_acquire().
377 * This is meant to be called in the callback that was passed to that method.
378 *
379 * \ingroup wpsiinterfaces
380 * \param self the session item
381 * \param res the async result
382 * \param error (out) (optional): the operation's error, if it occurred
383 * \returns TRUE on success, FALSE if there was an error
384 */
385 gboolean
386 wp_si_acquisition_acquire_finish (WpSiAcquisition * self, GAsyncResult * res,
387 GError ** error)
388 {
389 g_return_val_if_fail (WP_IS_SI_ACQUISITION (self), FALSE);
390 g_return_val_if_fail (WP_SI_ACQUISITION_GET_IFACE (self)->acquire_finish,
391 FALSE);
392
393 return WP_SI_ACQUISITION_GET_IFACE (self)->acquire_finish (self, res, error);
394 }
395
396 /*!
397 * \brief Releases the \a item, which means that it is being unlinked.
398 *
399 * \ingroup wpsiinterfaces
400 * \param self the session item
401 * \param acquisitor the link that had previously acquired the item
402 * \param item the port info that is being released
403 */
404 void
405 wp_si_acquisition_release (WpSiAcquisition * self, WpSiLink * acquisitor,
406 WpSiLinkable * item)
407 {
408 g_return_if_fail (WP_IS_SI_ACQUISITION (self));
409 g_return_if_fail (WP_SI_ACQUISITION_GET_IFACE (self)->release);
410
411 WP_SI_ACQUISITION_GET_IFACE (self)->release (self, acquisitor, item);
412 }