mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-10-29 05:40:27 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
pipewire/doc/pipewire-protocol.dox
Wim Taymans d7315ee572 docs: add more docs
2023-05-16 12:42:36 +02:00

994 lines
21 KiB
Text
Raw Blame History

/** \page page_native_protocol Native Protocol
PipeWire has a pluggable client/server IPC protocol.
The reference implementation uses unix sockets and is implemented in
\ref page_module_protocol_native.
We document the messages here.
# Message header
Each message on the unix socket contains a 16 bytes header and a
variable length payload size:
```
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Id |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| opcode | size |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| seq |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_fds |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| payload POD |
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| optional footer POD |
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
These are four uint32 words to be read in native endianness.
Id: the message id this is the destination resource/proxy id
opcode: the opcode on the resource/proxy interface
size: the size of the payload and optional footer of the message
seq: an increasing sequence number for each message
n_fds: number of file descriptors in this message.
The sender should send along with each message the fds that belong to
the message. If there are more than the maximum number of fds in the
message than can fit in one message, the message is split into multiple
parts.
The payload is a single POD see \ref page_spa_pod for details.
After the payload, there is an optional footer POD object.
# Making a connection
# Core proxy/resource
The core is always the object with Id 0.
## Core Methods (Id 0)
### Hello (Opcode 1)
The first message sent by a client is the Hello message and contains the
version number of the client.
```
Struct(
Int: version
)
```
The version is 3.
### Sync (Opcode 2)
The Sync message will result in a Done event from the server. When the Done
event is received, the client can be sure that all operations before the Sync
method have been completed.
```
Struct(
Int: id
Int: seq
)
```
id: the id will be returned in the Done event.
seq: is usually generated automatically and will be returned in the Done event.
### Pong (Opcode 3)
Is sent from the client to the server when the server emits the Ping event.
The id and seq should be copied from the Ping event.
```
Struct(
Int: id
Int: seq
)
```
### Error (Opcode 4)
An error occured in an object on the client.
```
Struct(
Int: id
Int: seq
Int: res
String: message
)
```
id: The id of the proxy that is in error.
seq: a seq number from the failing request (if any)
res: a negative errno style error code
message: an error message
### GetRegistry (Opcode 5)
A client requests to bind to the registry object and list the available objects
on the server.
Like with all bindings, first the client allocates a new proxy id and puts this
as the new_id field. Methods and Events can then be sent and received on the
new_id (in the message Id field).
```
Struct(
Int: version
Int: new_id
)
```
version: the version of the registry interface used on the client
new_id: the id of the new proxy with the registry interface
### CreateObject (Opcode 6)
Create a new object from a factory of a certain type.
The client allocates a new_id for the proxy. The server will allocate a new
resource with the same new_id and from then on, Methods and Events will be
exchanged between the new object of the given type.
```
Struct(
String: factory_name
String: type
Int: version
Struct(
Int: n_items
(String: key
String: value)*
): props
Int: new_id
)
```
factory_name: the name of a server factory object to use
type: the type of the object to create, this is also the type of the
interface of the new_id proxy.
props: extra properties to create the object
new_id: the proxy id of the new object
### Destroy (Opcode 7)
Destroy an object.
```
Struct(
Int: id
)
```
id: the proxy id of the object to destroy.
## Core Events
Core events are emited by the server.
### Info (Opcode 0)
Emited by the server upon connection with the more information about the
server.
```
Struct(
Int: id
Int: cookie
String: user_name
String: host_name
String: version
String: name
Long: change_mask
Struct(
Int: n_items
(String: key
String: value)*
): props
)
```
id: the id of the server (0)
cookie: a unique cookie for this server
user_name: the name of the user running the server
host_name: the name of the host running the server
version: a version string of the server
name: the name of the server
change_mask: a set of bits with changes to the info
- 1<<0: Properties changed
props: optional key/value properties
### Done (Opcode 1)
Emited as a result of a client Sync method.
```
Struct(
Int: id
Int: seq
)
```
id and seq are passed from the client Sync request.
### Ping (Opcode 2)
Emited by the server when it wants to check if a client is alive or ensure
that it has processed the previous events.
```
Struct(
Int: id
Int: seq
)
```
id: the object id to ping
seq: usually automatically generated. The client should pass this in the Pong
method reply.
### Error (Opcode 3)
The error event is sent out when a fatal (non-recoverable)
error has occurred. The id argument is the proxy object where
the error occurred, most often in response to a request to that
object. The message is a brief description of the error,
for (debugging) convenience.
```
Struct(
Int: id
Int: seq
Int: res
String: message
)
```
id: The id of the resource that is in error.
seq: a seq number from the failing request (if any)
res: a negative errno style error code
message: an error message
### RemoveId (Opcode 4)
This event is used internally by the object ID management
logic. When a client deletes an object, the server will send
this event to acknowledge that it has seen the delete request.
When the client receives this event, it will know that it can
safely reuse the object ID.
```
Struct(
Int: id
)
```
### BoundId (Opcode 5)
This event is emitted when a local object ID is bound to a
global ID. It is emitted before the global becomes visible in the
registry. This event is deprecated, the BoundProps event should
be used because it also contains extra properties.
```
Struct(
Int: id
Int: global_id
)
```
id: a proxy id
global_id: the global_id as it will appear in the registry.
### AddMem (Opcode 6)
Memory is given to a client as fd of a certain memory type.
Further references to this fd will be made with the per memory
unique identifier id.
```
Struct(
Int: id
Id: type
Fd: fd
Int: flags
)
```
id: a server allocated id for this memory
type: the memory type, see enum spa_data_type
fd: the index of the fd sent with this message
flags: extra flags
### RemoveMem (Opcode 7)
Remove memory for a client with the given id
```
Struct(
Int: id
)
```
id: the id of the memory to remove. This is the Id from
AddMem.
### BoundProps (Opcode 8)
This event is emitted when a local object ID is bound to a
global ID. It is emitted before the global becomes visible in the
registry.
```
Struct(
Int: id
Int: global_id
Struct(
Int: n_items
(String: key
String: value)*
): props
)
```
id: a proxy id
global_id: the global_id as it will appear in the registry.
props: the properties of the global
# Registry proxy/resource
The registry is obtained with the GetRegistry method on the Core object.
The Id depends on the new_id that was provided.
## Registry Methods
### Bind (Opcode 1)
Bind to the global object with id and use the client proxy
with new_id as the proxy. After this call, methods can be
send to the remote global object and events can be received.
```
Struct(
Int: id
String: type
Int: version
Int: new_id
)
```
id: the global_id to bind to
type: the type of the global id
version: the client version of the interface for type
new_id: the client proxy id for the global object
### Destroy (Opcode 2)
Try to destroy the global object with id. This might fail when the
client does not have permission.
```
Struct(
Int: id
)
```
id: the global id to destroy.
## Registry Events
### Global (Opcode 0)
Notify a client about a new global object.
```
Struct(
Int: id
Int: permissions
String: type
Int: version
Struct(
Int: n_items
(String: key
String: value)*
): props
)
```
id: the global id
permissions: permission bits
type: the type of object
version: the server version of the object
props: extra global properties
### GlobalRemove (Opcode 1)
A global with id was removed
```
Struct(
Int: id
)
```
id: the global id that was removed.
# PipeWire:Interface:Client
The client object represents a client connect to the PipeWire server.
Permissions of the client can be managed.
The currently connected client always has the Client object with
proxy id 1.
## Client Methods
### Error (Opcode 1)
Is used to send an error to a client.
```
Struct(
Int: id
Int: res
String: error
)
```
id: a client proxy id to send the error to
res: a negative errno style error code
error: an error message
### UpdateProperties (Opcode 2)
Is used to update the properties of a client.
```
Struct(
Struct(
Int: n_items
(String: key
String: value)*
): props
)
```
props: properties to update on the client.
### GetPermissions (Opcode 3)
Get the currently configured permissions on the client.
```
Struct(
Int: index
Int: num
)
```
index: the start index of the permissions to get
num: the number of permissions to get
This method will result in at most num Permission Events.
### UpdatePermissions (Opcode 4)
Update the permissions of the global objects using the
provided array with permissions
```
Struct(
Int: n_permissions
( Int: id
Int: permission
)*
)
```
n_permissions: number of permissions
id: the global id
permissions: the permissions for the global id
## Client Events
### Info (Opcode 0)
Get client information updates. This is emitted when binding to a client or
when the client info is updated later.
```
Struct(
Int: id
Long: change_mask
Struct(
Int: n_items
(String: key
String: value)*
): props
)
```
id: the global id of the client
change_mask: the changes emitted by this event
- Props (1<<0) property changes
props: properties of this object.
### Permissions (Opcode 1)
Emitted as the reply of the GetPermissions method.
```
Struct(
Int: index
Struct(
Int: n_permissions
(Int: id
Int: permission)*
)
)
```
index: index of the first permission
n_permissions: the number of permission entries
id: the global id of the object
permissions: the permission for the given id
# PipeWire:Interface:Device
A device is an object that manages other devices or nodes.
The usual flow is to bind to the Device object. This will result in an
Info event. From the Info event one can find the available params to
enumerate.
## Device methods
### SubscribeParams (Opcode 1)
Automatically emit Param events for the given ids when they are changed.
```
Struct(
Array[Id]: ids
)
```
ids: and array of param Id to subscribe to
### EnumParams (Opcode 2)
Enumerate the values of a param. This will result in Param events.
```
Struct(
Int: seq
Id: id
Int: index
Int: num
Pod: filter
)
```
seq: an automatically generated sequence number, will be copied into the reply
id: the param id to enumerate.
index: the first param index to retrieve
num: the number of params to retrieve
filter: an optional filter object for the param.
### SetParam (Opcode 3)
Set a parameter on the Device.
```
Struct(
Id: id
Int: flags
Pod: param
)
```
id: the param id to set.
flags: extra flags
param: the param object to set
## Device events
### Info (Opcode 0)
The info event is emitted when binding or when the device information changed.
```
Struct(
Int: id
Long: change_mask
Struct(
Int: n_items
( String: key
String: value )*
): props
Struct(
Int: n_params
( Int: id
Int: flags )*
): param_info
)
```
id: the id of the global
change_mask: a bitmask of changed fields
props: extra properties, valid when change_mask is (1<<0)
param_info: info about the parameters, valid when change_mask is (1<<1)
For each parameter, the id and current flags are given.
param_info.id : see enum spa_param_type
param_info.flags: struct spa_param_info.flags
### Param (Opcode 1)
Emitted as a result of EnumParams or SubscribeParams.
```
Struct(
Int: seq
Id: id
Int: index
Int: next
Pod: param
)
```
seq: the sequence number send by the client EnumParams or server generated
in the SubscribeParams case.
id: the param id that is reported, see enum spa_param_type
index: the index of the parameter
next: the index of the next parameter
param: the parameter. The object type depends on the id
# PipeWire:Interface:Factory
A factory is an object that allows one to create new objects.
## Factory methods
A factory has no methods
## Factory events
### Info (Opcode 0)
Info is emitted when binding to the factory global or when the information changed.
```
Struct(
Int: id
String: name
String: type
Int: version
Long: change_mask
Struct(
Int: n_items
( String: key
String: value )*
): props
)
```
id: the global id of the factory
name: the name of the factory. This can be used as the name for Core::CreateObject
type: the object type produced by this factory
version: the version of the object interface
change_mask: bitfield of changed values.
props: optional properties of the factory, valid when change_mask is (1<<0)
# PipeWire:Interface:Link
A link is a connection between 2 ports.
## Link methods
A link has no methods
## Link events
### Info (Opcode 0)
Info is emitted when binding to the link global or when the information changed.
```
Struct(
Int: id
Int: output_node_id
Int: output_port_id
Int: input_node_id
Int: input_port_id
Long: change_mask
Int: state
String: error
Pod: format
Struct(
Int: n_items
( String: key
String: value )*
): props
)
```
id: the global id of the link
output_node_id: the global id of the output node
output_port_id: the global id of the output port
input_node_id: the global id of the input node
input_port_id: the global id of the input port
change_mask: bitfield of changed values.
state: the state of the link, valid when change_mask has (1<<0)
- see enum pw_link_state for values
error: an optional error string
format: an optional format for the link, valid when change_mask has (1<<1)
props: optional properties of the link, valid when change_mask is (1<<2)
# PipeWire:Interface:Module
A Module provides dynamically loaded functionality
## Module methods
A module has no methods
## Module events
### Info (Opcode 0)
Info is emitted when binding to the module global or when the information changed.
```
Struct(
Int: id
String: name
String: filename
String: args
Long: change_mask
Struct(
Int: n_items
( String: key
String: value )*
): props
)
```
id: the global id of the module
name: the name of the module
filename: the filename of the module
args: arguments passed when loading the module
change_mask: bitfield of changed values.
props: optional properties of the module, valid when change_mask has (1<<0)
# PipeWire:Interface:Node
A Node is a processing element in the graph
## Node methods
### SubscribeParams (Opcode 1)
Automatically emit Param events for the given ids when they are changed.
```
Struct(
Array[Id]: ids
)
```
ids: and array of param Id to subscribe to
### EnumParams (Opcode 2)
Enumerate the values of a param. This will result in Param events.
```
Struct(
Int: seq
Id: id
Int: index
Int: num
Pod: filter
)
```
seq: an automatically generated sequence number, will be copied into the reply
id: the param id to enumerate.
index: the first param index to retrieve
num: the number of params to retrieve
filter: an optional filter object for the param.
### SetParam (Opcode 3)
Set a parameter on the Node.
```
Struct(
Id: id
Int: flags
Pod: param
)
```
id: the param id to set.
flags: extra flags
param: the param object to set
### SendCommand (Opcode 4)
Send a Command to the node.
```
Struct(
Pod: command
)
```
command: the command to send. See enum spa_node_command
## Node events
### Info (Opcode 0)
The info event is emitted when binding or when the node information changed.
```
Struct(
Int: id
Int: max_input_ports
Int: max_output_ports
Long: change_mask
Int: n_input_ports
Int: n_output_ports
Id: state
String: error
Struct(
Int: n_items
( String: key
String: value )*
): props
Struct(
Int: n_params
( Int: id
Int: flags )*
): param_info
)
```
id: the id of the node global
max_input_port: the maximum input ports for the node
max_output_port: the maximum output ports for the node
change_mask: a bitmask of changed fields
n_input_port: the number of input ports, when change_mask has (1<<0)
n_output_port: the number of output ports, when change_mask has (1<<1)
state: the current node state, when change_mask has (1<<2)
See enum pw_node_state for values
error: an error message.
props: extra properties, valid when change_mask is (1<<3)
param_info: info about the parameters, valid when change_mask is (1<<4)
For each parameter, the id and current flags are given.
param_info.id : see enum spa_param_type
param_info.flags: struct spa_param_info.flags
### Param (Opcode 1)
Emitted as a result of EnumParams or SubscribeParams.
```
Struct(
Int: seq
Id: id
Int: index
Int: next
Pod: param
)
```
seq: the sequence number send by the client EnumParams or server generated
in the SubscribeParams case.
id: the param id that is reported, see enum spa_param_type
index: the index of the parameter
next: the index of the next parameter
param: the parameter. The object type depends on the id
# PipeWire:Interface:Port
A port is part of a node and allows links with other ports.
## Port methods
### SubscribeParams (Opcode 1)
Automatically emit Param events for the given ids when they are changed.
```
Struct(
Array[Id]: ids
)
```
ids: and array of param Id to subscribe to
### EnumParams (Opcode 2)
Enumerate the values of a param. This will result in Param events.
```
Struct(
Int: seq
Id: id
Int: index
Int: num
Pod: filter
)
```
seq: an automatically generated sequence number, will be copied into the reply
id: the param id to enumerate.
index: the first param index to retrieve
num: the number of params to retrieve
filter: an optional filter object for the param.
## Port events
### Info (Opcode 0)
The info event is emitted when binding or when the port information changed.
```
Struct(
Int: id
Int: direction
Long: change_mask
Struct(
Int: n_items
( String: key
String: value )*
): props
Struct(
Int: n_params
( Int: id
Int: flags )*
): param_info
)
```
id: the id of the port global
direction: the direction of the port, see enum pw_direction
change_mask: a bitmask of changed fields
props: extra properties, valid when change_mask is (1<<0)
param_info: info about the parameters, valid when change_mask is (1<<1)
For each parameter, the id and current flags are given.
param_info.id : see enum spa_param_type
param_info.flags: struct spa_param_info.flags
### Param (Opcode 1)
Emitted as a result of EnumParams or SubscribeParams.
```
Struct(
Int: seq
Id: id
Int: index
Int: next
Pod: param
)
```
seq: the sequence number send by the client EnumParams or server generated
in the SubscribeParams case.
id: the param id that is reported, see enum spa_param_type
index: the index of the parameter
next: the index of the next parameter
*/
Reference in a new issue View git blame Copy permalink