PipeWire: spa_node_methods Struct Reference

PipeWire 1.6.8

Loading...
Searching...
No Matches
spa_node_methods Struct Reference
SPA » Node

Node methods. More...

`#include <spa/node/node.h>`

## Data Fields
uint32_t | version
int(* | add_listener )(void *object, struct spa_hook *listener, const struct spa_node_events *events, void *data)
| Adds an event listener on node.
int(* | set_callbacks )(void *object, const struct spa_node_callbacks *callbacks, void *data)
| Set callbacks to on node.
int(* | sync )(void *object, int seq)
| Perform a sync operation.
int(* | enum_params )(void *object, int seq, uint32_t id, uint32_t start, uint32_t max, const struct spa_pod *filter)
| Enumerate the parameters of a node.
int(* | set_param )(void *object, uint32_t id, uint32_t flags, const struct spa_pod *param)
| Set the configurable parameter in node.
int(* | set_io )(void *object, uint32_t id, void *data, size_t size)
| Configure the given memory area with id on node.
int(* | send_command )(void *object, const struct spa_command *command)
| Send a command to a node.
int(* | add_port )(void *object, enum spa_direction direction, uint32_t port_id, const struct spa_dict *props)
| Make a new port with port_id.
int(* | remove_port )(void *object, enum spa_direction direction, uint32_t port_id)
| Remove a port with port_id.
int(* | port_enum_params )(void *object, int seq, enum spa_direction direction, uint32_t port_id, uint32_t id, uint32_t start, uint32_t max, const struct spa_pod *filter)
| Enumerate all possible parameters of id on port_id of node that are compatible with filter.
int(* | port_set_param )(void *object, enum spa_direction direction, uint32_t port_id, uint32_t id, uint32_t flags, const struct spa_pod *param)
| Set a parameter on port_id of node.
int(* | port_use_buffers )(void *object, enum spa_direction direction, uint32_t port_id, uint32_t flags, struct spa_buffer **buffers, uint32_t n_buffers)
| Tell the port to use the given buffers.
int(* | port_set_io )(void *object, enum spa_direction direction, uint32_t port_id, uint32_t id, void *data, size_t size)
| Configure the given memory area with id on port_id.
int(* | port_reuse_buffer )(void *object, uint32_t port_id, uint32_t buffer_id)
| Tell an output port to reuse a buffer.
int(* | process )(void *object)
| Process the node.

## Detailed Description

Node methods.

Examples
  export-sink.c, and export-source.c.

## Field Documentation

## ◆ version

uint32_t spa_node_methods::version

## ◆ add_listener

int(* spa_node_methods::add_listener) (void *object, struct spa_hook *listener, const struct spa_node_events *events, void *data)

Adds an event listener on node.

Setting the events will trigger the info event and a port_info event for each managed port on the new listener.

Parameters

  node | a spa_node
  listener | a listener
  events | a struct spa_node_events
  data | data passed as first argument in functions of events

Returns
  0 on success < 0 errno on error

## ◆ set_callbacks

int(* spa_node_methods::set_callbacks) (void *object, const struct spa_node_callbacks *callbacks, void *data)

Set callbacks to on node.

if callbacks is NULL, the current callbacks are removed.

This function must be called from the main thread.

All callbacks are called from the data thread.

Parameters

  node | a spa_node
  callbacks | callbacks to set

Returns
  0 on success -EINVAL when node is NULL

## ◆ sync

int(* spa_node_methods::sync) (void *object, int seq)

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 node, 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

## ◆ enum_params

int(* spa_node_methods::enum_params) (void *object, int seq, uint32_t id, uint32_t start, uint32_t max, const struct spa_pod *filter)

Enumerate the parameters of a node.

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 function will emit the result event up to max times with the result value. The seq in the result will either be the seq number when executed synchronously or the async return value of this function when executed asynchronously.

This function must be called from the main thread.

Parameters

  node | a Node
  seq | a sequence number to pass to the result event when this method is executed synchronously.
  id | the param id to enumerate
  start | the index of enumeration, pass 0 for the first item
  max | the maximum number of parameters to enumerate
  filter | and optional filter to use

Returns
  0 when no more items can be iterated. -EINVAL when invalid arguments are given -ENOENT the parameter id is unknown -ENOTSUP when there are no parameters implemented on node an async return value when the result event will be emitted later.

## ◆ set_param

int(* spa_node_methods::set_param) (void *object, uint32_t id, uint32_t flags, const struct spa_pod *param)

Set the configurable parameter in node.

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

  node | a Node
  id | the parameter id to configure
  flags | additional flags
  param | the parameter to configure

Returns
  0 on success -EINVAL when node is NULL -ENOTSUP when there are no parameters implemented on node -ENOENT the parameter is unknown

## ◆ set_io

int(* spa_node_methods::set_io) (void *object, uint32_t id, void *data, size_t size)

Configure the given memory area with id on node.

This structure is allocated by the host and is used to exchange data and parameters with the node.

Setting an io of NULL will disable the node io.

This function must be called from the main thread.

Parameters

  id | the id of the io area, the available ids can be enumerated with the node parameters.
  data | a io area memory
  size | the size of data

Returns
  0 on success -EINVAL when invalid input is given -ENOENT when id is unknown -ENOSPC when size is too small

## ◆ send_command

int(* spa_node_methods::send_command) (void *object, const struct spa_command *command)

Send a command to a node.

Upon completion, a command might change the state of a node.

This function must be called from the main thread.

Parameters

  node | a spa_node
  command | a spa_command

Returns
  0 on success -EINVAL when node or command is NULL -ENOTSUP when this node can't process commands -EINVAL command is an invalid command

## ◆ add_port

int(* spa_node_methods::add_port) (void *object, enum spa_direction direction, uint32_t port_id, const struct spa_dict *props)

Make a new port with port_id.

The caller should use the lowest unused port id for the given direction.

Port ids should be between 0 and max_ports as obtained from the info event.

This function must be called from the main thread.

Parameters

  node | a spa_node
  direction | a enum spa_direction
  port_id | an unused port id
  props | extra properties

Returns
  0 on success -EINVAL when node is NULL

## ◆ remove_port

int(* spa_node_methods::remove_port) (void *object, enum spa_direction direction, uint32_t port_id)

Remove a port with port_id.

Parameters

  node | a spa_node
  direction | a enum spa_direction
  port_id | a port id

Returns
  0 on success -EINVAL when node is NULL or when port_id is unknown or when the port can't be removed.

## ◆ port_enum_params

int(* spa_node_methods::port_enum_params) (void *object, int seq, enum spa_direction direction, uint32_t port_id, uint32_t id, uint32_t start, uint32_t max, const struct spa_pod *filter)

Enumerate all possible parameters of id on port_id of node that are compatible with filter.

When SPA_ID_INVALID is given as the port_id, the node will reply with the params that would be returned for a new port in the given direction.

The result parameters can be queried and modified and ultimately be used to call port_set_param.

The function will emit the result event up to max times with the result value. The seq in the result event will either be the seq number when executed synchronously or the async return value of this function when executed asynchronously.

This function must be called from the main thread.

Parameters

  node | a spa_node
  seq | a sequence number to pass to the result event when this method is executed synchronously.
  direction | an spa_direction
  port_id | the port to query or SPA_ID_INVALID
  id | the parameter id to query
  start | the first index to query, 0 to get the first item
  max | the maximum number of params to query
  filter | a parameter filter or NULL for no filter

Returns
  0 when no more items can be iterated. -EINVAL when invalid parameters are given -ENOENT when id is unknown an async return value when the result event will be emitted later.

## ◆ port_set_param

int(* spa_node_methods::port_set_param) (void *object, enum spa_direction direction, uint32_t port_id, uint32_t id, uint32_t flags, const struct spa_pod *param)

Set a parameter on port_id of node.

When param is NULL, the parameter will be unset.

This function must be called from the main thread. The node muse be paused or the port SPA_IO_Buffers area is NULL when this function is called with a param that changes the processing state (like a format change).

Parameters

  node | a struct Node
  direction | a enum spa_direction
  port_id | the port to configure
  id | the parameter id to set
  flags | optional flags
  param | a struct POD with the parameter to set

Returns
  0 on success 1 on success, the value of param might have been changed depending on flags and the final value can be found by doing port_enum_params. -EINVAL when node is NULL or invalid arguments are given -ESRCH when one of the mandatory param properties is not specified and SPA_NODE_PARAM_FLAG_FIXATE was not set in flags. -ESRCH when the type or size of a property is not correct. -ENOENT when the param id is not found

## ◆ port_use_buffers

int(* spa_node_methods::port_use_buffers) (void *object, enum spa_direction direction, uint32_t port_id, uint32_t flags, struct spa_buffer **buffers, uint32_t n_buffers)

Tell the port to use the given buffers.

When flags contains SPA_NODE_BUFFERS_FLAG_ALLOC, the data in the buffers should point to an array of at least 1 data entry with the desired supported type that will be filled by this function.

The port should also have a spa_io_buffers io area configured to exchange the buffers with the port.

For an input port, all the buffers will remain dequeued. Once a buffer has been queued on a port in the spa_io_buffers, it should not be reused until the reuse_buffer callback is notified or when the buffer has been returned in the spa_io_buffers of the port.

For output ports, all buffers will be queued in the port. When process returns SPA_STATUS_HAVE_DATA, buffers are available in one or more of the spa_io_buffers areas.

When a buffer can be reused, port_reuse_buffer() should be called or the buffer_id should be placed in the spa_io_buffers area before calling process.

Passing NULL as buffers will remove the reference that the port has on the buffers.

When this function returns async, use the spa_node_sync operation to wait for completion.

This function must be called from the main thread. The node muse be paused or the port SPA_IO_Buffers area is NULL when this function is called.

Parameters

  object | an object implementing the interface
  direction | a port direction
  port_id | a port id
  flags | extra flags
  buffers | an array of buffer pointers
  n_buffers | number of elements in buffers

Returns
  0 on success

## ◆ port_set_io

int(* spa_node_methods::port_set_io) (void *object, enum spa_direction direction, uint32_t port_id, uint32_t id, void *data, size_t size)

Configure the given memory area with id on port_id.

This structure is allocated by the host and is used to exchange data and parameters with the port.

Setting an io of NULL will disable the port io.

This function must be called from the main thread.

This function can be called when the node is running and the node must be prepared to handle changes in io areas while running. This is normally done by synchronizing the port io updates with the data processing loop.

Parameters

  direction | a spa_direction
  port_id | a port id
  id | the id of the io area, the available ids can be enumerated with the port parameters.
  data | a io area memory
  size | the size of data

Returns
  0 on success -EINVAL when invalid input is given -ENOENT when id is unknown -ENOSPC when size is too small

## ◆ port_reuse_buffer

int(* spa_node_methods::port_reuse_buffer) (void *object, uint32_t port_id, uint32_t buffer_id)

Tell an output port to reuse a buffer.

This function must be called from the data thread.

Parameters

  node | a spa_node
  port_id | a port id
  buffer_id | a buffer id to reuse

Returns
  0 on success -EINVAL when node is NULL

## ◆ process

int(* spa_node_methods::process) (void *object)

Process the node.

This function must be called from the data thread.

Output io areas with SPA_STATUS_NEED_DATA will recycle the buffers if any.

Input areas with SPA_STATUS_HAVE_DATA are consumed if possible and the status is set to SPA_STATUS_NEED_DATA or SPA_STATUS_OK.

When the node has new output buffers, the SPA_STATUS_HAVE_DATA bit will be set.

When the node can accept new input in the next cycle, the SPA_STATUS_NEED_DATA bit will be set.

Note that the node might return SPA_STATUS_NEED_DATA even when no input ports have this status. This means that the amount of data still available on the input ports is likely not going to be enough for the next cycle and the host might need to prefetch data for the next cycle.

The documentation for this struct was generated from the following file:

- spa/node/node.h