PipeWire  0.3.58
Device

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"

◆ 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
objecta Device
listenera listener
eventsa struct spa_device_events
datadata 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
seqa 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
devicea Device
seqa sequence number to pass to the result function
idthe param id to enumerate
indexthe index of enumeration, pass 0 for the first item.
maxthe maximum number of items to iterate
filterand 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
objectDevice
idthe parameter id to configure
flagsadditional flags
paramthe 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,
 
)    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,
 
)    spa_device_emit(hooks,event, 0, e)

◆ spa_device_emit_object_info

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

Enumeration Type Documentation

◆ spa_device_event

Enumerator
SPA_DEVICE_EVENT_ObjectConfig 

◆ 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