Debian Codegraph @

lib/wp/proxy-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 "proxy-interfaces.h"
10 #include "properties.h"
11 #include "log.h"
12
13 WP_DEFINE_LOCAL_LOG_TOPIC ("wp-proxy-ifaces")
14
15 /*! \defgroup wppipewireobject WpPipewireObject */
16 /*!
17 * \struct WpPipewireObject
18 *
19 * An interface for standard PipeWire objects.
20 *
21 * The common characteristic of all objects that implement this interface is
22 * the presence of an "info" structure that contains additional properties
23 * for this object (in the form of a spa_dict / pw_properties) and optionally
24 * also some parameters that can be enumerated and set on the object.
25 *
26 * \gproperties
27 *
28 * \gproperty{properties, WpProperties *, G_PARAM_READABLE,
29 * The properties of the pipewire object}
30 *
31 * \gproperty{param-info, GVariant * (a{ss}), G_PARAM_READABLE,
32 * The param info of the object}
33 *
34 * \gproperty{native-info, gpointer, G_PARAM_READABLE,
35 * The native info structure}
36 *
37 * \gsignals
38 *
39 * \par params-changed
40 * \parblock
41 * \code
42 * params_changed_callback (WpPipewireObject * self,
43 * const gchar *id,
44 * gpointer user_data)
45 * \endcode
46 *
47 * Emitted when the params for id have changed. On proxies that cache params
48 * from a remote object, this is emitted after the cached values have changed.
49 *
50 * You can expect this to be emitted only when the relevant
51 * WP_PIPEWIRE_OBJECT_FEATURE_PARAM_* has been activated.
52 *
53 * Parameters:
54 * - `id` - the parameter id as a string (ex "Props", "EnumRoute")
55 *
56 * Flags: G_SIGNAL_RUN_FIRST
57 * \endparblock
58 */
59
60 G_DEFINE_INTERFACE (WpPipewireObject, wp_pipewire_object, WP_TYPE_PROXY)
61
62 static void
63 wp_pipewire_object_default_init (WpPipewireObjectInterface * iface)
64 {
65 g_object_interface_install_property (iface,
66 g_param_spec_pointer ("native-info", "native-info",
67 "The native info structure",
68 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
69
70 g_object_interface_install_property (iface,
71 g_param_spec_boxed ("properties", "properties",
72 "The properties of the pipewire object", WP_TYPE_PROPERTIES,
73 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
74
75 g_object_interface_install_property (iface,
76 g_param_spec_variant ("param-info", "param-info",
77 "The param info of the object", G_VARIANT_TYPE ("a{ss}"), NULL,
78 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
79
80 g_signal_new ("params-changed", G_TYPE_FROM_INTERFACE (iface),
81 G_SIGNAL_RUN_FIRST, 0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_STRING);
82 }
83
84 /*!
85 * \brief Retrieves the native info structure of this object
86 * (pw_node_info, pw_port_info, etc...)
87 *
88 * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
89 *
90 * \ingroup wppipewireobject
91 * \param self the pipewire object
92 * \returns (nullable): the native pipewire info structure of this object
93 */
94 gconstpointer
95 wp_pipewire_object_get_native_info (WpPipewireObject * self)
96 {
97 g_return_val_if_fail (WP_IS_PIPEWIRE_OBJECT (self), NULL);
98 g_return_val_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_native_info,
99 NULL);
100
101 return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_native_info (self);
102 }
103
104 /*!
105 * \brief Retrieves the PipeWire properties of this object
106 *
107 * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
108 *
109 * \ingroup wppipewireobject
110 * \param self the pipewire object
111 * \returns (transfer full): the pipewire properties of this object;
112 * normally these are the properties that are part of the info structure
113 */
114 WpProperties *
115 wp_pipewire_object_get_properties (WpPipewireObject * self)
116 {
117 g_return_val_if_fail (WP_IS_PIPEWIRE_OBJECT (self), NULL);
118 g_return_val_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_properties,
119 NULL);
120
121 return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_properties (self);
122 }
123
124 /*!
125 * \brief Iterates over the object's PipeWire properties
126 *
127 * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
128 *
129 * \ingroup wppipewireobject
130 * \param self the pipewire object
131 * \returns (transfer full): an iterator that iterates over the pipewire
132 * properties of this object. Use wp_properties_iterator_item_get_key() and
133 * wp_properties_iterator_item_get_value() to parse the items returned by
134 * this iterator.
135 */
136 WpIterator *
137 wp_pipewire_object_new_properties_iterator (WpPipewireObject * self)
138 {
139 g_autoptr (WpProperties) properties =
140 wp_pipewire_object_get_properties (self);
141 return properties ? wp_properties_new_iterator (properties) : NULL;
142 }
143
144 /*!
145 * \brief Returns the value of a single pipewire property.
146 *
147 * This is the same as getting the whole properties structure with
148 * wp_pipewire_object_get_properties() and accessing a single property with
149 * wp_properties_get(), but saves one call and having to clean up the
150 * WpProperties reference count afterwards.
151 *
152 * The value is owned by the proxy, but it is guaranteed to stay alive
153 * until execution returns back to the event loop.
154 *
155 * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
156 *
157 * \ingroup wppipewireobject
158 * \param self the pipewire object
159 * \param key the property name
160 * \returns (transfer none) (nullable): the value of the pipewire property
161 * \a key or NULL if the property doesn't exist
162 */
163 const gchar *
164 wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
165 {
166 g_autoptr (WpProperties) properties =
167 wp_pipewire_object_get_properties (self);
168 return properties ? wp_properties_get (properties, key) : NULL;
169 }
170
171 /*!
172 * \brief Returns the available parameters of this pipewire object.
173 *
174 * The return value is a GVariant of type `a{ss}`, where the key of each map
175 * entry is a spa param type id (the same ids that you can pass in
176 * wp_pipewire_object_enum_params()) and the value is a string that can
177 * contain the following letters, each of them representing a flag:
178 * - `r`: the param is readable (`SPA_PARAM_INFO_READ`)
179 * - `w`: the param is writable (`SPA_PARAM_INFO_WRITE`)
180 *
181 * For params that are readable, you can query them with
182 * wp_pipewire_object_enum_params()
183 *
184 * Params that are writable can be set with wp_pipewire_object_set_param()
185 *
186 * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
187 *
188 * \ingroup wppipewireobject
189 * \param self the pipewire object
190 * \returns (transfer full) (nullable): a variant of type `a{ss}` or NULL
191 * if the object does not support params at all
192 */
193 GVariant *
194 wp_pipewire_object_get_param_info (WpPipewireObject * self)
195 {
196 g_return_val_if_fail (WP_IS_PIPEWIRE_OBJECT (self), NULL);
197 g_return_val_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_param_info,
198 NULL);
199
200 return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->get_param_info (self);
201 }
202
203 /*!
204 * \brief Enumerate object parameters.
205 *
206 * This will asynchronously return the result, or an error, by calling the
207 * given \a callback. The result is going to be a WpIterator containing
208 * WpSpaPod objects, which can be retrieved
209 * with wp_pipewire_object_enum_params_finish().
210 *
211 * \ingroup wppipewireobject
212 * \param self the pipewire object
213 * \param id (nullable): the parameter id to enumerate or NULL for all parameters
214 * \param filter (nullable): a param filter or NULL
215 * \param cancellable (nullable): a cancellable for the async operation
216 * \param callback (scope async)(closure user_data): a callback to call with the result
217 * \param user_data data to pass to \a callback
218 */
219 void
220 wp_pipewire_object_enum_params (WpPipewireObject * self, const gchar * id,
221 WpSpaPod *filter, GCancellable * cancellable,
222 GAsyncReadyCallback callback, gpointer user_data)
223 {
224 g_return_if_fail (WP_IS_PIPEWIRE_OBJECT (self));
225 g_return_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->enum_params);
226
227 WP_PIPEWIRE_OBJECT_GET_IFACE (self)->enum_params (self, id, filter,
228 cancellable, callback, user_data);
229 }
230
231 /*!
232 * \brief Finishes an asynchronous parameter enumeration operation.
233 *
234 * \ingroup wppipewireobject
235 * \param self the pipewire object
236 * \param res the async result
237 * \param error (out) (optional): the reported error of the operation, if any
238 * \returns (transfer full) (nullable): an iterator to iterate over the
239 * collected params, or NULL if the operation resulted in error;
240 * the items in the iterator are WpSpaPod
241 */
242 WpIterator *
243 wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
244 GAsyncResult * res, GError ** error)
245 {
246 g_return_val_if_fail (WP_IS_PIPEWIRE_OBJECT (self), NULL);
247 g_return_val_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->enum_params_finish,
248 NULL);
249
250 return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->enum_params_finish (self, res,
251 error);
252 }
253
254 /*!
255 * \brief This method can be used to retrieve object parameters in a synchronous
256 * way (in contrast with wp_pipewire_object_enum_params(), which is async).
257 *
258 * The `WP_PIPEWIRE_OBJECT_FEATURE_PARAM_<something>` feature
259 * that corresponds to the specified \a id must have been activated earlier.
260 * These features enable monitoring and caching of params underneath, so that
261 * they are always available for retrieval with this method.
262 *
263 * Note, however, that cached params may be out-of-date if they have changed
264 * very recently on the remote object and the caching mechanism hasn't been
265 * able to update them yet, so if you really need up-to-date information you
266 * should only rely on wp_pipewire_object_enum_params() instead.
267 *
268 * \ingroup wppipewireobject
269 * \param self the pipewire object
270 * \param id the parameter id to enumerate
271 * \param filter (nullable): a param filter or NULL
272 * \returns (transfer full) (nullable): an iterator to iterate over cached
273 * parameters, or NULL if parameters for this \a id are not cached;
274 * the items in the iterator are WpSpaPod
275 */
276 WpIterator *
277 wp_pipewire_object_enum_params_sync (WpPipewireObject * self,
278 const gchar * id, WpSpaPod * filter)
279 {
280 g_return_val_if_fail (WP_IS_PIPEWIRE_OBJECT (self), NULL);
281 g_return_val_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->enum_params_sync,
282 NULL);
283
284 return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->enum_params_sync (self, id,
285 filter);
286 }
287
288 /*!
289 * \brief Sets a parameter on the object.
290 *
291 * \ingroup wppipewireobject
292 * \param self the pipewire object
293 * \param id the parameter id to set
294 * \param flags optional flags or 0
295 * \param param (transfer full): the parameter to set
296 * \returns TRUE on success, FALSE if setting the param failed
297 */
298 gboolean
299 wp_pipewire_object_set_param (WpPipewireObject * self, const gchar * id,
300 guint32 flags, WpSpaPod * param)
301 {
302 g_return_val_if_fail (WP_IS_PIPEWIRE_OBJECT (self), FALSE);
303 g_return_val_if_fail (WP_PIPEWIRE_OBJECT_GET_IFACE (self)->set_param, FALSE);
304
305 return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->set_param (self, id, flags,
306 param);
307 }