mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-12-15 08:56:38 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: improve formatting

Browse source
This commit is contained in:
Wim Taymans 2023-05-16 12:50:18 +02:00
parent d7315ee572
commit b5224a6844
1 changed files with 159 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

319
doc/pipewire-protocol.dox
View file

@ -35,11 +35,11 @@ variable length payload size:
These are four uint32 words to be read in native endianness. These are four uint32 words to be read in native endianness.
Id: the message id this is the destination resource/proxy id - Id: the message id this is the destination resource/proxy id
opcode: the opcode on the resource/proxy interface - opcode: the opcode on the resource/proxy interface
size: the size of the payload and optional footer of the message - size: the size of the payload and optional footer of the message
seq: an increasing sequence number for each message - seq: an increasing sequence number for each message
n_fds: number of file descriptors in this message. - n_fds: number of file descriptors in this message.
The sender should send along with each message the fds that belong to 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 the message. If there are more than the maximum number of fds in the
@ -87,8 +87,8 @@ method have been completed.
) )
``` ```
id: the id will be returned in the Done event. - id: the id will be returned in the Done event.
seq: is usually generated automatically and will be returned in the Done event. - seq: is usually generated automatically and will be returned in the Done event.
### Pong (Opcode 3) ### Pong (Opcode 3)
@ -115,10 +115,10 @@ An error occured in an object on the client.
) )
``` ```
id: The id of the proxy that is in error. - id: The id of the proxy that is in error.
seq: a seq number from the failing request (if any) - seq: a seq number from the failing request (if any)
res: a negative errno style error code - res: a negative errno style error code
message: an error message - message: an error message
### GetRegistry (Opcode 5) ### GetRegistry (Opcode 5)
@ -136,8 +136,8 @@ new_id (in the message Id field).
) )
``` ```
version: the version of the registry interface used on the client - version: the version of the registry interface used on the client
new_id: the id of the new proxy with the registry interface - new_id: the id of the new proxy with the registry interface
### CreateObject (Opcode 6) ### CreateObject (Opcode 6)
@ -161,11 +161,11 @@ exchanged between the new object of the given type.
) )
``` ```
factory_name: the name of a server factory object to use - 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 - type: the type of the object to create, this is also the type of the
interface of the new_id proxy. interface of the new_id proxy.
props: extra properties to create the object - props: extra properties to create the object
new_id: the proxy id of the new object - new_id: the proxy id of the new object
### Destroy (Opcode 7) ### Destroy (Opcode 7)
@ -177,7 +177,7 @@ Destroy an object.
) )
``` ```
id: the proxy id of the object to destroy. - id: the proxy id of the object to destroy.
## Core Events ## Core Events
@ -205,15 +205,14 @@ server.
) )
``` ```
id: the id of the server (0) - id: the id of the server (0)
cookie: a unique cookie for this server - cookie: a unique cookie for this server
user_name: the name of the user running the server - user_name: the name of the user running the server
host_name: the name of the host running the server - host_name: the name of the host running the server
version: a version string of the server - version: a version string of the server
name: the name of the server - name: the name of the server
change_mask: a set of bits with changes to the info - change_mask: a set of bits with changes to the info
- 1<<0: Properties changed - props: optional key/value properties, valid when change_mask has (1<<0)
props: optional key/value properties
### Done (Opcode 1) ### Done (Opcode 1)
@ -240,9 +239,9 @@ that it has processed the previous events.
) )
``` ```
id: the object id to ping - id: the object id to ping
seq: usually automatically generated. The client should pass this in the Pong - seq: usually automatically generated. The client should pass this in the Pong
method reply. method reply.
### Error (Opcode 3) ### Error (Opcode 3)
@ -261,10 +260,10 @@ for (debugging) convenience.
) )
``` ```
id: The id of the resource that is in error. - id: The id of the resource that is in error.
seq: a seq number from the failing request (if any) - seq: a seq number from the failing request (if any)
res: a negative errno style error code - res: a negative errno style error code
message: an error message - message: an error message
### RemoveId (Opcode 4) ### RemoveId (Opcode 4)
@ -281,6 +280,8 @@ safely reuse the object ID.
) )
``` ```
- id: a proxy id that was removed
### BoundId (Opcode 5) ### BoundId (Opcode 5)
This event is emitted when a local object ID is bound to a This event is emitted when a local object ID is bound to a
@ -295,8 +296,8 @@ be used because it also contains extra properties.
) )
``` ```
id: a proxy id - id: a proxy id
global_id: the global_id as it will appear in the registry. - global_id: the global_id as it will appear in the registry.
### AddMem (Opcode 6) ### AddMem (Opcode 6)
@ -313,10 +314,10 @@ unique identifier id.
) )
``` ```
id: a server allocated id for this memory - id: a server allocated id for this memory
type: the memory type, see enum spa_data_type - type: the memory type, see enum spa_data_type
fd: the index of the fd sent with this message - fd: the index of the fd sent with this message
flags: extra flags - flags: extra flags
### RemoveMem (Opcode 7) ### RemoveMem (Opcode 7)
@ -328,8 +329,7 @@ Remove memory for a client with the given id
) )
``` ```
id: the id of the memory to remove. This is the Id from - id: the id of the memory to remove. This is the Id from AddMem.
AddMem.
### BoundProps (Opcode 8) ### BoundProps (Opcode 8)
@ -349,9 +349,9 @@ registry.
) )
``` ```
id: a proxy id - id: a proxy id
global_id: the global_id as it will appear in the registry. - global_id: the global_id as it will appear in the registry.
props: the properties of the global - props: the properties of the global
# Registry proxy/resource # Registry proxy/resource
@ -375,10 +375,10 @@ send to the remote global object and events can be received.
) )
``` ```
id: the global_id to bind to - id: the global_id to bind to
type: the type of the global id - type: the type of the global id
version: the client version of the interface for type - version: the client version of the interface for type
new_id: the client proxy id for the global object - new_id: the client proxy id for the global object
### Destroy (Opcode 2) ### Destroy (Opcode 2)
@ -391,7 +391,7 @@ client does not have permission.
) )
``` ```
id: the global id to destroy. - id: the global id to destroy.
## Registry Events ## Registry Events
@ -413,11 +413,11 @@ Notify a client about a new global object.
) )
``` ```
id: the global id - id: the global id
permissions: permission bits - permissions: permission bits
type: the type of object - type: the type of object
version: the server version of the object - version: the server version of the object
props: extra global properties - props: extra global properties
### GlobalRemove (Opcode 1) ### GlobalRemove (Opcode 1)
@ -429,7 +429,7 @@ A global with id was removed
) )
``` ```
id: the global id that was removed. - id: the global id that was removed.
# PipeWire:Interface:Client # PipeWire:Interface:Client
@ -453,9 +453,9 @@ Is used to send an error to a client.
) )
``` ```
id: a client proxy id to send the error to - id: a client proxy id to send the error to
res: a negative errno style error code - res: a negative errno style error code
error: an error message - error: an error message
### UpdateProperties (Opcode 2) ### UpdateProperties (Opcode 2)
@ -470,7 +470,7 @@ Is used to update the properties of a client.
): props ): props
) )
``` ```
props: properties to update on the client. - props: properties to update on the client.
### GetPermissions (Opcode 3) ### GetPermissions (Opcode 3)
@ -482,8 +482,8 @@ Get the currently configured permissions on the client.
Int: num Int: num
) )
``` ```
index: the start index of the permissions to get - index: the start index of the permissions to get
num: the number of permissions to get - num: the number of permissions to get
This method will result in at most num Permission Events. This method will result in at most num Permission Events.
@ -502,9 +502,9 @@ provided array with permissions
) )
``` ```
n_permissions: number of permissions - n_permissions: number of permissions
id: the global id - id: the global id
permissions: the permissions for the global id - permissions: the permissions for the global id
## Client Events ## Client Events
@ -524,10 +524,9 @@ when the client info is updated later.
): props ): props
) )
``` ```
id: the global id of the client - id: the global id of the client
change_mask: the changes emitted by this event - change_mask: the changes emitted by this event
- Props (1<<0) property changes - props: properties of this object, valid when change_mask has (1<<0)
props: properties of this object.
### Permissions (Opcode 1) ### Permissions (Opcode 1)
@ -543,10 +542,10 @@ Emitted as the reply of the GetPermissions method.
) )
) )
``` ```
index: index of the first permission - index: index of the first permission
n_permissions: the number of permission entries - n_permissions: the number of permission entries
id: the global id of the object - id: the global id of the object
permissions: the permission for the given id - permissions: the permission for the given id
# PipeWire:Interface:Device # PipeWire:Interface:Device
@ -567,7 +566,7 @@ Automatically emit Param events for the given ids when they are changed.
Array[Id]: ids Array[Id]: ids
) )
``` ```
ids: and array of param Id to subscribe to - ids: and array of param Id to subscribe to
### EnumParams (Opcode 2) ### EnumParams (Opcode 2)
@ -582,11 +581,11 @@ Enumerate the values of a param. This will result in Param events.
Pod: filter Pod: filter
) )
``` ```
seq: an automatically generated sequence number, will be copied into the reply - seq: an automatically generated sequence number, will be copied into the reply
id: the param id to enumerate. - id: the param id to enumerate.
index: the first param index to retrieve - index: the first param index to retrieve
num: the number of params to retrieve - num: the number of params to retrieve
filter: an optional filter object for the param. - filter: an optional filter object for the param.
### SetParam (Opcode 3) ### SetParam (Opcode 3)
@ -599,9 +598,9 @@ Set a parameter on the Device.
Pod: param Pod: param
) )
``` ```
id: the param id to set. - id: the param id to set.
flags: extra flags - flags: extra flags
param: the param object to set - param: the param object to set
## Device events ## Device events
@ -626,13 +625,13 @@ The info event is emitted when binding or when the device information changed.
) )
``` ```
id: the id of the global - id: the id of the global
change_mask: a bitmask of changed fields - change_mask: a bitmask of changed fields
props: extra properties, valid when change_mask is (1<<0) - props: extra properties, valid when change_mask is (1<<0)
param_info: info about the parameters, valid when change_mask is (1<<1) - param_info: info about the parameters, valid when change_mask is (1<<1)
For each parameter, the id and current flags are given. For each parameter, the id and current flags are given.
param_info.id : see enum spa_param_type - param_info.id : see enum spa_param_type
param_info.flags: struct spa_param_info.flags - param_info.flags: struct spa_param_info.flags
### Param (Opcode 1) ### Param (Opcode 1)
@ -647,12 +646,12 @@ Emitted as a result of EnumParams or SubscribeParams.
Pod: param Pod: param
) )
``` ```
seq: the sequence number send by the client EnumParams or server generated - seq: the sequence number send by the client EnumParams or server generated
in the SubscribeParams case. in the SubscribeParams case.
id: the param id that is reported, see enum spa_param_type - id: the param id that is reported, see enum spa_param_type
index: the index of the parameter - index: the index of the parameter
next: the index of the next parameter - next: the index of the next parameter
param: the parameter. The object type depends on the id - param: the parameter. The object type depends on the id
# PipeWire:Interface:Factory # PipeWire:Interface:Factory
@ -683,12 +682,12 @@ Info is emitted when binding to the factory global or when the information chang
): props ): props
) )
``` ```
id: the global id of the factory - id: the global id of the factory
name: the name of the factory. This can be used as the name for Core::CreateObject - name: the name of the factory. This can be used as the name for Core::CreateObject
type: the object type produced by this factory - type: the object type produced by this factory
version: the version of the object interface - version: the version of the object interface
change_mask: bitfield of changed values. - change_mask: bitfield of changed values.
props: optional properties of the factory, valid when change_mask is (1<<0) - props: optional properties of the factory, valid when change_mask is (1<<0)
# PipeWire:Interface:Link # PipeWire:Interface:Link
@ -724,17 +723,17 @@ Info is emitted when binding to the link global or when the information changed.
) )
``` ```
id: the global id of the link - id: the global id of the link
output_node_id: the global id of the output node - output_node_id: the global id of the output node
output_port_id: the global id of the output port - output_port_id: the global id of the output port
input_node_id: the global id of the input node - input_node_id: the global id of the input node
input_port_id: the global id of the input port - input_port_id: the global id of the input port
change_mask: bitfield of changed values. - change_mask: bitfield of changed values.
state: the state of the link, valid when change_mask has (1<<0) - state: the state of the link, valid when change_mask has (1<<0)
- see enum pw_link_state for values - see enum pw_link_state for values
error: an optional error string - error: an optional error string
format: an optional format for the link, valid when change_mask has (1<<1) - 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) - props: optional properties of the link, valid when change_mask is (1<<2)
# PipeWire:Interface:Module # PipeWire:Interface:Module
@ -766,12 +765,12 @@ Info is emitted when binding to the module global or when the information change
) )
``` ```
id: the global id of the module - id: the global id of the module
name: the name of the module - name: the name of the module
filename: the filename of the module - filename: the filename of the module
args: arguments passed when loading the module - args: arguments passed when loading the module
change_mask: bitfield of changed values. - change_mask: bitfield of changed values.
props: optional properties of the module, valid when change_mask has (1<<0) - props: optional properties of the module, valid when change_mask has (1<<0)
# PipeWire:Interface:Node # PipeWire:Interface:Node
@ -789,7 +788,7 @@ Automatically emit Param events for the given ids when they are changed.
Array[Id]: ids Array[Id]: ids
) )
``` ```
ids: and array of param Id to subscribe to - ids: and array of param Id to subscribe to
### EnumParams (Opcode 2) ### EnumParams (Opcode 2)
@ -804,11 +803,11 @@ Enumerate the values of a param. This will result in Param events.
Pod: filter Pod: filter
) )
``` ```
seq: an automatically generated sequence number, will be copied into the reply - seq: an automatically generated sequence number, will be copied into the reply
id: the param id to enumerate. - id: the param id to enumerate.
index: the first param index to retrieve - index: the first param index to retrieve
num: the number of params to retrieve - num: the number of params to retrieve
filter: an optional filter object for the param. - filter: an optional filter object for the param.
### SetParam (Opcode 3) ### SetParam (Opcode 3)
@ -821,9 +820,9 @@ Set a parameter on the Node.
Pod: param Pod: param
) )
``` ```
id: the param id to set. - id: the param id to set.
flags: extra flags - flags: extra flags
param: the param object to set - param: the param object to set
### SendCommand (Opcode 4) ### SendCommand (Opcode 4)
@ -834,7 +833,7 @@ Send a Command to the node.
Pod: command Pod: command
) )
``` ```
command: the command to send. See enum spa_node_command - command: the command to send. See enum spa_node_command
## Node events ## Node events
@ -865,20 +864,20 @@ The info event is emitted when binding or when the node information changed.
) )
``` ```
id: the id of the node global - id: the id of the node global
max_input_port: the maximum input ports for the node - max_input_port: the maximum input ports for the node
max_output_port: the maximum output ports for the node - max_output_port: the maximum output ports for the node
change_mask: a bitmask of changed fields - change_mask: a bitmask of changed fields
n_input_port: the number of input ports, when change_mask has (1<<0) - 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) - 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) - state: the current node state, when change_mask has (1<<2)
See enum pw_node_state for values - See enum pw_node_state for values
error: an error message. - error: an error message.
props: extra properties, valid when change_mask is (1<<3) - props: extra properties, valid when change_mask is (1<<3)
param_info: info about the parameters, valid when change_mask is (1<<4) - param_info: info about the parameters, valid when change_mask is (1<<4)
For each parameter, the id and current flags are given. For each parameter, the id and current flags are given.
param_info.id : see enum spa_param_type - param_info.id : see enum spa_param_type
param_info.flags: struct spa_param_info.flags - param_info.flags: struct spa_param_info.flags
### Param (Opcode 1) ### Param (Opcode 1)
@ -893,12 +892,12 @@ Emitted as a result of EnumParams or SubscribeParams.
Pod: param Pod: param
) )
``` ```
seq: the sequence number send by the client EnumParams or server generated - seq: the sequence number send by the client EnumParams or server generated
in the SubscribeParams case. in the SubscribeParams case.
id: the param id that is reported, see enum spa_param_type - id: the param id that is reported, see enum spa_param_type
index: the index of the parameter - index: the index of the parameter
next: the index of the next parameter - next: the index of the next parameter
param: the parameter. The object type depends on the id - param: the parameter. The object type depends on the id
# PipeWire:Interface:Port # PipeWire:Interface:Port
@ -916,7 +915,7 @@ Automatically emit Param events for the given ids when they are changed.
Array[Id]: ids Array[Id]: ids
) )
``` ```
ids: and array of param Id to subscribe to - ids: and array of param Id to subscribe to
### EnumParams (Opcode 2) ### EnumParams (Opcode 2)
@ -931,11 +930,11 @@ Enumerate the values of a param. This will result in Param events.
Pod: filter Pod: filter
) )
``` ```
seq: an automatically generated sequence number, will be copied into the reply - seq: an automatically generated sequence number, will be copied into the reply
id: the param id to enumerate. - id: the param id to enumerate.
index: the first param index to retrieve - index: the first param index to retrieve
num: the number of params to retrieve - num: the number of params to retrieve
filter: an optional filter object for the param. - filter: an optional filter object for the param.
## Port events ## Port events
@ -961,14 +960,14 @@ The info event is emitted when binding or when the port information changed.
) )
``` ```
id: the id of the port global - id: the id of the port global
direction: the direction of the port, see enum pw_direction - direction: the direction of the port, see enum pw_direction
change_mask: a bitmask of changed fields - change_mask: a bitmask of changed fields
props: extra properties, valid when change_mask is (1<<0) - props: extra properties, valid when change_mask is (1<<0)
param_info: info about the parameters, valid when change_mask is (1<<1) - param_info: info about the parameters, valid when change_mask is (1<<1)
For each parameter, the id and current flags are given. For each parameter, the id and current flags are given.
param_info.id : see enum spa_param_type - param_info.id : see enum spa_param_type
param_info.flags: struct spa_param_info.flags - param_info.flags: struct spa_param_info.flags
### Param (Opcode 1) ### Param (Opcode 1)
@ -983,11 +982,11 @@ Emitted as a result of EnumParams or SubscribeParams.
Pod: param Pod: param
) )
``` ```
seq: the sequence number send by the client EnumParams or server generated - seq: the sequence number send by the client EnumParams or server generated
in the SubscribeParams case. in the SubscribeParams case.
id: the param id that is reported, see enum spa_param_type - id: the param id that is reported, see enum spa_param_type
index: the index of the parameter - index: the index of the parameter
next: the index of the next parameter - next: the index of the next parameter