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

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 }

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()
#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
#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.
#define	spa_device_sync(d, ...)   spa_device_method(d, sync, 0, __VA_ARGS__)
	Perform a sync operation.
#define	spa_device_enum_params(d, ...)   spa_device_method(d, enum_params, 0, __VA_ARGS__)
	Enumerate the parameters of a device.
#define	spa_device_set_param(d, ...)   spa_device_method(d, set_param, 0, __VA_ARGS__)
	Set the configurable parameter in device.
#define	SPA_KEY_DEVICE_ENUM_API   "device.enum.api"
	the api used to discover this device
#define	SPA_KEY_DEVICE_API   "device.api"
	the api used by the device Ex.
#define	SPA_KEY_DEVICE_NAME   "device.name"
	the name of the device
#define	SPA_KEY_DEVICE_ALIAS   "device.alias"
	alternative name of the device
#define	SPA_KEY_DEVICE_NICK   "device.nick"
	the device short name
#define	SPA_KEY_DEVICE_DESCRIPTION   "device.description"
	a device description
#define	SPA_KEY_DEVICE_ICON   "device.icon"
	icon for the device.
#define	SPA_KEY_DEVICE_ICON_NAME   "device.icon-name"
	an XDG icon name for the device.
#define	SPA_KEY_DEVICE_PLUGGED_USEC   "device.plugged.usec"
	when the device was plugged
#define	SPA_KEY_DEVICE_BUS_ID   "device.bus-id"
	the device bus-id
#define	SPA_KEY_DEVICE_BUS_PATH   "device.bus-path"
	bus path to the device in the OS' format.
#define	SPA_KEY_DEVICE_BUS   "device.bus"
	bus of the device if applicable.
#define	SPA_KEY_DEVICE_SUBSYSTEM   "device.subsystem"
	device subsystem
#define	SPA_KEY_DEVICE_SYSFS_PATH   "device.sysfs.path"
	device sysfs path
#define	SPA_KEY_DEVICE_VENDOR_ID   "device.vendor.id"
	vendor ID if applicable
#define	SPA_KEY_DEVICE_VENDOR_NAME   "device.vendor.name"
	vendor name if applicable
#define	SPA_KEY_DEVICE_PRODUCT_ID   "device.product.id"
	product ID if applicable
#define	SPA_KEY_DEVICE_PRODUCT_NAME   "device.product.name"
	product name if applicable
#define	SPA_KEY_DEVICE_SERIAL   "device.serial"
	Serial number if applicable.
#define	SPA_KEY_DEVICE_CLASS   "device.class"
	device class
#define	SPA_KEY_DEVICE_CAPABILITIES   "device.capabilities"
	api specific device capabilities
#define	SPA_KEY_DEVICE_FORM_FACTOR   "device.form-factor"
	form factor if applicable.
#define	SPA_KEY_DEVICE_PROFILE   "device.profile "
	profile for the device
#define	SPA_KEY_DEVICE_PROFILE_SET   "device.profile-set"
	profile set for the device
#define	SPA_KEY_DEVICE_STRING   "device.string"
	device string in the underlying layer's format.
#define	SPA_KEY_DEVICE_DEVIDS   "device.devids"
	space separated list of device ids (dev_t) of the underlying device(s) if applicable
#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)

Functions
static void	spa_result_func_device_params (void *data, int seq, int res 1, 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.

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

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_KEY_DEVICE_DEVIDS

#define SPA_KEY_DEVICE_DEVIDS   "device.devids"

space separated list of device ids (dev_t) of the underlying device(s) if applicable

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)

Function Documentation

spa_result_func_device_params()

static void spa_result_func_device_params ( void *  data, int  seq, int res  1, 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