Debian Codegraph @

lib/wp/properties.c

raw
1 /* WirePlumber
2 *
3 * Copyright © 2019 Collabora Ltd.
4 * @author George Kiagiadakis <[email protected]>
5 *
6 * SPDX-License-Identifier: MIT
7 */
8
9 #include "properties.h"
10 #include "log.h"
11
12 #include <errno.h>
13 #include <pipewire/properties.h>
14
15 WP_DEFINE_LOCAL_LOG_TOPIC ("wp-properties")
16
17 /*! \defgroup wpproperties WpProperties */
18 /*!
19 * \struct WpProperties
20 *
21 * WpProperties is a data structure that contains string key-value pairs,
22 * which are used to send/receive/attach arbitrary properties to PipeWire objects.
23 *
24 * This could be thought of as a hash table with strings as both keys and
25 * values. However, the reason that this class exists instead of using
26 * GHashTable directly is that in reality it wraps the PipeWire native
27 * `struct spa_dict` and `struct pw_properties` and therefore it can be
28 * easily passed to PipeWire function calls that require a `struct spa_dict *`
29 * or a `struct pw_properties *` as arguments. Or alternatively, it can easily
30 * wrap a `struct spa_dict *` or a `struct pw_properties *` that was given
31 * from the PipeWire API without necessarily doing an expensive copy operation.
32 *
33 * WpProperties normally wraps a `struct pw_properties`, unless it was created
34 * with wp_properties_new_wrap_dict(), in which case it wraps a
35 * `struct spa_dict` and it is immutable (you cannot add/remove/modify any
36 * key-value pair).
37 *
38 * In most cases, it actually owns the `struct pw_properties`
39 * internally and manages its lifetime. The exception to that rule is when
40 * WpProperties is constructed with wp_properties_new_wrap(), in which case
41 * the ownership of the `struct pw_properties` remains outside. This must
42 * be used with care, as the `struct pw_properties` may be free'ed externally.
43 *
44 * WpProperties is reference-counted with wp_properties_ref() and
45 * wp_properties_unref().
46 */
47
48 enum {
49 FLAG_IS_DICT = (1<<1),
50 FLAG_NO_OWNERSHIP = (1<<2),
51 };
52
53 struct _WpProperties
54 {
55 grefcount ref;
56 guint32 flags;
57 union {
58 struct pw_properties *props;
59 const struct spa_dict *dict;
60 };
61 };
62
63 G_DEFINE_BOXED_TYPE(WpProperties, wp_properties, wp_properties_ref, wp_properties_unref)
64
65 /*!
66 * \brief Creates a new empty properties set
67 * \ingroup wpproperties
68 * \returns (transfer full): the newly constructed properties set
69 */
70 WpProperties *
71 wp_properties_new_empty (void)
72 {
73 WpProperties * self = g_slice_new0 (WpProperties);
74 g_ref_count_init (&self->ref);
75 self->flags = 0;
76 self->props = pw_properties_new (NULL, NULL);
77 return self;
78 }
79
80 /*!
81 * \brief Constructs a new properties set that contains the given properties
82 *
83 * \ingroup wpproperties
84 * \param key a property name
85 * \param ... a property value, followed by any number of further property
86 * key-value pairs, followed by NULL
87 * \returns (transfer full): the newly constructed properties set
88 */
89 WpProperties *
90 wp_properties_new (const gchar * key, ...)
91 {
92 WpProperties * self;
93 va_list varargs;
94
95 va_start(varargs, key);
96 self = wp_properties_new_valist (key, varargs);
97 va_end(varargs);
98
99 return self;
100 }
101
102 /*!
103 * \brief This is the `va_list` version of wp_properties_new()
104 *
105 * \ingroup wpproperties
106 * \param key a property name
107 * \param args the variable arguments passed to wp_properties_new()
108 * \returns (transfer full): the newly constructed properties set
109 */
110 WpProperties *
111 wp_properties_new_valist (const gchar * key, va_list args)
112 {
113 WpProperties * self = wp_properties_new_empty ();
114 const gchar *value;
115
116 while (key != NULL) {
117 value = va_arg(args, gchar *);
118 if (value && key[0])
119 wp_properties_set (self, key, value);
120 key = va_arg(args, gchar *);
121 }
122
123 return self;
124 }
125
126 /*!
127 * \brief Constructs a new properties set that contains the properties that can
128 * be parsed from the given string
129 *
130 * \ingroup wpproperties
131 * \param str a string containing either a whitespace separated list of key=value
132 * pairs (ex. "key1=value1 key2=value2") or a JSON object (ex. '{"key1":"value1"}')
133 * \returns (transfer full): the newly constructed properties set
134 */
135 WpProperties *
136 wp_properties_new_string (const gchar * str)
137 {
138 WpProperties * self;
139
140 g_return_val_if_fail (str != NULL, NULL);
141
142 self = g_slice_new0 (WpProperties);
143 g_ref_count_init (&self->ref);
144 self->flags = 0;
145 self->props = pw_properties_new_string (str);
146 return self;
147 }
148
149 /*!
150 * \brief Constructs a new properties set that contains the properties that can
151 * be parsed from the given JSON object
152 *
153 * \ingroup wpproperties
154 * \param json a JSON object
155 * \returns (transfer full): the newly constructed properties set
156 */
157 WpProperties *
158 wp_properties_new_json (const WpSpaJson * json)
159 {
160 WpProperties * self;
161
162 g_return_val_if_fail (json != NULL, NULL);
163
164 self = wp_properties_new_empty ();
165 wp_properties_update_from_json (self, json);
166 return self;
167 }
168
169 /*!
170 * \brief Constructs a new WpProperties that wraps the given \a props structure,
171 * allowing reading properties on that \a props structure through
172 * the WpProperties API.
173 *
174 * Care must be taken when using this function, since the returned WpProperties
175 * object does not own the \a props structure. Therefore, if the owner decides
176 * to free \a props, the returned WpProperties will crash when used. In addition,
177 * the returned WpProperties object will not try to free \a props when destroyed.
178 *
179 * Furthermore, note that the returned WpProperties object is immutable. That
180 * means that you cannot add or modify any properties on it, unless you make
181 * a copy first.
182 *
183 * \ingroup wpproperties
184 * \param props a native `pw_properties` structure to wrap
185 * \returns (transfer full): the newly constructed properties set
186 */
187 WpProperties *
188 wp_properties_new_wrap (const struct pw_properties * props)
189 {
190 WpProperties * self;
191
192 g_return_val_if_fail (props != NULL, NULL);
193
194 self = g_slice_new0 (WpProperties);
195 g_ref_count_init (&self->ref);
196 self->flags = FLAG_NO_OWNERSHIP;
197 self->props = (struct pw_properties *) props;
198 return self;
199 }
200
201 /*!
202 * \brief Constructs a new WpProperties that wraps the given \a props structure,
203 * allowing reading & writing properties on that \a props structure through
204 * the WpProperties API.
205 *
206 * In contrast with wp_properties_new_wrap(), this function assumes ownership
207 * of the \a props structure, so it will try to free \a props when it is destroyed.
208 *
209 * \ingroup wpproperties
210 * \param props a native `pw_properties` structure to wrap
211 * \returns (transfer full): the newly constructed properties set
212 */
213 WpProperties *
214 wp_properties_new_take (struct pw_properties * props)
215 {
216 WpProperties * self;
217
218 g_return_val_if_fail (props != NULL, NULL);
219
220 self = g_slice_new0 (WpProperties);
221 g_ref_count_init (&self->ref);
222 self->flags = 0;
223 self->props = props;
224 return self;
225 }
226
227 /*!
228 * \brief Constructs a new WpProperties that contains a copy of all the properties
229 * contained in the given \a props structure.
230 *
231 * \ingroup wpproperties
232 * \param props a native `pw_properties` structure to copy
233 * \returns (transfer full): the newly constructed properties set
234 */
235 WpProperties *
236 wp_properties_new_copy (const struct pw_properties * props)
237 {
238 WpProperties * self;
239
240 g_return_val_if_fail (props != NULL, NULL);
241
242 self = g_slice_new0 (WpProperties);
243 g_ref_count_init (&self->ref);
244 self->flags = 0;
245 self->props = pw_properties_copy (props);
246 return self;
247 }
248
249 /*!
250 * \brief Constructs a new WpProperties that wraps the given \a dict structure,
251 * allowing reading properties from that \a dict through the WpProperties API.
252 *
253 * Note that the returned object does not own the \a dict, so care must be taken
254 * not to free it externally while this WpProperties object is alive.
255 *
256 * In addition, note that the returned WpProperties object is immutable. That
257 * means that you cannot add or modify any properties on it, since there is
258 * no defined method for modifying a `struct spa_dict`. If you need to change
259 * this properties set later, you should make a copy with wp_properties_copy().
260 *
261 * \ingroup wpproperties
262 * \param dict a native `spa_dict` structure to wrap
263 * \returns (transfer full): the newly constructed properties set
264 */
265 WpProperties *
266 wp_properties_new_wrap_dict (const struct spa_dict * dict)
267 {
268 WpProperties * self;
269
270 g_return_val_if_fail (dict != NULL, NULL);
271
272 self = g_slice_new0 (WpProperties);
273 g_ref_count_init (&self->ref);
274 self->flags = FLAG_NO_OWNERSHIP | FLAG_IS_DICT;
275 self->dict = dict;
276 return self;
277 }
278
279 /*!
280 * \brief Constructs a new WpProperties that contains a copy of all the
281 * properties contained in the given \a dict structure.
282 *
283 * \ingroup wpproperties
284 * \param dict a native `spa_dict` structure to copy
285 * \returns (transfer full): the newly constructed properties set
286 */
287 WpProperties *
288 wp_properties_new_copy_dict (const struct spa_dict * dict)
289 {
290 WpProperties * self;
291
292 g_return_val_if_fail (dict != NULL, NULL);
293
294 self = g_slice_new0 (WpProperties);
295 g_ref_count_init (&self->ref);
296 self->flags = 0;
297 self->props = pw_properties_new_dict (dict);
298 return self;
299 }
300
301 /*!
302 * \brief Constructs and returns a new WpProperties object that contains a copy
303 * of all the properties contained in \a other.
304 *
305 * \ingroup wpproperties
306 * \param other a properties object
307 * \returns (transfer full): the newly constructed properties set
308 */
309
310 WpProperties *
311 wp_properties_copy (WpProperties * other)
312 {
313 return wp_properties_new_copy_dict (wp_properties_peek_dict (other));
314 }
315
316 static void
317 wp_properties_free (WpProperties * self)
318 {
319 if (!(self->flags & FLAG_NO_OWNERSHIP))
320 pw_properties_free (self->props);
321 g_slice_free (WpProperties, self);
322 }
323
324 /*!
325 * \ingroup wpproperties
326 * \param self a properties object
327 * \returns (transfer full): \a self with an additional reference count on it
328 */
329 WpProperties *
330 wp_properties_ref (WpProperties * self)
331 {
332 g_ref_count_inc (&self->ref);
333 return self;
334 }
335
336 /*!
337 * \brief Decreases the reference count on \a self and frees it when the ref
338 * count reaches zero.
339 *
340 * \ingroup wpproperties
341 * \param self (transfer full): a properties object
342 */
343 void
344 wp_properties_unref (WpProperties * self)
345 {
346 if (g_ref_count_dec (&self->ref))
347 wp_properties_free (self);
348 }
349
350 /*!
351 * \brief Ensures that the given properties set is uniquely owned.
352 *
353 * "Uniquely owned" means that:
354 * - its reference count is 1
355 * - it is not wrapping a native `spa_dict` or `pw_properties` object
356 *
357 * If \a self is not uniquely owned already, then it is unrefed and a copy of
358 * it is returned instead. You should always consider \a self as unsafe to use
359 * after this call and you should use the returned object instead.
360 *
361 * \ingroup wpproperties
362 * \param self (transfer full): a properties object
363 * \returns (transfer full): the uniquely owned properties object
364 */
365 WpProperties *
366 wp_properties_ensure_unique_owner (WpProperties * self)
367 {
368 if (!g_ref_count_compare (&self->ref, 1) ||
369 self->flags & (FLAG_IS_DICT | FLAG_NO_OWNERSHIP))
370 {
371 WpProperties *copy = wp_properties_copy (self);
372 wp_properties_unref (self);
373 return copy;
374 }
375 return self;
376 }
377
378 /*!
379 * \brief Updates (adds new or modifies existing) properties in \a self,
380 * using the given \a props as a source.
381 *
382 * Any properties that are not contained in \a props are left untouched.
383 *
384 * \ingroup wpproperties
385 * \param self a properties object
386 * \param props a properties set that contains properties to update
387 * \returns the number of properties that were changed
388 */
389 gint
390 wp_properties_update (WpProperties * self, WpProperties * props)
391 {
392 g_return_val_if_fail (self != NULL, -EINVAL);
393 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
394 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
395
396 return pw_properties_update (self->props, wp_properties_peek_dict (props));
397 }
398
399 /*!
400 * \brief Updates (adds new or modifies existing) properties in \a self,
401 * using the given \a dict as a source.
402 *
403 * Any properties that are not contained in \a dict are left untouched.
404 *
405 * \ingroup wpproperties
406 * \param self a properties object
407 * \param dict a `spa_dict` that contains properties to update
408 * \returns the number of properties that were changed
409 */
410 gint
411 wp_properties_update_from_dict (WpProperties * self,
412 const struct spa_dict * dict)
413 {
414 g_return_val_if_fail (self != NULL, -EINVAL);
415 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
416 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
417
418 return pw_properties_update (self->props, dict);
419 }
420
421 /*!
422 * \brief Updates (adds new or modifies existing) properties in \a self,
423 * using the given \a json as a source.
424 *
425 * Any properties that are not contained in \a json are left untouched.
426 *
427 * \ingroup wpproperties
428 * \param self a properties object
429 * \param json a JSON object that contains properties to update
430 * \returns the number of properties that were changed
431 */
432 gint
433 wp_properties_update_from_json (WpProperties * self, const WpSpaJson * json)
434 {
435 g_return_val_if_fail (self != NULL, -EINVAL);
436 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
437 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
438
439 return pw_properties_update_string (self->props, wp_spa_json_get_data (json),
440 wp_spa_json_get_size (json));
441 }
442
443 /*!
444 * \brief Adds new properties in \a self, using the given \a props as a source.
445 *
446 * Properties (keys) from \a props that are already contained in \a self
447 * are not modified, unlike what happens with wp_properties_update().
448 * Properties in \a self that are not contained in \a props are left untouched.
449 *
450 * \ingroup wpproperties
451 * \param self a properties object
452 * \param props a properties set that contains properties to add
453 * \returns the number of properties that were changed
454 */
455 gint
456 wp_properties_add (WpProperties * self, WpProperties * props)
457 {
458 g_return_val_if_fail (self != NULL, -EINVAL);
459 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
460 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
461
462 return pw_properties_add (self->props, wp_properties_peek_dict (props));
463 }
464
465 /*!
466 * \brief Adds new properties in \a self, using the given \a dict as a source.
467 *
468 * Properties (keys) from \a dict that are already contained in \a self
469 * are not modified, unlike what happens with wp_properties_update_from_dict().
470 * Properties in \a self that are not contained in \a dict are left untouched.
471 *
472 * \ingroup wpproperties
473 * \param self a properties object
474 * \param dict a `spa_dict` that contains properties to add
475 * \returns the number of properties that were changed
476 */
477 gint
478 wp_properties_add_from_dict (WpProperties * self,
479 const struct spa_dict * dict)
480 {
481 g_return_val_if_fail (self != NULL, -EINVAL);
482 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
483 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
484
485 return pw_properties_add (self->props, dict);
486 }
487
488 /*!
489 * \brief Updates (adds new or modifies existing) properties in \a self,
490 * using the given \a props as a source.
491 *
492 * Unlike wp_properties_update(), this function only updates properties that
493 * have one of the specified keys; the rest is left untouched.
494 *
495 * \ingroup wpproperties
496 * \param self a properties set
497 * \param props a properties set that contains properties to update
498 * \param key1 a property to update
499 * \param ... a list of additional properties to update, followed by NULL
500 * \returns the number of properties that were changed
501 */
502 gint
503 wp_properties_update_keys (WpProperties * self, WpProperties * props,
504 const gchar * key1, ...)
505 {
506 gint changed = 0;
507 const gchar *value;
508
509 g_return_val_if_fail (self != NULL, -EINVAL);
510 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
511 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
512
513 va_list args;
514 va_start (args, key1);
515 for (; key1; key1 = va_arg (args, const gchar *)) {
516 if ((value = wp_properties_get (props, key1)) != NULL)
517 changed += wp_properties_set (self, key1, value);
518 }
519 va_end (args);
520 return changed;
521 }
522
523 /*!
524 * \brief Updates (adds new or modifies existing) properties in \a self,
525 * using the given \a dict as a source.
526 *
527 * Unlike wp_properties_update_from_dict(), this function only updates
528 * properties that have one of the specified keys; the rest is left untouched.
529 *
530 * \ingroup wpproperties
531 * \param self a properties set
532 * \param dict a `spa_dict` that contains properties to update
533 * \param key1 a property to update
534 * \param ... a list of additional properties to update, followed by NULL
535 * \returns the number of properties that were changed
536 */
537 gint
538 wp_properties_update_keys_from_dict (WpProperties * self,
539 const struct spa_dict * dict, const gchar * key1, ...)
540 {
541 gint changed = 0;
542 const gchar *value;
543
544 g_return_val_if_fail (self != NULL, -EINVAL);
545 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
546 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
547
548 va_list args;
549 va_start (args, key1);
550 for (; key1; key1 = va_arg (args, const gchar *)) {
551 if ((value = spa_dict_lookup (dict, key1)) != NULL)
552 changed += wp_properties_set (self, key1, value);
553 }
554 va_end (args);
555 return changed;
556 }
557
558 /*!
559 * \brief The same as wp_properties_update_keys(), using a NULL-terminated array
560 * for specifying the keys to update
561 *
562 * \ingroup wpproperties
563 * \param self a properties set
564 * \param props a properties set that contains properties to update
565 * \param keys (array zero-terminated=1): the properties to update
566 * \returns the number of properties that were changed
567 */
568 gint
569 wp_properties_update_keys_array (WpProperties * self, WpProperties * props,
570 const gchar * keys[])
571 {
572 g_return_val_if_fail (self != NULL, -EINVAL);
573 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
574 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
575
576 return pw_properties_update_keys (self->props,
577 wp_properties_peek_dict (props), keys);
578 }
579
580 /*!
581 * \brief Adds new properties in \a self, using the given \a props as a source.
582 *
583 * Unlike wp_properties_add(), this function only adds properties that
584 * have one of the specified keys; the rest is left untouched.
585 *
586 * \ingroup wpproperties
587 * \param self a properties set
588 * \param props a properties set that contains properties to add
589 * \param key1 a property to add
590 * \param ... a list of additional properties to add, followed by NULL
591 * \returns the number of properties that were changed
592 */
593 gint
594 wp_properties_add_keys (WpProperties * self, WpProperties * props,
595 const gchar * key1, ...)
596 {
597 gint changed = 0;
598 const gchar *value;
599
600 g_return_val_if_fail (self != NULL, -EINVAL);
601 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
602 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
603
604 va_list args;
605 va_start (args, key1);
606 for (; key1; key1 = va_arg (args, const gchar *)) {
607 if ((value = wp_properties_get (props, key1)) == NULL)
608 continue;
609 if (wp_properties_get (self, key1) == NULL)
610 changed += wp_properties_set (self, key1, value);
611 }
612 va_end (args);
613 return changed;
614 }
615
616 /*!
617 * \brief Adds new properties in \a self, using the given \a dict as a source.
618 *
619 * Unlike wp_properties_add_from_dict(), this function only adds
620 * properties that have one of the specified keys; the rest is left untouched.
621 *
622 * \ingroup wpproperties
623 * \param self a properties set
624 * \param dict a `spa_dict` that contains properties to add
625 * \param key1 a property to add
626 * \param ... a list of additional properties to add, followed by NULL
627 * \returns the number of properties that were changed
628 */
629 gint
630 wp_properties_add_keys_from_dict (WpProperties * self,
631 const struct spa_dict * dict, const gchar * key1, ...)
632 {
633 gint changed = 0;
634 const gchar *value;
635
636 g_return_val_if_fail (self != NULL, -EINVAL);
637 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
638 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
639
640 va_list args;
641 va_start (args, key1);
642 for (; key1; key1 = va_arg (args, const gchar *)) {
643 if ((value = spa_dict_lookup (dict, key1)) == NULL)
644 continue;
645 if (wp_properties_get (self, key1) == NULL)
646 changed += wp_properties_set (self, key1, value);
647 }
648 va_end (args);
649 return changed;
650 }
651
652 /*!
653 * \brief The same as wp_properties_add_keys(), using a NULL-terminated array
654 * for specifying the keys to add
655 *
656 * \ingroup wpproperties
657 * \param self a properties set
658 * \param props a properties set that contains properties to add
659 * \param keys (array zero-terminated=1): the properties to add
660 * \returns the number of properties that were changed
661 */
662 gint
663 wp_properties_add_keys_array (WpProperties * self, WpProperties * props,
664 const gchar * keys[])
665 {
666 g_return_val_if_fail (self != NULL, -EINVAL);
667 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
668 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
669
670 return pw_properties_add_keys (self->props,
671 wp_properties_peek_dict (props), keys);
672 }
673
674 /*!
675 * \brief Looks up a given property value from a key
676 *
677 * \ingroup wpproperties
678 * \param self a properties object
679 * \param key a property key
680 * \returns (transfer none) (nullable): the value of the property identified
681 * with \a key, or NULL if this property is not contained in \a self
682 */
683 const gchar *
684 wp_properties_get (WpProperties * self, const gchar * key)
685 {
686 g_return_val_if_fail (self != NULL, NULL);
687 g_return_val_if_fail (key != NULL, NULL);
688
689 return spa_dict_lookup (wp_properties_peek_dict (self), key);
690 }
691
692 /*!
693 * \brief Sets the given property \a key - \a value pair on \a self.
694 *
695 * If the property already existed, the value is overwritten with the new one.
696 *
697 * If the \a value is NULL, then the specified property is removed from \a self
698 *
699 * \ingroup wpproperties
700 * \param self a properties object
701 * \param key a property key
702 * \param value (nullable): a property value
703 * \returns 1 if the property was changed. 0 if nothing was changed because
704 * the property already existed with the same value or because the key to
705 * remove did not exist.
706 */
707 gint
708 wp_properties_set (WpProperties * self, const gchar * key,
709 const gchar * value)
710 {
711 g_return_val_if_fail (self != NULL, -EINVAL);
712 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
713 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
714
715 return pw_properties_set (self->props, key, value);
716 }
717
718 /*!
719 * \brief Formats the given \a format string with the specified arguments
720 * and sets the result as a value of the property specified with \a key
721 *
722 * \ingroup wpproperties
723 * \param self a properties object
724 * \param key a property key
725 * \param format a printf-style format to be formatted and set as a value for
726 * this property \a key
727 * \param ... arguments for \a format
728 * \returns 1 if the property was changed. 0 if nothing was changed because
729 * the property already existed with the same value
730 */
731 gint
732 wp_properties_setf (WpProperties * self, const gchar * key,
733 const gchar * format, ...)
734 {
735 gint res;
736 va_list varargs;
737
738 va_start (varargs, format);
739 res = wp_properties_setf_valist (self, key, format, varargs);
740 va_end (varargs);
741
742 return res;
743 }
744
745 /*!
746 * \brief This is the `va_list` version of wp_properties_setf()
747 *
748 * \ingroup wpproperties
749 * \param self a properties object
750 * \param key a property key
751 * \param format a printf-style format to be formatted and set as a value for
752 * this property \a key
753 * \param args the variable arguments passed to wp_properties_setf()
754 * \returns 1 if the property was changed. 0 if nothing was changed because
755 * the property already existed with the same value
756 */
757 gint
758 wp_properties_setf_valist (WpProperties * self, const gchar * key,
759 const gchar * format, va_list args)
760 {
761 g_return_val_if_fail (self != NULL, -EINVAL);
762 g_return_val_if_fail (!(self->flags & FLAG_IS_DICT), -EINVAL);
763 g_return_val_if_fail (!(self->flags & FLAG_NO_OWNERSHIP), -EINVAL);
764
765 return pw_properties_setva (self->props, key, format, args);
766 }
767
768 struct _WpPropertiesItem
769 {
770 WpProperties *props;
771 const struct spa_dict_item *item;
772 };
773
774 G_DEFINE_BOXED_TYPE (WpPropertiesItem, wp_properties_item,
775 wp_properties_item_ref, wp_properties_item_unref)
776
777 static WpPropertiesItem *
778 wp_properties_item_new (WpProperties *props, const struct spa_dict_item *item)
779 {
780 WpPropertiesItem *self = g_rc_box_new0 (WpPropertiesItem);
781 self->props = wp_properties_ref (props);
782 self->item = item;
783 return self;
784 }
785
786 static void
787 wp_properties_item_free (gpointer p)
788 {
789 WpPropertiesItem *self = p;
790 wp_properties_unref (self->props);
791 }
792
793 /*!
794 * \brief Increases the reference count of a properties item object
795 * \ingroup wpproperties
796 * \param self a properties item object
797 * \returns (transfer full): \a self with an additional reference count on it
798 * \since 0.4.2
799 */
800 WpPropertiesItem *
801 wp_properties_item_ref (WpPropertiesItem *self)
802 {
803 return g_rc_box_acquire (self);
804 }
805
806 /*!
807 * \brief Decreases the reference count on \a self and frees it when the ref
808 * count reaches zero.
809 * \ingroup wpproperties
810 * \param self (transfer full): a properties item object
811 * \since 0.4.2
812 */
813 void
814 wp_properties_item_unref (WpPropertiesItem *self)
815 {
816 g_rc_box_release_full (self, wp_properties_item_free);
817 }
818
819 /*!
820 * \brief Gets the key from a properties item
821 *
822 * \ingroup wpproperties
823 * \param self the item held by the GValue that was returned from the WpIterator
824 * of wp_properties_new_iterator()
825 * \returns (transfer none): the property key of the \a item
826 * \since 0.4.2
827 */
828 const gchar *
829 wp_properties_item_get_key (WpPropertiesItem * self)
830 {
831 return self->item->key;
832 }
833
834 /*!
835 * \brief Gets the value from a properties item
836 *
837 * \ingroup wpproperties
838 * \param self the item held by the GValue that was returned from the WpIterator
839 * of wp_properties_new_iterator()
840 * \returns (transfer none): the property value of the \a item
841 * \since 0.4.2
842 */
843 const gchar *
844 wp_properties_item_get_value (WpPropertiesItem * self)
845 {
846 return self->item->value;
847 }
848
849 struct dict_iterator_data
850 {
851 WpProperties *properties;
852 const struct spa_dict_item *item;
853 };
854
855 static void
856 dict_iterator_reset (WpIterator *it)
857 {
858 struct dict_iterator_data *it_data = wp_iterator_get_user_data (it);
859 it_data->item = wp_properties_peek_dict (it_data->properties)->items;
860 }
861
862 static gboolean
863 dict_iterator_next (WpIterator *it, GValue *item)
864 {
865 struct dict_iterator_data *it_data = wp_iterator_get_user_data (it);
866 const struct spa_dict *dict = wp_properties_peek_dict (it_data->properties);
867
868 if ((it_data->item - dict->items) < dict->n_items) {
869 g_value_init (item, WP_TYPE_PROPERTIES_ITEM);
870 g_autoptr (WpPropertiesItem) pi = wp_properties_item_new (
871 it_data->properties, it_data->item);
872 g_value_take_boxed (item, g_steal_pointer (&pi));
873 it_data->item++;
874 return TRUE;
875 }
876 return FALSE;
877 }
878
879 static gboolean
880 dict_iterator_fold (WpIterator *it, WpIteratorFoldFunc func, GValue *ret,
881 gpointer data)
882 {
883 struct dict_iterator_data *it_data = wp_iterator_get_user_data (it);
884 const struct spa_dict *dict = wp_properties_peek_dict (it_data->properties);
885 const struct spa_dict_item *i;
886
887 spa_dict_for_each (i, dict) {
888 g_auto (GValue) item = G_VALUE_INIT;
889 g_autoptr (WpPropertiesItem) pi = wp_properties_item_new (
890 it_data->properties, i);
891 g_value_init (&item, WP_TYPE_PROPERTIES_ITEM);
892 g_value_take_boxed (&item, g_steal_pointer (&pi));
893 if (!func (&item, ret, data))
894 return FALSE;
895 }
896 return TRUE;
897 }
898
899 static void
900 dict_iterator_finalize (WpIterator *it)
901 {
902 struct dict_iterator_data *it_data = wp_iterator_get_user_data (it);
903 wp_properties_unref (it_data->properties);
904 }
905
906 static const WpIteratorMethods dict_iterator_methods = {
907 .version = WP_ITERATOR_METHODS_VERSION,
908 .reset = dict_iterator_reset,
909 .next = dict_iterator_next,
910 .fold = dict_iterator_fold,
911 .finalize = dict_iterator_finalize,
912 };
913
914 /*!
915 * \brief Iterates through all the properties in the properties object
916 *
917 * \ingroup wpproperties
918 * \param self a properties object
919 * \returns (transfer full): an iterator that iterates over the properties.
920 * The items in the iterator are of type WpPropertiesItem.
921 * Use wp_properties_item_get_key() and
922 * wp_properties_item_get_value() to retrieve their contents.
923 */
924 WpIterator *
925 wp_properties_new_iterator (WpProperties * self)
926 {
927 g_autoptr (WpIterator) it = NULL;
928 struct dict_iterator_data *it_data;
929
930 g_return_val_if_fail (self != NULL, NULL);
931
932 it = wp_iterator_new (&dict_iterator_methods,
933 sizeof (struct dict_iterator_data));
934 it_data = wp_iterator_get_user_data (it);
935 it_data->properties = wp_properties_ref (self);
936 it_data->item = wp_properties_peek_dict (it_data->properties)->items;
937 return g_steal_pointer (&it);
938 }
939
940 /*!
941 * \brief Gets the number of properties contained in this object
942 * \ingroup wpproperties
943 * \param self a properties object
944 * \returns the number of properties contained in this object
945 * \since 0.4.10
946 */
947 guint
948 wp_properties_get_count (WpProperties * self)
949 {
950 const struct spa_dict *dict = wp_properties_peek_dict(self);
951 g_return_val_if_fail (dict != NULL, 0);
952
953 return dict->n_items;
954 }
955
956 /*!
957 * \brief Sorts the keys in alphabetical order
958 * \ingroup wpproperties
959 * \param self a properties object
960 */
961 void
962 wp_properties_sort (WpProperties * self)
963 {
964 g_return_if_fail (self != NULL);
965 g_return_if_fail (!(self->flags & FLAG_IS_DICT));
966 g_return_if_fail (!(self->flags & FLAG_NO_OWNERSHIP));
967
968 return spa_dict_qsort (&self->props->dict);
969 }
970
971 /*!
972 * \brief Gets the dictionary wrapped by a properties object
973 *
974 * \ingroup wpproperties
975 * \param self a properties object
976 * \returns (transfer none): the internal properties set as a `struct spa_dict *`
977 */
978 const struct spa_dict *
979 wp_properties_peek_dict (WpProperties * self)
980 {
981 g_return_val_if_fail (self != NULL, NULL);
982
983 return (self->flags & FLAG_IS_DICT) ? self->dict : &self->props->dict;
984 }
985
986 /*!
987 * \brief Gets a copy of the properties object as a `struct pw_properties`
988 *
989 * \ingroup wpproperties
990 * \param self a properties object
991 * \returns (transfer full): a copy of the properties in \a self
992 * as a `struct pw_properties`
993 */
994 struct pw_properties *
995 wp_properties_to_pw_properties (WpProperties * self)
996 {
997 g_return_val_if_fail (self != NULL, NULL);
998
999 return pw_properties_new_dict (wp_properties_peek_dict (self));
1000 }
1001
1002 /*!
1003 * \brief Similar to wp_properties_to_pw_properties(), but this method avoids making
1004 * a copy of the properties by returning the `struct pw_properties` that is
1005 * stored internally and then freeing the WpProperties wrapper.
1006 *
1007 * If \a self is not uniquely owned (see wp_properties_ensure_unique_owner()),
1008 * then this method does make a copy and is the same as
1009 * wp_properties_to_pw_properties(), performance-wise.
1010 *
1011 * \ingroup wpproperties
1012 * \param self (transfer full): a properties object
1013 * \returns (transfer full): the properties in \a self as a `struct pw_properties`
1014 */
1015 struct pw_properties *
1016 wp_properties_unref_and_take_pw_properties (WpProperties * self)
1017 {
1018 g_return_val_if_fail (self != NULL, NULL);
1019
1020 g_autoptr (WpProperties) unique = wp_properties_ensure_unique_owner (self);
1021 /* set the flag so that unref-ing \a unique will not destroy unique->props */
1022 unique->flags = FLAG_NO_OWNERSHIP;
1023 return unique->props;
1024 }
1025
1026 /*!
1027 * \brief Checks if all property values contained in \a other are matching with
1028 * the values in \a self.
1029 *
1030 * If a property is contained in \a other and not in \a self, the result is not
1031 * matched. If a property is contained in both sets, then the value of the
1032 * property in \a other is interpreted as a glob-style pattern
1033 * (using g_pattern_match_simple()) and the value in \a self is checked to
1034 * see if it matches with this pattern.
1035 *
1036 * \ingroup wpproperties
1037 * \param self a properties object
1038 * \param other a set of properties to match
1039 * \returns TRUE if all matches were successful, FALSE if at least one
1040 * property value did not match
1041 */
1042 gboolean
1043 wp_properties_matches (WpProperties * self, WpProperties *other)
1044 {
1045 const struct spa_dict * dict;
1046 const struct spa_dict_item *item;
1047 const gchar *value;
1048
1049 g_return_val_if_fail (self != NULL, FALSE);
1050
1051 /* Check if the property values match the ones from 'self' */
1052 dict = wp_properties_peek_dict (other);
1053 spa_dict_for_each(item, dict) {
1054 value = wp_properties_get (self, item->key);
1055 if (!value || !g_pattern_match_simple (value, item->value))
1056 return FALSE;
1057 }
1058
1059 return TRUE;
1060 }