PipeWire 1.2.6

Loading...
Searching...
No Matches
Files | Data Structures | Macros | Functions
Core
Core API

## Files
file | core.h
| `pipewire/core.h`

## Data Structures
struct | pw_core_info
| The core information. More...
struct | pw_core_events
| Core events. More...
struct | pw_core_methods
| Core methods. More...
struct | pw_core
struct | pw_registry

## Macros
#define | PW_TYPE_INTERFACE_Core PW_TYPE_INFO_INTERFACE_BASE "Core"
#define | PW_TYPE_INTERFACE_Registry PW_TYPE_INFO_INTERFACE_BASE "Registry"
#define | PW_CORE_PERM_MASK PW_PERM_R|PW_PERM_X|PW_PERM_M
#define | PW_VERSION_CORE 4
#define | PW_VERSION_REGISTRY 3
#define | PW_DEFAULT_REMOTE "pipewire-0"
| The default remote name to connect to.
#define | PW_ID_CORE 0
| default ID for the core object after connect
#define | PW_ID_ANY (uint32_t)(0xffffffff)
#define | PW_CORE_CHANGE_MASK_PROPS (1 << 0)
#define | PW_CORE_CHANGE_MASK_ALL ((1 << 1)-1)
#define | PW_CORE_EVENT_INFO 0
| Core.
#define | PW_CORE_EVENT_DONE 1
#define | PW_CORE_EVENT_PING 2
#define | PW_CORE_EVENT_ERROR 3
#define | PW_CORE_EVENT_REMOVE_ID 4
#define | PW_CORE_EVENT_BOUND_ID 5
#define | PW_CORE_EVENT_ADD_MEM 6
#define | PW_CORE_EVENT_REMOVE_MEM 7
#define | PW_CORE_EVENT_BOUND_PROPS 8
#define | PW_CORE_EVENT_NUM 9
#define | PW_VERSION_CORE_EVENTS 1
#define | PW_CORE_METHOD_ADD_LISTENER 0
#define | PW_CORE_METHOD_HELLO 1
#define | PW_CORE_METHOD_SYNC 2
#define | PW_CORE_METHOD_PONG 3
#define | PW_CORE_METHOD_ERROR 4
#define | PW_CORE_METHOD_GET_REGISTRY 5
#define | PW_CORE_METHOD_CREATE_OBJECT 6
#define | PW_CORE_METHOD_DESTROY 7
#define | PW_CORE_METHOD_NUM 8
#define | PW_VERSION_CORE_METHODS 0
#define | pw_core_method(o, method, version, ...)
#define | pw_core_add_listener(c, ...)
#define | pw_core_hello(c, ...)
| Start a conversation with the server.
#define | pw_core_sync(c, ...)
| Do server roundtrip.
#define | pw_core_pong(c, ...)
| Reply to a server ping event.
#define | pw_core_error(c, ...)
| Fatal error event.
#define | pw_core_destroy(c, ...)
| Destroy an resource.

## Functions
struct pw_core_info * | pw_core_info_update (struct pw_core_info *info, const struct pw_core_info *update)
| Update an existing pw_core_info with update with reset.
struct pw_core_info * | pw_core_info_merge (struct pw_core_info *info, const struct pw_core_info *update, bool reset)
| Update an existing pw_core_info with update.
void | pw_core_info_free (struct pw_core_info *info)
| Free a pw_core_info
static int | pw_core_errorv (struct pw_core *core, uint32_t id, int seq, int res, const char *message, va_list args)
static int | pw_core_errorf (struct pw_core *core, uint32_t id, int seq, int res, const char *message,...)
static struct pw_registry * | pw_core_get_registry (struct pw_core *core, uint32_t version, size_t user_data_size)
static void * | pw_core_create_object (struct pw_core *core, const char *factory_name, const char *type, uint32_t version, const struct spa_dict *props, size_t user_data_size)
struct pw_core * | pw_context_connect (struct pw_context *context, struct pw_properties *properties, size_t user_data_size)
| Connect to a PipeWire instance.
struct pw_core * | pw_context_connect_fd (struct pw_context *context, int fd, struct pw_properties *properties, size_t user_data_size)
| Connect to a PipeWire instance on the given socket.
struct pw_core * | pw_context_connect_self (struct pw_context *context, struct pw_properties *properties, size_t user_data_size)
| Connect to a given PipeWire instance.
int | pw_core_steal_fd (struct pw_core *core)
| Steal the fd of the core connection or < 0 on error.
int | pw_core_set_paused (struct pw_core *core, bool paused)
| Pause or resume the core.
int | pw_core_disconnect (struct pw_core *core)
| disconnect and destroy a core
void * | pw_core_get_user_data (struct pw_core *core)
| Get the user_data.
struct pw_client * | pw_core_get_client (struct pw_core *core)
| Get the client proxy of the connected core.
struct pw_context * | pw_core_get_context (struct pw_core *core)
| Get the context object used to created this core.
const struct pw_properties * | pw_core_get_properties (struct pw_core *core)
| Get properties from the core.
int | pw_core_update_properties (struct pw_core *core, const struct spa_dict *dict)
| Update the core properties.
struct pw_mempool * | pw_core_get_mempool (struct pw_core *core)
| Get the core mempool object.
struct pw_proxy * | pw_core_find_proxy (struct pw_core *core, uint32_t id)
| Get the proxy with the given id.
struct pw_proxy * | pw_core_export (struct pw_core *core, const char *type, const struct spa_dict *props, void *object, size_t user_data_size)
| Export an object into the PipeWire instance associated with core.

## Detailed Description

The core global object.

This is a special singleton object. It is used for internal PipeWire protocol features. Connecting to a PipeWire instance returns one core object, the caller should then register event listeners using pw_core_add_listener.

Updates to the core object are then provided through the pw_core_events interface. See Tutorial - Part 2: Enumerating Objects for an example.

## Macro Definition Documentation

## ◆ PW_TYPE_INTERFACE_Core

#define PW_TYPE_INTERFACE_Core PW_TYPE_INFO_INTERFACE_BASE "Core"

## ◆ PW_TYPE_INTERFACE_Registry

#define PW_TYPE_INTERFACE_Registry PW_TYPE_INFO_INTERFACE_BASE "Registry"

## ◆ PW_CORE_PERM_MASK

#define PW_CORE_PERM_MASK PW_PERM_R|PW_PERM_X|PW_PERM_M

## ◆ PW_VERSION_CORE

#define PW_VERSION_CORE 4

## ◆ PW_VERSION_REGISTRY

#define PW_VERSION_REGISTRY 3

Examples
  tutorial2.c, tutorial3.c, and tutorial6.c.

## ◆ PW_DEFAULT_REMOTE

#define PW_DEFAULT_REMOTE "pipewire-0"

The default remote name to connect to.

## ◆ PW_ID_CORE

#define PW_ID_CORE 0

default ID for the core object after connect

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, and tutorial3.c.

## ◆ PW_ID_ANY

#define PW_ID_ANY (uint32_t)(0xffffffff)

Examples
  audio-capture.c, audio-src.c, export-sink.c, tutorial4.c, tutorial5.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ PW_CORE_CHANGE_MASK_PROPS

#define PW_CORE_CHANGE_MASK_PROPS (1 << 0)

## ◆ PW_CORE_CHANGE_MASK_ALL

#define PW_CORE_CHANGE_MASK_ALL ((1 << 1)-1)

## ◆ PW_CORE_EVENT_INFO

#define PW_CORE_EVENT_INFO 0

Core.

## ◆ PW_CORE_EVENT_DONE

#define PW_CORE_EVENT_DONE 1

## ◆ PW_CORE_EVENT_PING

#define PW_CORE_EVENT_PING 2

## ◆ PW_CORE_EVENT_ERROR

#define PW_CORE_EVENT_ERROR 3

## ◆ PW_CORE_EVENT_REMOVE_ID

#define PW_CORE_EVENT_REMOVE_ID 4

## ◆ PW_CORE_EVENT_BOUND_ID

#define PW_CORE_EVENT_BOUND_ID 5

## ◆ PW_CORE_EVENT_ADD_MEM

#define PW_CORE_EVENT_ADD_MEM 6

## ◆ PW_CORE_EVENT_REMOVE_MEM

#define PW_CORE_EVENT_REMOVE_MEM 7

## ◆ PW_CORE_EVENT_BOUND_PROPS

#define PW_CORE_EVENT_BOUND_PROPS 8

## ◆ PW_CORE_EVENT_NUM

#define PW_CORE_EVENT_NUM 9

## ◆ PW_VERSION_CORE_EVENTS

#define PW_VERSION_CORE_EVENTS 1

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, and tutorial3.c.

## ◆ PW_CORE_METHOD_ADD_LISTENER

#define PW_CORE_METHOD_ADD_LISTENER 0

## ◆ PW_CORE_METHOD_HELLO

#define PW_CORE_METHOD_HELLO 1

## ◆ PW_CORE_METHOD_SYNC

#define PW_CORE_METHOD_SYNC 2

## ◆ PW_CORE_METHOD_PONG

#define PW_CORE_METHOD_PONG 3

## ◆ PW_CORE_METHOD_ERROR

#define PW_CORE_METHOD_ERROR 4

## ◆ PW_CORE_METHOD_GET_REGISTRY

#define PW_CORE_METHOD_GET_REGISTRY 5

## ◆ PW_CORE_METHOD_CREATE_OBJECT

#define PW_CORE_METHOD_CREATE_OBJECT 6

## ◆ PW_CORE_METHOD_DESTROY

#define PW_CORE_METHOD_DESTROY 7

## ◆ PW_CORE_METHOD_NUM

#define PW_CORE_METHOD_NUM 8

## ◆ PW_VERSION_CORE_METHODS

#define PW_VERSION_CORE_METHODS 0

## ◆ pw_core_method

#define pw_core_method | ( |  | o,
|  |  | method,
|  |  | version,
|  |  | ... )

## ◆ pw_core_add_listener

#define pw_core_add_listener | ( |  | c,
|  |  | ... )

Value:
pw_core_method(c,add_listener,0,__VA_ARGS__)
pw_core_method
#define pw_core_method(o, method, version,...)
Definition core.h:375

See also
  pw_core_methods.add_listener

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, and tutorial3.c.

## ◆ pw_core_hello

#define pw_core_hello | ( |  | c,
|  |  | ... )

Value:
pw_core_method(c,hello,0,__VA_ARGS__)

Start a conversation with the server.

This will send the core info and will destroy all resources for the client (except the core and client resource).

This requires X permissions on the core.

See also
  pw_core_methods.hello

## ◆ pw_core_sync

#define pw_core_sync | ( |  | c,
|  |  | ... )

Value:
pw_core_method(c,sync,0,__VA_ARGS__)

Do server roundtrip.

Ask the server to emit the 'done' event with seq.

Since methods are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous methods and the resulting events have been handled.

Parameters

  seq | the seq number passed to the done event

This requires X permissions on the core.

See also
  pw_core_methods.sync

Examples
  tutorial3.c.

## ◆ pw_core_pong

#define pw_core_pong | ( |  | c,
|  |  | ... )

Value:
pw_core_method(c,pong,0,__VA_ARGS__)

Reply to a server ping event.

Reply to the server ping event with the same seq.

Parameters

  seq | the seq number received in the ping event

This requires X permissions on the core.

See also
  pw_core_methods.pong

## ◆ pw_core_error

#define pw_core_error | ( |  | c,
|  |  | ... )

Value:
pw_core_method(c,error,0,__VA_ARGS__)

Fatal error event.

The error method 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 an event on that object. The message is a brief description of the error, for (debugging) convenience.

This method is usually also emitted on the resource object with id.

Parameters

  id | resource id where the error occurred
  res | error code
  message | error description

This requires X permissions on the core.

See also
  pw_core_methods.error

## ◆ pw_core_destroy

#define pw_core_destroy | ( |  | c,
|  |  | ... )

Value:
pw_core_method(c,destroy,0,__VA_ARGS__)

Destroy an resource.

Destroy the server resource for the given proxy.

Parameters

  obj | the proxy to destroy

This requires X permissions on the core.

See also
  pw_core_methods.destroy

## Function Documentation

## ◆ pw_core_info_update()

struct pw_core_info * pw_core_info_update | ( | struct pw_core_info * | info,
|  | const struct pw_core_info * | update )

Update an existing pw_core_info with update with reset.

When info is NULL, a new one will be allocated. Returns NULL on failure.

## ◆ pw_core_info_merge()

struct pw_core_info * pw_core_info_merge | ( | struct pw_core_info * | info,
|  | const struct pw_core_info * | update,
|  | bool | reset )

Update an existing pw_core_info with update.

When info is NULL, a new one will be allocated. Returns NULL on failure

## ◆ pw_core_info_free()

void pw_core_info_free | ( | struct pw_core_info * | info | ) |

Free a pw_core_info

## ◆ pw_core_errorv()

static int pw_core_errorv | ( | struct pw_core * | core,
|  | uint32_t | id,
|  | int | seq,
|  | int | res,
|  | const char * | message,
|  | va_list | args )
| inline static

## ◆ pw_core_errorf()

static int pw_core_errorf | ( | struct pw_core * | core,
|  | uint32_t | id,
|  | int | seq,
|  | int | res,
|  | const char * | message,
|  |  | ... )
| inline static

## ◆ pw_core_get_registry()

static struct pw_registry * pw_core_get_registry | ( | struct pw_core * | core,
|  | uint32_t | version,
|  | size_t | user_data_size )
| inline static

Examples
  tutorial2.c, tutorial3.c, and tutorial6.c.

## ◆ pw_core_create_object()

static void * pw_core_create_object | ( | struct pw_core * | core,
|  | const char * | factory_name,
|  | const char * | type,
|  | uint32_t | version,
|  | const struct spa_dict * | props,
|  | size_t | user_data_size )
| inline static

Examples
  internal.c.

## ◆ pw_context_connect()

struct pw_core * pw_context_connect | ( | struct pw_context * | context,
|  | struct pw_properties * | properties,
|  | size_t | user_data_size )

Connect to a PipeWire instance.

Parameters

  context | a Context
  properties | optional properties, ownership of the properties is taken.
  user_data_size | extra user data size

Returns
  a Core on success or NULL with errno set on error. The core will have an id of PW_ID_CORE (0)

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, tutorial2.c, tutorial3.c, tutorial6.c, video-dsp-src.c, and video-src.c.

## ◆ pw_context_connect_fd()

struct pw_core * pw_context_connect_fd | ( | struct pw_context * | context,
|  | int | fd,
|  | struct pw_properties * | properties,
|  | size_t | user_data_size )

Connect to a PipeWire instance on the given socket.

Parameters

  context | a Context
  fd | the connected socket to use, the socket will be closed automatically on disconnect or error.
  properties | optional properties, ownership of the properties is taken.
  user_data_size | extra user data size

Returns
  a Core on success or NULL with errno set on error

## ◆ pw_context_connect_self()

struct pw_core * pw_context_connect_self | ( | struct pw_context * | context,
|  | struct pw_properties * | properties,
|  | size_t | user_data_size )

Connect to a given PipeWire instance.

Parameters

  context | a Context to connect to
  properties | optional properties, ownership of the properties is taken.
  user_data_size | extra user data size

Returns
  a Core on success or NULL with errno set on error

Examples
  internal.c.

## ◆ pw_core_steal_fd()

int pw_core_steal_fd | ( | struct pw_core * | core | ) |

Steal the fd of the core connection or < 0 on error.

The core will be disconnected after this call.

## ◆ pw_core_set_paused()

int pw_core_set_paused | ( | struct pw_core * | core,
|  | bool | paused )

Pause or resume the core.

When the core is paused, no new events will be dispatched until the core is resumed again.

## ◆ pw_core_disconnect()

int pw_core_disconnect | ( | struct pw_core * | core | ) |

disconnect and destroy a core

Examples
  export-spa.c, tutorial2.c, tutorial3.c, and tutorial6.c.

## ◆ pw_core_get_user_data()

void * pw_core_get_user_data | ( | struct pw_core * | core | ) |

Get the user_data.

It is of the size specified when this object was constructed

## ◆ pw_core_get_client()

struct pw_client * pw_core_get_client | ( | struct pw_core * | core | ) |

Get the client proxy of the connected core.

This will have the id of PW_ID_CLIENT (1)

Examples
  export-sink.c.

## ◆ pw_core_get_context()

struct pw_context * pw_core_get_context | ( | struct pw_core * | core | ) |

Get the context object used to created this core.

## ◆ pw_core_get_properties()

const struct pw_properties * pw_core_get_properties | ( | struct pw_core * | core | ) |

Get properties from the core.

## ◆ pw_core_update_properties()

int pw_core_update_properties | ( | struct pw_core * | core,
|  | const struct spa_dict * | dict )

Update the core properties.

This updates the properties of the associated client.

Returns
  the number of properties that were updated

## ◆ pw_core_get_mempool()

struct pw_mempool * pw_core_get_mempool | ( | struct pw_core * | core | ) |

Get the core mempool object.

## ◆ pw_core_find_proxy()

struct pw_proxy * pw_core_find_proxy | ( | struct pw_core * | core,
|  | uint32_t | id )

Get the proxy with the given id.

## ◆ pw_core_export()

struct pw_proxy * pw_core_export | ( | struct pw_core * | core,
|  | const char * | type,
|  | const struct spa_dict * | props,
|  | void * | object,
|  | size_t | user_data_size )

Export an object into the PipeWire instance associated with core.

Parameters

  core | the core
  type | the type of object
  props | extra properties
  object | object to export
  user_data_size | extra user data

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, and export-spa.c.