PipeWire: Device

PipeWire 0.3.51

Files | Data Structures | Macros | Enumerations | Functions | Variables
Device
SPA

The device interface can be used to monitor all kinds of devices and create objects as a result. More...

## Files
file | device.h
| `spa/monitor/device.h`
file | event.h
| `spa/monitor/event.h`
file | type-info.h
| `spa/monitor/type-info.h`

## Data Structures
struct | spa_device
struct | spa_device_info
| Information about the device and parameters it supports. More...
struct | spa_device_object_info
| Information about a device object. More...
struct | spa_result_device_params
struct | spa_device_events
| spa_device_events: More...
struct | spa_device_methods
| spa_device_methods: More...
struct | spa_result_device_params_data

## Macros
#define | SPA_TYPE_INTERFACE_Device SPA_TYPE_INFO_INTERFACE_BASE "Device"
#define | SPA_VERSION_DEVICE 0
#define | SPA_VERSION_DEVICE_INFO 0
#define | SPA_DEVICE_CHANGE_MASK_FLAGS (1u<<0)
#define | SPA_DEVICE_CHANGE_MASK_PROPS (1u<<1)
#define | SPA_DEVICE_CHANGE_MASK_PARAMS (1u<<2)
#define | SPA_DEVICE_INFO_INIT() (struct spa_device_info){ SPA_VERSION_DEVICE_INFO, }
#define | SPA_VERSION_DEVICE_OBJECT_INFO 0
#define | SPA_DEVICE_OBJECT_CHANGE_MASK_FLAGS (1u<<0)
#define | SPA_DEVICE_OBJECT_CHANGE_MASK_PROPS (1u<<1)
#define | SPA_DEVICE_OBJECT_INFO_INIT() (struct spa_device_object_info){ SPA_VERSION_DEVICE_OBJECT_INFO, }
#define | SPA_RESULT_TYPE_DEVICE_PARAMS 1
| the result of spa_device_enum_params() More...
#define | SPA_DEVICE_EVENT_INFO 0
#define | SPA_DEVICE_EVENT_RESULT 1
#define | SPA_DEVICE_EVENT_EVENT 2
#define | SPA_DEVICE_EVENT_OBJECT_INFO 3
#define | SPA_DEVICE_EVENT_NUM 4
#define | SPA_VERSION_DEVICE_EVENTS 0
| version of the structure More...
#define | SPA_DEVICE_METHOD_ADD_LISTENER 0
#define | SPA_DEVICE_METHOD_SYNC 1
#define | SPA_DEVICE_METHOD_ENUM_PARAMS 2
#define | SPA_DEVICE_METHOD_SET_PARAM 3
#define | SPA_DEVICE_METHOD_NUM 4
#define | SPA_VERSION_DEVICE_METHODS 0
#define | spa_device_method(o, method, version, ...)
#define | spa_device_add_listener(d, ...) spa_device_method(d, add_listener, 0, __VA_ARGS__)
| Set events to receive asynchronous notifications from the device. More...
#define | spa_device_sync(d, ...) spa_device_method(d, sync, 0, __VA_ARGS__)
| Perform a sync operation. More...
#define | spa_device_enum_params(d, ...) spa_device_method(d, enum_params, 0, __VA_ARGS__)
| Enumerate the parameters of a device. More...
#define | spa_device_set_param(d, ...) spa_device_method(d, set_param, 0, __VA_ARGS__)
| Set the configurable parameter in device. More...
#define | SPA_KEY_DEVICE_ENUM_API "device.enum.api"
| the api used to discover this device More...
#define | SPA_KEY_DEVICE_API "device.api"
| the api used by the device Ex. More...
#define | SPA_KEY_DEVICE_NAME "device.name"
| the name of the device More...
#define | SPA_KEY_DEVICE_ALIAS "device.alias"
| alternative name of the device More...
#define | SPA_KEY_DEVICE_NICK "device.nick"
| the device short name More...
#define | SPA_KEY_DEVICE_DESCRIPTION "device.description"
| a device description More...
#define | SPA_KEY_DEVICE_ICON "device.icon"
| icon for the device. More...
#define | SPA_KEY_DEVICE_ICON_NAME "device.icon-name"
| an XDG icon name for the device. More...
#define | SPA_KEY_DEVICE_PLUGGED_USEC "device.plugged.usec"
| when the device was plugged More...
#define | SPA_KEY_DEVICE_BUS_ID "device.bus-id"
| the device bus-id More...
#define | SPA_KEY_DEVICE_BUS_PATH "device.bus-path"
| bus path to the device in the OS' format. More...
#define | SPA_KEY_DEVICE_BUS "device.bus"
| bus of the device if applicable. More...
#define | SPA_KEY_DEVICE_SUBSYSTEM "device.subsystem"
| device subsystem More...
#define | SPA_KEY_DEVICE_SYSFS_PATH "device.sysfs.path"
| device sysfs path More...
#define | SPA_KEY_DEVICE_VENDOR_ID "device.vendor.id"
| vendor ID if applicable More...
#define | SPA_KEY_DEVICE_VENDOR_NAME "device.vendor.name"
| vendor name if applicable More...
#define | SPA_KEY_DEVICE_PRODUCT_ID "device.product.id"
| product ID if applicable More...
#define | SPA_KEY_DEVICE_PRODUCT_NAME "device.product.name"
| product name if applicable More...
#define | SPA_KEY_DEVICE_SERIAL "device.serial"
| Serial number if applicable. More...
#define | SPA_KEY_DEVICE_CLASS "device.class"
| device class More...
#define | SPA_KEY_DEVICE_CAPABILITIES "device.capabilities"
| api specific device capabilities More...
#define | SPA_KEY_DEVICE_FORM_FACTOR "device.form-factor"
| form factor if applicable. More...
#define | SPA_KEY_DEVICE_PROFILE "device.profile "
| profile for the device More...
#define | SPA_KEY_DEVICE_PROFILE_SET "device.profile-set"
| profile set for the device More...
#define | SPA_KEY_DEVICE_STRING "device.string"
| device string in the underlying layer's format. More...
#define | SPA_DEVICE_EVENT_ID(ev) SPA_EVENT_ID(ev, SPA_TYPE_EVENT_Device)
#define | SPA_DEVICE_EVENT_INIT(id) SPA_EVENT_INIT(SPA_TYPE_EVENT_Device, id)
#define | SPA_TYPE_INFO_DeviceEvent SPA_TYPE_INFO_EVENT_BASE "Device"
#define | SPA_TYPE_INFO_DEVICE_EVENT_BASE SPA_TYPE_INFO_DeviceEvent ":"
#define | SPA_TYPE_INFO_DeviceEventId SPA_TYPE_INFO_ENUM_BASE "DeviceEventId"
#define | SPA_TYPE_INFO_DEVICE_EVENT_ID_BASE SPA_TYPE_INFO_DeviceEventId ":"
#define | spa_device_emit(hooks, method, version, ...)
#define | spa_device_emit_info(hooks, i) spa_device_emit(hooks,info, 0, i)
#define | spa_device_emit_result(hooks, s, r, t, res) spa_device_emit(hooks,result, 0, s, r, t, res)
#define | spa_device_emit_event(hooks, e) spa_device_emit(hooks,event, 0, e)
#define | spa_device_emit_object_info(hooks, id, i) spa_device_emit(hooks,object_info, 0, id, i)

## Enumerations
enum | spa_device_event { SPA_DEVICE_EVENT_ObjectConfig }
enum | spa_event_device { SPA_EVENT_DEVICE_START , SPA_EVENT_DEVICE_Object , SPA_EVENT_DEVICE_Props }

## Functions
static void | spa_result_func_device_params (void *data, int seq, int res, uint32_t type, const void *result)
static int | spa_device_enum_params_sync (struct spa_device *device, uint32_t id, uint32_t *index, const struct spa_pod *filter, struct spa_pod **param, struct spa_pod_builder *builder)

## Variables
static const struct spa_type_info | spa_type_device_event_id []
static const struct spa_type_info | spa_type_device_event []

## Detailed Description

The device interface can be used to monitor all kinds of devices and create objects as a result.

Objects a typically other Devices or Nodes.

## Macro Definition Documentation

## ◆ SPA_TYPE_INTERFACE_Device

#define SPA_TYPE_INTERFACE_Device SPA_TYPE_INFO_INTERFACE_BASE "Device"

Examples
  bluez-session.c, and export-spa-device.c.

## ◆ SPA_VERSION_DEVICE

#define SPA_VERSION_DEVICE 0

## ◆ SPA_VERSION_DEVICE_INFO

#define SPA_VERSION_DEVICE_INFO 0

## ◆ SPA_DEVICE_CHANGE_MASK_FLAGS

#define SPA_DEVICE_CHANGE_MASK_FLAGS (1u<<0)

## ◆ SPA_DEVICE_CHANGE_MASK_PROPS

#define SPA_DEVICE_CHANGE_MASK_PROPS (1u<<1)

## ◆ SPA_DEVICE_CHANGE_MASK_PARAMS

#define SPA_DEVICE_CHANGE_MASK_PARAMS (1u<<2)

## ◆ SPA_DEVICE_INFO_INIT

#define SPA_DEVICE_INFO_INIT | ( |  | ) | (struct spa_device_info){ SPA_VERSION_DEVICE_INFO, }

## ◆ SPA_VERSION_DEVICE_OBJECT_INFO

#define SPA_VERSION_DEVICE_OBJECT_INFO 0

## ◆ SPA_DEVICE_OBJECT_CHANGE_MASK_FLAGS

#define SPA_DEVICE_OBJECT_CHANGE_MASK_FLAGS (1u<<0)

## ◆ SPA_DEVICE_OBJECT_CHANGE_MASK_PROPS

#define SPA_DEVICE_OBJECT_CHANGE_MASK_PROPS (1u<<1)

## ◆ SPA_DEVICE_OBJECT_INFO_INIT

#define SPA_DEVICE_OBJECT_INFO_INIT | ( |  | ) | (struct spa_device_object_info){ SPA_VERSION_DEVICE_OBJECT_INFO, }

## ◆ SPA_RESULT_TYPE_DEVICE_PARAMS

#define SPA_RESULT_TYPE_DEVICE_PARAMS 1

the result of spa_device_enum_params()

## ◆ SPA_DEVICE_EVENT_INFO

#define SPA_DEVICE_EVENT_INFO 0

## ◆ SPA_DEVICE_EVENT_RESULT

#define SPA_DEVICE_EVENT_RESULT 1

## ◆ SPA_DEVICE_EVENT_EVENT

#define SPA_DEVICE_EVENT_EVENT 2

## ◆ SPA_DEVICE_EVENT_OBJECT_INFO

#define SPA_DEVICE_EVENT_OBJECT_INFO 3

## ◆ SPA_DEVICE_EVENT_NUM

#define SPA_DEVICE_EVENT_NUM 4

## ◆ SPA_VERSION_DEVICE_EVENTS

#define SPA_VERSION_DEVICE_EVENTS 0

version of the structure

Examples
  bluez-session.c.

## ◆ SPA_DEVICE_METHOD_ADD_LISTENER

#define SPA_DEVICE_METHOD_ADD_LISTENER 0

## ◆ SPA_DEVICE_METHOD_SYNC

#define SPA_DEVICE_METHOD_SYNC 1

## ◆ SPA_DEVICE_METHOD_ENUM_PARAMS

#define SPA_DEVICE_METHOD_ENUM_PARAMS 2

## ◆ SPA_DEVICE_METHOD_SET_PARAM

#define SPA_DEVICE_METHOD_SET_PARAM 3

## ◆ SPA_DEVICE_METHOD_NUM

#define SPA_DEVICE_METHOD_NUM 4

## ◆ SPA_VERSION_DEVICE_METHODS

#define SPA_VERSION_DEVICE_METHODS 0

## ◆ spa_device_method

#define spa_device_method | ( |  | o,
|  |  | method,
|  |  | version,
|  |  | ...
| ) |  |

## ◆ spa_device_add_listener

#define spa_device_add_listener | ( |  | d,
|  |  | ...
| ) |  | spa_device_method(d, add_listener, 0, __VA_ARGS__)

Set events to receive asynchronous notifications from the device.

Setting the events will trigger the info event and an object_info event for each managed object on the new listener.

Parameters

  object | a Device
  listener | a listener
  events | a struct spa_device_events
  data | data passed as first argument in functions of events

Returns
  0 on success < 0 errno on error

See also
  spa_device_methods.add_listener

Examples
  bluez-session.c.

## ◆ spa_device_sync

#define spa_device_sync | ( |  | d,
|  |  | ...
| ) |  | spa_device_method(d, sync, 0, __VA_ARGS__)

Perform a sync operation.

This method will emit the result event with the given sequence number synchronously or with the returned async return value asynchronously.

Because all methods are serialized in the device, this can be used to wait for completion of all previous method calls.

Parameters

  seq | a sequence number

Returns
  0 on success -EINVAL when node is NULL an async result

See also
  spa_device_methods.sync

## ◆ spa_device_enum_params

#define spa_device_enum_params | ( |  | d,
|  |  | ...
| ) |  | spa_device_method(d, enum_params, 0, __VA_ARGS__)

Enumerate the parameters of a device.

Parameters are identified with an id. Some parameters can have multiple values, see the documentation of the parameter id.

Parameters can be filtered by passing a non-NULL filter.

The result callback will be called at most max times with a struct spa_result_device_params as the result.

This function must be called from the main thread.

Parameters

  device | a Device
  seq | a sequence number to pass to the result function
  id | the param id to enumerate
  index | the index of enumeration, pass 0 for the first item.
  max | the maximum number of items to iterate
  filter | and optional filter to use

Returns
  0 when there are no more parameters to enumerate -EINVAL when invalid arguments are given -ENOENT the parameter id is unknown -ENOTSUP when there are no parameters implemented on device

See also
  spa_device_methods.enum_params

## ◆ spa_device_set_param

#define spa_device_set_param | ( |  | d,
|  |  | ...
| ) |  | spa_device_method(d, set_param, 0, __VA_ARGS__)

Set the configurable parameter in device.

Usually, param will be obtained from enum_params and then modified but it is also possible to set another spa_pod as long as its keys and types match a supported object.

Objects with property keys that are not known are ignored.

This function must be called from the main thread.

Parameters

  object | Device
  id | the parameter id to configure
  flags | additional flags
  param | the parameter to configure

Returns
  0 on success -EINVAL when invalid arguments are given -ENOTSUP when there are no parameters implemented on device -ENOENT the parameter is unknown

See also
  spa_device_methods.set_param

## ◆ SPA_KEY_DEVICE_ENUM_API

#define SPA_KEY_DEVICE_ENUM_API "device.enum.api"

the api used to discover this device

## ◆ SPA_KEY_DEVICE_API

#define SPA_KEY_DEVICE_API "device.api"

the api used by the device Ex.

"udev", "alsa", "v4l2".

## ◆ SPA_KEY_DEVICE_NAME

#define SPA_KEY_DEVICE_NAME "device.name"

the name of the device

## ◆ SPA_KEY_DEVICE_ALIAS

#define SPA_KEY_DEVICE_ALIAS "device.alias"

alternative name of the device

## ◆ SPA_KEY_DEVICE_NICK

#define SPA_KEY_DEVICE_NICK "device.nick"

the device short name

## ◆ SPA_KEY_DEVICE_DESCRIPTION

#define SPA_KEY_DEVICE_DESCRIPTION "device.description"

a device description

## ◆ SPA_KEY_DEVICE_ICON

#define SPA_KEY_DEVICE_ICON "device.icon"

icon for the device.

A base64 blob containing PNG image data

## ◆ SPA_KEY_DEVICE_ICON_NAME

#define SPA_KEY_DEVICE_ICON_NAME "device.icon-name"

an XDG icon name for the device.

Ex. "sound-card-speakers-usb"

## ◆ SPA_KEY_DEVICE_PLUGGED_USEC

#define SPA_KEY_DEVICE_PLUGGED_USEC "device.plugged.usec"

when the device was plugged

## ◆ SPA_KEY_DEVICE_BUS_ID

#define SPA_KEY_DEVICE_BUS_ID "device.bus-id"

the device bus-id

## ◆ SPA_KEY_DEVICE_BUS_PATH

#define SPA_KEY_DEVICE_BUS_PATH "device.bus-path"

bus path to the device in the OS' format.

Ex. "pci-0000:00:14.0-usb-0:3.2:1.0"

## ◆ SPA_KEY_DEVICE_BUS

#define SPA_KEY_DEVICE_BUS "device.bus"

bus of the device if applicable.

One of "isa", "pci", "usb", "firewire", "bluetooth"

## ◆ SPA_KEY_DEVICE_SUBSYSTEM

#define SPA_KEY_DEVICE_SUBSYSTEM "device.subsystem"

device subsystem

## ◆ SPA_KEY_DEVICE_SYSFS_PATH

#define SPA_KEY_DEVICE_SYSFS_PATH "device.sysfs.path"

device sysfs path

## ◆ SPA_KEY_DEVICE_VENDOR_ID

#define SPA_KEY_DEVICE_VENDOR_ID "device.vendor.id"

vendor ID if applicable

## ◆ SPA_KEY_DEVICE_VENDOR_NAME

#define SPA_KEY_DEVICE_VENDOR_NAME "device.vendor.name"

vendor name if applicable

## ◆ SPA_KEY_DEVICE_PRODUCT_ID

#define SPA_KEY_DEVICE_PRODUCT_ID "device.product.id"

product ID if applicable

## ◆ SPA_KEY_DEVICE_PRODUCT_NAME

#define SPA_KEY_DEVICE_PRODUCT_NAME "device.product.name"

product name if applicable

## ◆ SPA_KEY_DEVICE_SERIAL

#define SPA_KEY_DEVICE_SERIAL "device.serial"

Serial number if applicable.

## ◆ SPA_KEY_DEVICE_CLASS

#define SPA_KEY_DEVICE_CLASS "device.class"

device class

## ◆ SPA_KEY_DEVICE_CAPABILITIES

#define SPA_KEY_DEVICE_CAPABILITIES "device.capabilities"

api specific device capabilities

## ◆ SPA_KEY_DEVICE_FORM_FACTOR

#define SPA_KEY_DEVICE_FORM_FACTOR "device.form-factor"

form factor if applicable.

One of "internal", "speaker", "handset", "tv", "webcam", "microphone", "headset", "headphone", "hands-free", "car", "hifi", "computer", "portable"

## ◆ SPA_KEY_DEVICE_PROFILE

#define SPA_KEY_DEVICE_PROFILE "device.profile "

profile for the device

## ◆ SPA_KEY_DEVICE_PROFILE_SET

#define SPA_KEY_DEVICE_PROFILE_SET "device.profile-set"

profile set for the device

## ◆ SPA_KEY_DEVICE_STRING

#define SPA_KEY_DEVICE_STRING "device.string"

device string in the underlying layer's format.

E.g. "surround51:0"

## ◆ SPA_DEVICE_EVENT_ID

#define SPA_DEVICE_EVENT_ID | ( |  | ev | ) | SPA_EVENT_ID(ev, SPA_TYPE_EVENT_Device)

## ◆ SPA_DEVICE_EVENT_INIT

#define SPA_DEVICE_EVENT_INIT | ( |  | id | ) | SPA_EVENT_INIT(SPA_TYPE_EVENT_Device, id)

## ◆ SPA_TYPE_INFO_DeviceEvent

#define SPA_TYPE_INFO_DeviceEvent SPA_TYPE_INFO_EVENT_BASE "Device"

## ◆ SPA_TYPE_INFO_DEVICE_EVENT_BASE

#define SPA_TYPE_INFO_DEVICE_EVENT_BASE SPA_TYPE_INFO_DeviceEvent ":"

## ◆ SPA_TYPE_INFO_DeviceEventId

#define SPA_TYPE_INFO_DeviceEventId SPA_TYPE_INFO_ENUM_BASE "DeviceEventId"

## ◆ SPA_TYPE_INFO_DEVICE_EVENT_ID_BASE

#define SPA_TYPE_INFO_DEVICE_EVENT_ID_BASE SPA_TYPE_INFO_DeviceEventId ":"

## ◆ spa_device_emit

#define spa_device_emit | ( |  | hooks,
|  |  | method,
|  |  | version,
|  |  | ...
| ) |  |

## ◆ spa_device_emit_info

#define spa_device_emit_info | ( |  | hooks,
|  |  | i
| ) |  | spa_device_emit(hooks,info, 0, i)

## ◆ spa_device_emit_result

#define spa_device_emit_result | ( |  | hooks,
|  |  | s,
|  |  | r,
|  |  | t,
|  |  | res
| ) |  | spa_device_emit(hooks,result, 0, s, r, t, res)

## ◆ spa_device_emit_event

#define spa_device_emit_event | ( |  | hooks,
|  |  | e
| ) |  | spa_device_emit(hooks,event, 0, e)

## ◆ spa_device_emit_object_info

#define spa_device_emit_object_info | ( |  | hooks,
|  |  | id,
|  |  | i
| ) |  | spa_device_emit(hooks,object_info, 0, id, i)

## Enumeration Type Documentation

## ◆ spa_device_event

enum spa_device_event

Enumerator
SPA_DEVICE_EVENT_ObjectConfig |

## ◆ spa_event_device

enum spa_event_device

Enumerator
SPA_EVENT_DEVICE_START |
SPA_EVENT_DEVICE_Object |
SPA_EVENT_DEVICE_Props |

## Function Documentation

## ◆ spa_result_func_device_params()

static void spa_result_func_device_params | ( | void * | data,
|  | int | seq,
|  | int | res,
|  | uint32_t | type,
|  | const void * | result
| ) |  |
| inlinestatic

## ◆ spa_device_enum_params_sync()

static int spa_device_enum_params_sync | ( | struct spa_device * | device,
|  | uint32_t | id,
|  | uint32_t * | index,
|  | const struct spa_pod * | filter,
|  | struct spa_pod ** | param,
|  | struct spa_pod_builder * | builder
| ) |  |
| inlinestatic

## Variable Documentation

## ◆ spa_type_device_event_id

const struct spa_type_info spa_type_device_event_id[]
| static

## ◆ spa_type_device_event

const struct spa_type_info spa_type_device_event[]
| static