Loading...
Searching...
No Matches
Core
Core API

The core global object. More...

## 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_API_CORE_IMPL static inline
#define | PW_API_REGISTRY_IMPL static inline
#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

## 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.
PW_API_CORE_IMPL int | pw_core_add_listener (struct pw_core *object, struct spa_hook *listener, const struct pw_core_events *events, void *data)
PW_API_CORE_IMPL int | pw_core_hello (struct pw_core *object, uint32_t version)
| Start a conversation with the server.
PW_API_CORE_IMPL int | pw_core_sync (struct pw_core *object, uint32_t id, int seq)
| Do server roundtrip.
PW_API_CORE_IMPL int | pw_core_pong (struct pw_core *object, uint32_t id, int seq)
| Reply to a server ping event.
PW_API_CORE_IMPL int | pw_core_error (struct pw_core *object, uint32_t id, int seq, int res, const char *message)
| Fatal error event.
| PW_API_CORE_IMPL (5, 0) int pw_core_errorv(struct pw_core *core
| vsnprintf (buffer, sizeof(buffer), message, args)
return | pw_core_error (core, id, seq, res, buffer)
| PW_API_CORE_IMPL (5, 6) int pw_core_errorf(struct pw_core *core
| va_start (args, message)
| va_end (args)
PW_API_CORE_IMPL struct pw_registry * | pw_core_get_registry (struct pw_core *core, uint32_t version, size_t user_data_size)
| Get the registry object.
PW_API_CORE_IMPL 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)
| Create a new object on the PipeWire server from a factory.
PW_API_CORE_IMPL void | pw_core_destroy (struct pw_core *core, void *proxy)
| Destroy an resource.
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.

## Variables

uint32_t | id
uint32_t int | seq
uint32_t int int | res
uint32_t int int const char * | message
uint32_t int int const char va_list | args
| buffer [1023] = '\0'
uint32_t int int const char int | r

## 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
  gmain.c, tutorial2.c, tutorial3.c, and tutorial6.c.

## PW_API_CORE_IMPL

#define PW_API_CORE_IMPL static inline

## PW_API_REGISTRY_IMPL

#define PW_API_REGISTRY_IMPL static inline

## 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-ring.c, audio-src-ring2.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-sync.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, video-src-sync.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

## 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_add_listener()

PW_API_CORE_IMPL int pw_core_add_listener | ( | struct pw_core * | object,
|  | struct spa_hook * | listener,
|  | const struct pw_core_events * | events,
|  | void * | data )

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()

PW_API_CORE_IMPL int pw_core_hello | ( | struct pw_core * | object,
|  | uint32_t | version )

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()

PW_API_CORE_IMPL int pw_core_sync | ( | struct pw_core * | object,
|  | uint32_t | id,
|  | int | seq )

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()

PW_API_CORE_IMPL int pw_core_pong | ( | struct pw_core * | object,
|  | uint32_t | id,
|  | int | seq )

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() [1/2]

PW_API_CORE_IMPL int pw_core_error | ( | struct pw_core * | object,
|  | uint32_t | id,
|  | int | seq,
|  | int | res,
|  | const char * | message )

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_API_CORE_IMPL() [1/2]

PW_API_CORE_IMPL | ( | 5 | ,
|  | 0 | )

## vsnprintf()

vsnprintf | ( | buffer | ,
|  | sizeof(buffer) | ,
|  | message | ,
|  | args | )

## pw_core_error() [2/2]

return pw_core_error | ( | core | ,
|  | id | ,
|  | seq | ,
|  | res | ,
|  | buffer | )

## PW_API_CORE_IMPL() [2/2]

PW_API_CORE_IMPL | ( | 5 | ,
|  | 6 | )

## va_start()

va_start | ( | args | ,
|  | message | )

## va_end()

va_end | ( | args |  | ) |

## pw_core_get_registry()

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

Get the registry object.

Create a registry object that allows the client to list and bind the global objects available from the PipeWire server

Parameters

  version | the client version
  user_data_size | extra size

This requires X permissions on the core.

See also
  pw_core_methods.get_registry

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

## pw_core_create_object()

PW_API_CORE_IMPL 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 )

Create a new object on the PipeWire server from a factory.

Parameters

  factory_name | the factory name to use
  type | the interface to bind to
  version | the version of the interface
  props | extra properties
  user_data_size | extra size

This requires X permissions on the core.

See also
  pw_core_methods.create_object

Examples
  internal.c.

## pw_core_destroy()

PW_API_CORE_IMPL void pw_core_destroy | ( | struct pw_core * | core,
|  | void * | proxy )

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

## 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, gmain.c, tutorial2.c, tutorial3.c, tutorial6.c, video-dsp-src.c, video-src-sync.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, gmain.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.

## Variable Documentation

## id

uint32_t id

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

## seq

uint32_t int seq

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, tutorial3.c, video-dsp-src.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, video-src-sync.c, and video-src.c.

## res

uint32_t int int res

Examples
  bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, internal.c, local-v4l2.c, spa/examples/adapter-control.c, spa/examples/example-control.c, spa/examples/local-libcamera.c, spa/examples/local-v4l2.c, spa/examples/local-videotestsrc.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play-sync.c, video-play.c, video-src-sync.c, and video-src.c.

## message

uint32_t int int const char * message

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

## args

uint32_t int int const char va_list args

## buffer

buffer[1023] = '\0'

Examples
  export-sink.c, and video-play-fixate.c.

## r

return r

Examples
  export-sink.c, video-dsp-play.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play-sync.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.