Wp.Properties¶

Fields¶

None

Methods¶

class	`new_copy` (props)
class	`new_copy_dict` (dict)
class	`new_empty` ()
class	`new_json` (json)
class	`new_string` (str)
class	`new_take` (props)
class	`new_wrap` (props)
class	`new_wrap_dict` (dict)
	`add` (props)
	`add_from_dict` (dict)
	`add_keys_array` (props, keys)
	`copy` ()
	`ensure_unique_owner` ()
	`get` (key)
	`get_count` ()
	`matches` (other)
	`new_iterator` ()
	`peek_dict` ()
	`ref` ()
	`set` (key, value)
	`sort` ()
	`to_pw_properties` ()
	`unref` ()
	`unref_and_take_pw_properties` ()
	`update` (props)
	`update_from_dict` (dict)
	`update_from_json` (json)
	`update_keys_array` (props, keys)

Details¶

class Wp.Properties¶

Wp.Properties 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 GLib.HashTable 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. Wp.Properties 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 Wp.Properties 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. Wp.Properties is reference-counted with Wp.Properties.ref() and Wp.Properties.unref().

classmethod new_copy(props)¶

Parameters:: props (object or None) – a native pw_properties structure to copy
Returns:: the newly constructed properties set
Return type:: Wp.Properties

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

classmethod new_copy_dict(dict)¶

Parameters:: dict (object or None) – a native spa_dict structure to copy
Returns:: the newly constructed properties set
Return type:: Wp.Properties

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

classmethod new_empty()¶

Returns:: the newly constructed properties set
Return type:: Wp.Properties

Creates a new empty properties set.

classmethod new_json(json)¶

Parameters:: json (Wp.SpaJson) – a JSON object
Returns:: the newly constructed properties set
Return type:: Wp.Properties

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

classmethod new_string(str)¶

Parameters:: str (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:: the newly constructed properties set
Return type:: Wp.Properties

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

classmethod new_take(props)¶

Parameters:: props (object or None) – a native pw_properties structure to wrap
Returns:: the newly constructed properties set
Return type:: Wp.Properties

Constructs a new Wp.Properties that wraps the given props structure, allowing reading & writing properties on that props structure through the Wp.Properties 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.

classmethod new_wrap(props)¶

Parameters:: props (object or None) – a native pw_properties structure to wrap
Returns:: the newly constructed properties set
Return type:: Wp.Properties

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

Care must be taken when using this function, since the returned Wp.Properties object does not own the props structure. Therefore, if the owner decides to free props, the returned Wp.Properties will crash when used. In addition, the returned Wp.Properties object will not try to free props when destroyed. Furthermore, note that the returned Wp.Properties object is immutable. That means that you cannot add or modify any properties on it, unless you make a copy first.

classmethod new_wrap_dict(dict)¶

Parameters:: dict (object or None) – a native spa_dict structure to wrap
Returns:: the newly constructed properties set
Return type:: Wp.Properties

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

Note that the returned object does not own the dict, so care must be taken not to free it externally while this Wp.Properties object is alive. In addition, note that the returned Wp.Properties 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().

add(props)¶

Parameters:: props (Wp.Properties) – a properties set that contains properties to add
Returns:: the number of properties that were changed
Return type:: int

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.

add_from_dict(dict)¶

Parameters:: dict (object or None) – a spa_dict that contains properties to add
Returns:: the number of properties that were changed
Return type:: int

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.

add_keys_array(props, keys)¶

Parameters:

props (Wp.Properties) – a properties set that contains properties to add
keys ([str]) – the properties to add

Returns:

the number of properties that were changed

Return type:

int

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

copy()¶

Returns:: the newly constructed properties set
Return type:: Wp.Properties

Constructs and returns a new Wp.Properties object that contains a copy of all the properties contained in self.

ensure_unique_owner()¶

Returns:: the uniquely owned properties object
Return type:: Wp.Properties

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.

get(key)¶

Parameters:: key (str) – a property key
Returns:: the value of the property identified with key, or None if this property is not contained in self
Return type:: str or None

Looks up a given property value from a key.

get_count()¶

Returns:: the number of properties contained in this object
Return type:: int

Gets the number of properties contained in this object.

New in version 0.4.10.

matches(other)¶

Parameters:: other (Wp.Properties) – a set of properties to match
Returns:: True if all matches were successfull, False if at least one property value did not match
Return type:: bool

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 GLib.pattern_match_simple()) and the value in self is checked to see if it matches with this pattern.

new_iterator()¶

Returns:: an iterator that iterates over the properties. The items in the iterator are of type Wp.PropertiesItem. Use Wp.PropertiesItem.get_key() and Wp.PropertiesItem.get_value() to retrieve their contents.
Return type:: Wp.Iterator

Iterates through all the properties in the properties object.

peek_dict()¶

Returns:: the internal properties set as a struct spa_dict *
Return type:: object or None

Gets the dictionary wrapped by a properties object.

ref()¶

Return type:: Wp.Properties

set(key, value)¶

Parameters:

key (str) – a property key
value (str or None) – 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.

Return type:

int

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 None, then the specified property is removed from self

sort()¶: Sorts the keys in alphabetical order.

to_pw_properties()¶

Returns:: a copy of the properties in self as a struct pw_properties
Return type:: object or None

Gets a copy of the properties object as a struct pw_properties

unref()¶: Decreases the reference count on self and frees it when the ref count reaches zero.

unref_and_take_pw_properties()¶

Returns:: the properties in self as a struct pw_properties
Return type:: object or None

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 Wp.Properties 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.

update(props)¶

Parameters:: props (Wp.Properties) – a properties set that contains properties to update
Returns:: the number of properties that were changed
Return type:: int

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.

update_from_dict(dict)¶

Parameters:: dict (object or None) – a spa_dict that contains properties to update
Returns:: the number of properties that were changed
Return type:: int

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.

update_from_json(json)¶

Parameters:: json (Wp.SpaJson) – a JSON object that contains properties to update
Returns:: the number of properties that were changed
Return type:: int

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.

update_keys_array(props, keys)¶

Parameters:

props (Wp.Properties) – a properties set that contains properties to update
keys ([str]) – the properties to update

Returns:

the number of properties that were changed

Return type:

int

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