Properties Dictionary

digraph inheritance { rankdir=LR; GBoxed -> WpProperties; }

struct WpProperties

WpProperties is a data structure that contains string key-value pairs, which are used to send/receive/attach arbitrary properties to PipeWire objects.

This could be thought of as a hash table with strings as both keys and values. However, the reason that this class exists instead of using GHashTable directly is that in reality it wraps the PipeWire native struct spa_dict and struct pw_properties and therefore it can be easily passed to PipeWire function calls that require a struct spa_dict * or a struct pw_properties * as arguments. Or alternatively, it can easily wrap a struct spa_dict * or a struct pw_properties * that was given from the PipeWire API without necessarily doing an expensive copy operation.

WpProperties normally wraps a struct pw_properties, unless it was created with wp_properties_new_wrap_dict(), in which case it wraps a struct spa_dict and it is immutable (you cannot add/remove/modify any key-value pair).

In most cases, it actually owns the struct pw_properties internally and manages its lifetime. The exception to that rule is when WpProperties is constructed with wp_properties_new_wrap(), in which case the ownership of the struct pw_properties remains outside. This must be used with care, as the struct pw_properties may be free’ed externally.

WpProperties is reference-counted with wp_properties_ref() and wp_properties_unref().

WpProperties *wp_properties_new_empty(void)

Creates a new empty properties set.

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new(const gchar *key, ...)

Constructs a new properties set that contains the given properties.

Parameters:

  • key – a property name

  • ... – a property value, followed by any number of further property key-value pairs, followed by NULL

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_valist(const gchar *key, va_list args)

This is the va_list version of wp_properties_new()

Parameters:
Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_string(const gchar *str)

Constructs a new properties set that contains the properties that can be parsed from the given string.

Parameters:

  • str – a string containing either a whitespace separated list of key=value pairs (ex. “key1=value1 key2=value2”) or a JSON object (ex. ‘{“key1”:”value1”}’)

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_json(const WpSpaJson *json)

Constructs a new properties set that contains the properties that can be parsed from the given JSON object.

Parameters:

  • json – a JSON object

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_wrap(const struct pw_properties *props)

Constructs a new WpProperties that wraps the given props structure, allowing reading properties on that props structure through the WpProperties API.

Care must be taken when using this function, since the returned WpProperties object does not own the props structure. Therefore, if the owner decides to free props, the returned WpProperties will crash when used. In addition, the returned WpProperties object will not try to free props when destroyed.

Furthermore, note that the returned WpProperties object is immutable. That means that you cannot add or modify any properties on it, unless you make a copy first.

Parameters:

  • props – a native pw_properties structure to wrap

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_take(struct pw_properties *props)

Constructs a new WpProperties that wraps the given props structure, allowing reading & writing properties on that props structure through the WpProperties API.

In constrast with wp_properties_new_wrap(), this function assumes ownership of the props structure, so it will try to free props when it is destroyed.

Parameters:

  • props – a native pw_properties structure to wrap

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_copy(const struct pw_properties *props)

Constructs a new WpProperties that contains a copy of all the properties contained in the given props structure.

Parameters:

  • props – a native pw_properties structure to copy

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_wrap_dict(const struct spa_dict *dict)

Constructs a new WpProperties that wraps the given dict structure, allowing reading properties from that dict through the WpProperties API.

Note that the returned object does not own the dict, so care must be taken not to free it externally while this WpProperties object is alive.

In addition, note that the returned WpProperties object is immutable. That means that you cannot add or modify any properties on it, since there is no defined method for modifying a struct spa_dict. If you need to change this properties set later, you should make a copy with wp_properties_copy().

Parameters:

  • dict – a native spa_dict structure to wrap

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_new_copy_dict(const struct spa_dict *dict)

Constructs a new WpProperties that contains a copy of all the properties contained in the given dict structure.

Parameters:

  • dict – a native spa_dict structure to copy

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_copy(WpProperties *other)

Constructs and returns a new WpProperties object that contains a copy of all the properties contained in other.

Parameters:

  • other – a properties object

Returns:

(transfer full): the newly constructed properties set

WpProperties *wp_properties_ref(WpProperties *self)
Parameters:

  • self – a properties object

Returns:

(transfer full): self with an additional reference count on it

void wp_properties_unref(WpProperties *self)

Decreases the reference count on self and frees it when the ref count reaches zero.

Parameters:

  • self – (transfer full): a properties object

WpProperties *wp_properties_ensure_unique_owner(WpProperties *self)

Ensures that the given properties set is uniquely owned.

“Uniquely owned” means that:

  • its reference count is 1

  • it is not wrapping a native spa_dict or pw_properties object

If self is not uniquely owned already, then it is unrefed and a copy of it is returned instead. You should always consider self as unsafe to use after this call and you should use the returned object instead.

Parameters:

  • self – (transfer full): a properties object

Returns:

(transfer full): the uniquely owned properties object

gint wp_properties_update(WpProperties *self, WpProperties *props)

Updates (adds new or modifies existing) properties in self, using the given props as a source.

Any properties that are not contained in props are left untouched.

Parameters:

  • self – a properties object

  • props – a properties set that contains properties to update

Returns:

the number of properties that were changed

gint wp_properties_update_from_dict(WpProperties *self, const struct spa_dict *dict)

Updates (adds new or modifies existing) properties in self, using the given dict as a source.

Any properties that are not contained in dict are left untouched.

Parameters:

  • self – a properties object

  • dict – a spa_dict that contains properties to update

Returns:

the number of properties that were changed

gint wp_properties_update_from_json(WpProperties *self, const WpSpaJson *json)

Updates (adds new or modifies existing) properties in self, using the given json as a source.

Any properties that are not contained in json are left untouched.

Parameters:

  • self – a properties object

  • json – a JSON object that contains properties to update

Returns:

the number of properties that were changed

gint wp_properties_add(WpProperties *self, WpProperties *props)

Adds new properties in self, using the given props as a source.

Properties (keys) from props that are already contained in self are not modified, unlike what happens with wp_properties_update(). Properties in self that are not contained in props are left untouched.

Parameters:

  • self – a properties object

  • props – a properties set that contains properties to add

Returns:

the number of properties that were changed

gint wp_properties_add_from_dict(WpProperties *self, const struct spa_dict *dict)

Adds new properties in self, using the given dict as a source.

Properties (keys) from dict that are already contained in self are not modified, unlike what happens with wp_properties_update_from_dict(). Properties in self that are not contained in dict are left untouched.

Parameters:

  • self – a properties object

  • dict – a spa_dict that contains properties to add

Returns:

the number of properties that were changed

gint wp_properties_update_keys(WpProperties *self, WpProperties *props, const gchar *key1, ...)

Updates (adds new or modifies existing) properties in self, using the given props as a source.

Unlike wp_properties_update(), this function only updates properties that have one of the specified keys; the rest is left untouched.

Parameters:

  • self – a properties set

  • props – a properties set that contains properties to update

  • key1 – a property to update

  • ... – a list of additional properties to update, followed by NULL

Returns:

the number of properties that were changed

gint wp_properties_update_keys_from_dict(WpProperties *self, const struct spa_dict *dict, const gchar *key1, ...)

Updates (adds new or modifies existing) properties in self, using the given dict as a source.

Unlike wp_properties_update_from_dict(), this function only updates properties that have one of the specified keys; the rest is left untouched.

Parameters:

  • self – a properties set

  • dict – a spa_dict that contains properties to update

  • key1 – a property to update

  • ... – a list of additional properties to update, followed by NULL

Returns:

the number of properties that were changed

gint wp_properties_update_keys_array(WpProperties *self, WpProperties *props, const gchar *keys[])

The same as wp_properties_update_keys(), using a NULL-terminated array for specifying the keys to update.

Parameters:

  • self – a properties set

  • props – a properties set that contains properties to update

  • keys – (array zero-terminated=1): the properties to update

Returns:

the number of properties that were changed

gint wp_properties_add_keys(WpProperties *self, WpProperties *props, const gchar *key1, ...)

Adds new properties in self, using the given props as a source.

Unlike wp_properties_add(), this function only adds properties that have one of the specified keys; the rest is left untouched.

Parameters:

  • self – a properties set

  • props – a properties set that contains properties to add

  • key1 – a property to add

  • ... – a list of additional properties to add, followed by NULL

Returns:

the number of properties that were changed

gint wp_properties_add_keys_from_dict(WpProperties *self, const struct spa_dict *dict, const gchar *key1, ...)

Adds new properties in self, using the given dict as a source.

Unlike wp_properties_add_from_dict(), this function only adds properties that have one of the specified keys; the rest is left untouched.

Parameters:

  • self – a properties set

  • dict – a spa_dict that contains properties to add

  • key1 – a property to add

  • ... – a list of additional properties to add, followed by NULL

Returns:

the number of properties that were changed

gint wp_properties_add_keys_array(WpProperties *self, WpProperties *props, const gchar *keys[])

The same as wp_properties_add_keys(), using a NULL-terminated array for specifying the keys to add.

Parameters:

  • self – a properties set

  • props – a properties set that contains properties to add

  • keys – (array zero-terminated=1): the properties to add

Returns:

the number of properties that were changed

const gchar *wp_properties_get(WpProperties *self, const gchar *key)

Looks up a given property value from a key.

Parameters:

  • self – a properties object

  • key – a property key

Returns:

(transfer none) (nullable): the value of the property identified with key, or NULL if this property is not contained in self

gint wp_properties_set(WpProperties *self, const gchar *key, const gchar *value)

Sets the given property key - value pair on self.

If the property already existed, the value is overwritten with the new one.

If the value is NULL, then the specified property is removed from self

Parameters:

  • self – a properties object

  • key – a property key

  • value – (nullable): a property value

Returns:

1 if the property was changed. 0 if nothing was changed because the property already existed with the same value or because the key to remove did not exist.

gint wp_properties_setf(WpProperties *self, const gchar *key, const gchar *format, ...)

Formats the given format string with the specified arguments and sets the result as a value of the property specified with key.

Parameters:

  • self – a properties object

  • key – a property key

  • format – a printf-style format to be formatted and set as a value for this property key

  • ... – arguments for format

Returns:

1 if the property was changed. 0 if nothing was changed because the property already existed with the same value

gint wp_properties_setf_valist(WpProperties *self, const gchar *key, const gchar *format, va_list args)

This is the va_list version of wp_properties_setf()

Parameters:

  • self – a properties object

  • key – a property key

  • format – a printf-style format to be formatted and set as a value for this property key

  • args – the variable arguments passed to wp_properties_setf()

Returns:

1 if the property was changed. 0 if nothing was changed because the property already existed with the same value

WpPropertiesItem *wp_properties_item_ref(WpPropertiesItem *self)

Increases the reference count of a properties item object.

Since

0.4.2

Parameters:

  • self – a properties item object

Returns:

(transfer full): self with an additional reference count on it

void wp_properties_item_unref(WpPropertiesItem *self)

Decreases the reference count on self and frees it when the ref count reaches zero.

Since

0.4.2

Parameters:

  • self – (transfer full): a properties item object

const gchar *wp_properties_item_get_key(WpPropertiesItem *self)

Gets the key from a properties item.

Since

0.4.2

Parameters:
Returns:

(transfer none): the property key of the item

const gchar *wp_properties_item_get_value(WpPropertiesItem *self)

Gets the value from a properties item.

Since

0.4.2

Parameters:
Returns:

(transfer none): the property value of the item

WpIterator *wp_properties_new_iterator(WpProperties *self)

Iterates through all the properties in the properties object.

Parameters:

  • self – a properties object

Returns:

(transfer full): an iterator that iterates over the properties. The items in the iterator are of type WpPropertiesItem. Use wp_properties_item_get_key() and wp_properties_item_get_value() to retrieve their contents.

guint wp_properties_get_count(WpProperties *self)

Gets the number of properties contained in this object.

Since

0.4.10

Parameters:

  • self – a properties object

Returns:

the number of properties contained in this object

void wp_properties_sort(WpProperties *self)

Sorts the keys in alphabetical order.

Parameters:

  • self – a properties object

const struct spa_dict *wp_properties_peek_dict(WpProperties *self)

Gets the dictionary wrapped by a properties object.

Parameters:

  • self – a properties object

Returns:

(transfer none): the internal properties set as a struct spa_dict *

struct pw_properties *wp_properties_to_pw_properties(WpProperties *self)

Gets a copy of the properties object as a struct pw_properties

Parameters:

  • self – a properties object

Returns:

(transfer full): a copy of the properties in self as a struct pw_properties

struct pw_properties *wp_properties_unref_and_take_pw_properties(WpProperties *self)

Similar to wp_properties_to_pw_properties(), but this method avoids making a copy of the properties by returning the struct pw_properties that is stored internally and then freeing the WpProperties wrapper.

If self is not uniquely owned (see wp_properties_ensure_unique_owner()), then this method does make a copy and is the same as wp_properties_to_pw_properties(), performance-wise.

Parameters:

  • self – (transfer full): a properties object

Returns:

(transfer full): the properties in self as a struct pw_properties

gboolean wp_properties_matches(WpProperties *self, WpProperties *other)

Checks if all property values contained in other are matching with the values in self.

If a property is contained in other and not in self, the result is not matched. If a property is contained in both sets, then the value of the property in other is interpreted as a glob-style pattern (using g_pattern_match_simple()) and the value in self is checked to see if it matches with this pattern.

Parameters:

  • self – a properties object

  • other – a set of properties to match

Returns:

TRUE if all matches were successfull, FALSE if at least one property value did not match

WP_TYPE_PROPERTIES (wp_properties_get_type ())

The WpProperties GType.