Key-Value pairs

Properties are used to pass around arbitrary key/value pairs. More...

Data Structures
struct	pw_properties

Macros
#define	PW_PROPERTIES_FLAG_NL   (1<<0)

Functions
struct pw_properties *	pw_properties_new (const char *key,...) 1
	Make a new properties object. More...
struct pw_properties *	pw_properties_new_dict (const struct spa_dict *dict)
	Make a new properties object from the given dictionary. More...
struct pw_properties *	pw_properties_new_string (const char *args)
	Make a new properties object from the given str. More...
struct pw_properties *	pw_properties_copy (const struct pw_properties *properties)
	Copy a properties object. More...
int	pw_properties_update_keys (struct pw_properties *props, const struct spa_dict *dict, const char *const keys[])
	Copy multiple keys from one property to another. More...
int	pw_properties_update_ignore (struct pw_properties *props, const struct spa_dict *dict, const char *const ignore[])
int	pw_properties_update (struct pw_properties *props, const struct spa_dict *dict)
	Update properties. More...
int	pw_properties_update_string (struct pw_properties *props, const char *str, size_t size)
	Update the properties from the given string, overwriting any existing keys with the new values from str. More...
int	pw_properties_add (struct pw_properties *oldprops, const struct spa_dict *dict)
	Add properties. More...
int	pw_properties_add_keys (struct pw_properties *oldprops, const struct spa_dict *dict, const char *const keys[])
	Add keys. More...
void	pw_properties_clear (struct pw_properties *properties)
	Clear a properties object. More...
void	pw_properties_free (struct pw_properties *properties)
	Free a properties object. More...
int	pw_properties_set (struct pw_properties *properties, const char *key, const char *value)
	Set a property value. More...
int	pw_properties_setf (struct pw_properties *properties, const char *key, const char *format,...) 1(3
int int	pw_properties_setva (struct pw_properties *properties, const char *key, const char *format, va_list args) 1(3
int int const char *	pw_properties_get (const struct pw_properties *properties, const char *key)
	Get a property. More...
const char *	pw_properties_iterate (const struct pw_properties *properties, void **state)
	Iterate property values. More...
int	pw_properties_serialize_dict (FILE *f, const struct spa_dict *dict, uint32_t flags)

Detailed Description

Properties are used to pass around arbitrary key/value pairs.

Both keys and values are strings which keeps things simple. Encoding of arbitrary values should be done by using a string serialization such as base64 for binary blobs.

Macro Definition Documentation

PW_PROPERTIES_FLAG_NL

#define PW_PROPERTIES_FLAG_NL   (1<<0)

Function Documentation

pw_properties_add()

int pw_properties_add	(	struct pw_properties *	props,
		const struct spa_dict *	dict
	)

Add properties.

Parameters

props	properties to add
dict	new properties

Returns

the number of added properties

The properties from dict that are not yet in props are added.

References spa_dict::items, spa_dict_item::key, spa_dict::n_items, props, pw_properties_get(), pw_properties_set(), and spa_dict_item::value.

pw_properties_add_keys()

int pw_properties_add_keys	(	struct pw_properties *	props,
		const struct spa_dict *	dict,
		const char *const	keys[]
	)

Add keys.

Parameters

props	properties to add
dict	new properties
keys	a NULL terminated list of keys to add

Returns

the number of added properties

The properties with keys from dict that are not yet in props are added.

References props, pw_properties_get(), pw_properties_set(), and spa_dict_lookup().

pw_properties_clear()

void pw_properties_clear

(

struct pw_properties *

properties

)

Clear a properties object.

Parameters

properties

properties to clear

References pw_array_for_each, and SPA_CONTAINER_OF.

Referenced by pw_properties_free().

pw_properties_copy()

struct pw_properties* pw_properties_copy

(

const struct pw_properties *

properties

)

Copy a properties object.

Parameters

properties

properties to copy

Returns

a new properties object

References dict, and pw_properties_new_dict().

Referenced by pipewire__module_init().

pw_properties_free()

void pw_properties_free

(

struct pw_properties *

properties

)

Free a properties object.

Parameters

properties

the properties to free

References pw_properties_clear(), and SPA_CONTAINER_OF.

Referenced by pw_context_create_core(), pw_context_create_factory(), pw_context_destroy(), pw_impl_core_destroy(), pw_impl_factory_destroy(), pw_impl_module_destroy(), and sm_bluez5_monitor_start().

pw_properties_get()

int int const char* pw_properties_get	(	const struct pw_properties *	properties,
		const char *	key
	)

Get a property.

Parameters

properties	a Key-Value pairs
key	a key

Returns

the property for key or NULL when the key was not found

Get the property in properties with key.

References SPA_CONTAINER_OF.

Referenced by main(), pipewire__module_init(), pw_context_create_core(), pw_context_get_conf_section(), pw_context_parse_conf_section(), pw_filter_connect(), pw_properties_add(), pw_properties_add_keys(), sm_alsa_midi_start(), sm_alsa_monitor_start(), sm_bluez5_monitor_start(), and sm_policy_node_start().

pw_properties_iterate()

const char* pw_properties_iterate	(	const struct pw_properties *	properties,
		void **	state
	)

Iterate property values.

Parameters

properties	a Key-Value pairs
state	state

Returns

The next key or NULL when there are no more keys to iterate.

Iterate over properties, returning each key in turn. state should point to a pointer holding NULL to get the first element and will be updated after each iteration. When NULL is returned, all elements have been iterated.

References pw_array_check_index, pw_array_get_unchecked, SPA_CONTAINER_OF, SPA_INT_TO_PTR, and SPA_PTR_TO_INT.

Referenced by sm_bluez5_monitor_start().

pw_properties_new()

struct pw_properties* pw_properties_new	(	const char *	key,
			...
	)

Make a new properties object.

Parameters

key	a first key
...	value and more keys NULL terminated

Returns

a newly allocated properties object

Referenced by main(), pipewire__module_init(), pw_context_connect_self(), pw_context_create_client(), pw_context_create_core(), pw_context_create_device(), pw_context_create_factory(), pw_context_create_metadata(), pw_context_create_node(), pw_context_create_port(), pw_filter_add_port(), pw_filter_new_simple(), pw_global_new(), pw_stream_new_simple(), sm_alsa_midi_start(), sm_alsa_monitor_start(), sm_bluez5_autoswitch_start(), sm_bluez5_monitor_start(), sm_default_nodes_start(), sm_default_profile_start(), sm_default_routes_start(), sm_restore_stream_start(), and sm_v4l2_monitor_start().

pw_properties_new_dict()

struct pw_properties* pw_properties_new_dict

(

const struct spa_dict *

dict

)

Make a new properties object from the given dictionary.

Parameters

dict	a dictionary. keys and values are copied

Returns

a new properties object

Referenced by pw_context_create_port(), and pw_properties_copy().

pw_properties_new_string()

struct pw_properties* pw_properties_new_string

(

const char *

object

)

Make a new properties object from the given str.

object should be a whitespace separated list of key=value strings or a json object.

Parameters

object

a property description

Returns

a new properties object

Referenced by pipewire__module_init().

pw_properties_serialize_dict()

int pw_properties_serialize_dict	(	FILE *	f,
		const struct spa_dict *	dict,
		uint32_t	flags
	)

References spa_dict_item::key, PW_PROPERTIES_FLAG_NL, spa_dict_for_each, spa_json_encode_string(), spa_json_is_bool(), spa_json_is_container(), spa_json_is_float(), spa_json_is_null(), spa_json_is_string(), and spa_dict_item::value.

pw_properties_set()

int pw_properties_set	(	struct pw_properties *	properties,
		const char *	key,
		const char *	value
	)

Set a property value.

Parameters

properties	the properties to change
key	a key
value	a value or NULL to remove the key

Returns

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

Set the property in properties with key to value. Any previous value of key will be overwritten. When value is NULL, the key will be removed.

Referenced by pipewire__module_init(), pw_context_connect_self(), pw_context_create_metadata(), pw_context_create_port(), pw_properties_add(), pw_properties_add_keys(), pw_properties_update(), pw_properties_update_keys(), pw_properties_update_string(), sm_bluez5_monitor_start(), and sm_streams_follow_default_start().

pw_properties_setf()

int pw_properties_setf	(	struct pw_properties *	properties,
		const char *	key,
		const char *	format,
			...
	)

Referenced by pipewire__module_init(), pw_context_create_core(), and pw_context_create_port().

pw_properties_setva()

int int pw_properties_setva	(	struct pw_properties *	properties,
		const char *	key,
		const char *	format,
		va_list	args
	)

pw_properties_update()

int pw_properties_update	(	struct pw_properties *	props,
		const struct spa_dict *	dict
	)

Update properties.

Parameters

props	properties to update
dict	new properties

Returns

the number of changed properties

The properties in props are updated with dict. Keys in dict with NULL values are removed from props.

References spa_dict_item::key, props, pw_properties_set(), spa_dict_for_each, and spa_dict_item::value.

Referenced by pw_context_update_properties(), pw_core_update_properties(), pw_filter_update_properties(), pw_impl_core_update_properties(), pw_impl_factory_update_properties(), pw_impl_module_update_properties(), and pw_stream_update_properties().

pw_properties_update_ignore()

int pw_properties_update_ignore	(	struct pw_properties *	props,
		const struct spa_dict *	dict,
		const char *const	ignore[]
	)

References spa_dict_for_each.

pw_properties_update_keys()

int pw_properties_update_keys	(	struct pw_properties *	props,
		const struct spa_dict *	dict,
		const char *const	keys[]
	)

Copy multiple keys from one property to another.

Parameters

props	properties to copy to
dict	properties to copy from
keys	a NULL terminated list of keys to copy

Returns

the number of keys changed in dest

References dict, props, pw_properties_set(), and spa_dict_lookup().

Referenced by pw_global_update_keys().

pw_properties_update_string()

int pw_properties_update_string	(	struct pw_properties *	props,
		const char *	str,
		size_t	size
	)

Update the properties from the given string, overwriting any existing keys with the new values from str.

str should be a whitespace separated list of key=value strings or a json object, see pw_properties_new_string().

Returns

The number of properties added or updated

References props, pw_properties_set(), SPA_CONTAINER_OF, spa_json_container_len(), spa_json_enter_object(), spa_json_get_string(), spa_json_init(), spa_json_is_container(), spa_json_is_null(), spa_json_next(), spa_json_parse_string(), and impl::this.

Referenced by main(), pipewire__module_init(), sm_alsa_monitor_start(), and sm_bluez5_monitor_start().