PipeWire: Properties

PipeWire 1.6.5

Loading...
Searching...
No Matches
Properties
Utilities

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

## Files
file | properties.h
| pipewire/properties.h

## Data Structures
struct | pw_properties

## Macros
#define | PW_PROPERTIES_FLAG_NL (1<<0)
#define | PW_PROPERTIES_FLAG_RECURSE (1<<1)
#define | PW_PROPERTIES_FLAG_ENCLOSE (1<<2)
#define | PW_PROPERTIES_FLAG_ARRAY (1<<3)
#define | PW_PROPERTIES_FLAG_COLORS (1<<4)

## Functions
struct pw_properties * | pw_properties_new (const char *key,...)
| Make a new properties object.
struct pw_properties * | pw_properties_new_dict (const struct spa_dict *dict)
| Make a new properties object from the given dictionary.
struct pw_properties * | pw_properties_new_string (const char *args)
| Make a new properties object from the given str.
struct pw_properties * | pw_properties_new_string_checked (const char *args, size_t size, struct spa_error_location *loc)
struct pw_properties * | pw_properties_copy (const struct pw_properties *properties)
| Copy a properties object.
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.
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.
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.
int | pw_properties_update_string_checked (struct pw_properties *props, const char *str, size_t size, struct spa_error_location *loc)
| Check str is a well-formed properties JSON string and update the properties on success.
int | pw_properties_add (struct pw_properties *oldprops, const struct spa_dict *dict)
| Add properties.
int | pw_properties_add_keys (struct pw_properties *oldprops, const struct spa_dict *dict, const char *const keys[])
| Add keys.
void | pw_properties_clear (struct pw_properties *properties)
| Clear a properties object.
void | pw_properties_free (struct pw_properties *properties)
| Free a properties object.
int | pw_properties_set (struct pw_properties *properties, const char *key, const char *value)
| Set a property value.
int | pw_properties_setf (struct pw_properties *properties, const char *key, const char *format,...)
| Set a property value by format.
int | pw_properties_setva (struct pw_properties *properties, const char *key, const char *format, va_list args)
const char * | pw_properties_get (const struct pw_properties *properties, const char *key)
| Get a property.
int | pw_properties_fetch_uint32 (const struct pw_properties *properties, const char *key, uint32_t *value)
| Fetch a property as uint32_t.
int | pw_properties_fetch_int32 (const struct pw_properties *properties, const char *key, int32_t *value)
| Fetch a property as int32_t.
int | pw_properties_fetch_uint64 (const struct pw_properties *properties, const char *key, uint64_t *value)
| Fetch a property as uint64_t.
int | pw_properties_fetch_int64 (const struct pw_properties *properties, const char *key, int64_t *value)
| Fetch a property as int64_t.
int | pw_properties_fetch_bool (const struct pw_properties *properties, const char *key, bool *value)
| Fetch a property as boolean value.
PW_API_PROPERTIES uint32_t | pw_properties_get_uint32 (const struct pw_properties *properties, const char *key, uint32_t deflt)
PW_API_PROPERTIES int32_t | pw_properties_get_int32 (const struct pw_properties *properties, const char *key, int32_t deflt)
PW_API_PROPERTIES uint64_t | pw_properties_get_uint64 (const struct pw_properties *properties, const char *key, uint64_t deflt)
PW_API_PROPERTIES int64_t | pw_properties_get_int64 (const struct pw_properties *properties, const char *key, int64_t deflt)
PW_API_PROPERTIES bool | pw_properties_get_bool (const struct pw_properties *properties, const char *key, bool deflt)
const char * | pw_properties_iterate (const struct pw_properties *properties, void **state)
| Iterate property values.
int | pw_properties_serialize_dict (FILE *f, const struct spa_dict *dict, uint32_t flags)
PW_API_PROPERTIES bool | pw_properties_parse_bool (const char *value)
PW_API_PROPERTIES int | pw_properties_parse_int (const char *value)
PW_API_PROPERTIES int64_t | pw_properties_parse_int64 (const char *value)
PW_API_PROPERTIES uint64_t | pw_properties_parse_uint64 (const char *value)
PW_API_PROPERTIES float | pw_properties_parse_float (const char *value)
PW_API_PROPERTIES double | pw_properties_parse_double (const char *value)

## 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)

## ◆ PW_PROPERTIES_FLAG_RECURSE

#define PW_PROPERTIES_FLAG_RECURSE (1<<1)

## ◆ PW_PROPERTIES_FLAG_ENCLOSE

#define PW_PROPERTIES_FLAG_ENCLOSE (1<<2)

## ◆ PW_PROPERTIES_FLAG_ARRAY

#define PW_PROPERTIES_FLAG_ARRAY (1<<3)

## ◆ PW_PROPERTIES_FLAG_COLORS

#define PW_PROPERTIES_FLAG_COLORS (1<<4)

## Function Documentation

## ◆ 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

Examples
  audio-capture.c, audio-dsp-filter.c, audio-dsp-sink.c, audio-dsp-sink2.c, audio-dsp-src.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, internal.c, midi-src.c, tutorial4.c, tutorial5.c, tutorial7.c, video-dsp-play.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play-sync.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, video-src-sync.c, and video-src.c.

## ◆ 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

## ◆ 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

## ◆ pw_properties_new_string_checked()

struct pw_properties * pw_properties_new_string_checked | ( | const char * | args,
|  | size_t | size,
|  | struct spa_error_location * | loc )

## ◆ 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

## ◆ 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

## ◆ pw_properties_update_ignore()

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

## ◆ 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.

## ◆ 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

## ◆ pw_properties_update_string_checked()

int pw_properties_update_string_checked | ( | struct pw_properties * | props,
|  | const char * | str,
|  | size_t | size,
|  | struct spa_error_location * | loc )

Check str is a well-formed properties JSON string and update the properties on success.

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

When the check fails, this function will not update props.

Parameters

  props | The properties to attempt to update, maybe be NULL to simply check the JSON string.
  str | The JSON object with new values
  size | The length of the JSON string.
  loc | Return value for parse error location

Returns
  a negative value when string is not valid and loc contains the error location or the number of updated properties in props.

Since
  1.1.0

## ◆ 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.

## ◆ 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.

## ◆ pw_properties_clear()

void pw_properties_clear | ( | struct pw_properties * | properties | ) |

Clear a properties object.

Parameters

  properties | properties to clear

Examples
  internal.c.

## ◆ pw_properties_free()

void pw_properties_free | ( | struct pw_properties * | properties | ) |

Free a properties object.

Parameters

  properties | the properties to free

Examples
  export-sink.c, export-source.c, export-spa.c, and internal.c.

## ◆ 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. < 0 if an error occurred and nothing was changed.

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.

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, export-sink.c, export-source.c, export-spa.c, tutorial5.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play-sync.c, and video-play.c.

## ◆ pw_properties_setf()

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

Set a property value by format.

Parameters

  properties | a Properties
  key | a key
  format | a value
  ... | extra arguments

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.

Set the property in properties with key to the value in printf style format Any previous value of key will be overwritten.

Examples
  internal.c.

## ◆ pw_properties_setva()

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

## ◆ pw_properties_get()

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

Get a property.

Parameters

  properties | a Properties
  key | a key

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

Get the property in properties with key.

## ◆ pw_properties_fetch_uint32()

int pw_properties_fetch_uint32 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | uint32_t * | value )

Fetch a property as uint32_t.

Parameters

  properties | a Properties
  key | a key
  value | set to the value of the property on success, otherwise left unmodified

Returns
  0 on success or a negative errno otherwise

Return values

  -ENOENT | The property does not exist
  -EINVAL | The property is not in the expected format

## ◆ pw_properties_fetch_int32()

int pw_properties_fetch_int32 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | int32_t * | value )

Fetch a property as int32_t.

Parameters

  properties | a Properties
  key | a key
  value | set to the value of the property on success, otherwise left unmodified

Returns
  0 on success or a negative errno otherwise

Return values

  -ENOENT | The property does not exist
  -EINVAL | The property is not in the expected format

## ◆ pw_properties_fetch_uint64()

int pw_properties_fetch_uint64 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | uint64_t * | value )

Fetch a property as uint64_t.

Parameters

  properties | a Properties
  key | a key
  value | set to the value of the property on success, otherwise left unmodified

Returns
  0 on success or a negative errno otherwise

Return values

  -ENOENT | The property does not exist
  -EINVAL | The property is not in the expected format

## ◆ pw_properties_fetch_int64()

int pw_properties_fetch_int64 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | int64_t * | value )

Fetch a property as int64_t.

Parameters

  properties | a Properties
  key | a key
  value | set to the value of the property on success, otherwise left unmodified

Returns
  0 on success or a negative errno otherwise

Return values

  -ENOENT | The property does not exist
  -EINVAL | The property is not in the expected format

## ◆ pw_properties_fetch_bool()

int pw_properties_fetch_bool | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | bool * | value )

Fetch a property as boolean value.

Parameters

  properties | a Properties
  key | a key
  value | set to the value of the property on success, otherwise left unmodified

Returns
  0 on success or a negative errno otherwise

Return values

  -ENOENT | The property does not exist
  -EINVAL | The property is not in the expected format

## ◆ pw_properties_get_uint32()

PW_API_PROPERTIES uint32_t pw_properties_get_uint32 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | uint32_t | deflt )

## ◆ pw_properties_get_int32()

PW_API_PROPERTIES int32_t pw_properties_get_int32 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | int32_t | deflt )

## ◆ pw_properties_get_uint64()

PW_API_PROPERTIES uint64_t pw_properties_get_uint64 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | uint64_t | deflt )

## ◆ pw_properties_get_int64()

PW_API_PROPERTIES int64_t pw_properties_get_int64 | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | int64_t | deflt )

## ◆ pw_properties_get_bool()

PW_API_PROPERTIES bool pw_properties_get_bool | ( | const struct pw_properties * | properties,
|  | const char * | key,
|  | bool | deflt )

## ◆ pw_properties_iterate()

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

Iterate property values.

Parameters

  properties | a Properties
  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.

## ◆ pw_properties_serialize_dict()

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

## ◆ pw_properties_parse_bool()

PW_API_PROPERTIES bool pw_properties_parse_bool | ( | const char * | value | ) |

## ◆ pw_properties_parse_int()

PW_API_PROPERTIES int pw_properties_parse_int | ( | const char * | value | ) |

## ◆ pw_properties_parse_int64()

PW_API_PROPERTIES int64_t pw_properties_parse_int64 | ( | const char * | value | ) |

## ◆ pw_properties_parse_uint64()

PW_API_PROPERTIES uint64_t pw_properties_parse_uint64 | ( | const char * | value | ) |

## ◆ pw_properties_parse_float()

PW_API_PROPERTIES float pw_properties_parse_float | ( | const char * | value | ) |

## ◆ pw_properties_parse_double()

PW_API_PROPERTIES double pw_properties_parse_double | ( | const char * | value | ) |