PipeWire 1.0.4
Loading...
Searching...
No Matches

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_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, ...)   pw_core_method(c,add_listener,0,__VA_ARGS__)
 
#define pw_core_hello(c, ...)   pw_core_method(c,hello,0,__VA_ARGS__)
 Start a conversation with the server.
 
#define pw_core_sync(c, ...)   pw_core_method(c,sync,0,__VA_ARGS__)
 Do server roundtrip.
 
#define pw_core_pong(c, ...)   pw_core_method(c,pong,0,__VA_ARGS__)
 Reply to a server ping event.
 
#define pw_core_error(c, ...)   pw_core_method(c,error,0,__VA_ARGS__)
 Fatal error event.
 
#define pw_core_destroy(c, ...)   pw_core_method(c,destroy,0,__VA_ARGS__)
 Destroy an resource.
 

Functions

struct pw_core_infopw_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_infopw_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_registrypw_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_corepw_context_connect (struct pw_context *context, struct pw_properties *properties, size_t user_data_size)
 Connect to a PipeWire instance.
 
struct pw_corepw_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_corepw_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_clientpw_core_get_client (struct pw_core *core)
 Get the client proxy of the connected core.
 
struct pw_contextpw_core_get_context (struct pw_core *core)
 Get the context object used to created this core.
 
const struct pw_propertiespw_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_mempoolpw_core_get_mempool (struct pw_core *core)
 Get the core mempool object.
 
struct pw_proxypw_core_find_proxy (struct pw_core *core, uint32_t id)
 Get the proxy with the given id.
 
struct pw_proxypw_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

◆ 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

◆ 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

◆ 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,
  ... 
)    pw_core_method(c,add_listener,0,__VA_ARGS__)

◆ pw_core_hello

#define pw_core_hello (   c,
  ... 
)    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,
  ... 
)    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
seqthe 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,
  ... 
)    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
seqthe 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,
  ... 
)    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
idresource id where the error occurred
reserror code
messageerror description

This requires X permissions on the core.

See also
pw_core_methods.error

◆ pw_core_destroy

#define pw_core_destroy (   c,
  ... 
)    pw_core_method(c,destroy,0,__VA_ARGS__)

Destroy an resource.

Destroy the server resource for the given proxy.

Parameters
objthe 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.

◆ 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.

◆ 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 
)
inlinestatic

◆ pw_core_errorf()

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

◆ pw_core_get_registry()

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

◆ 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 
)
inlinestatic
Examples
internal.c, and local-v4l2.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
contexta Context
propertiesoptional properties, ownership of the properties is taken.
user_data_sizeextra 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, 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
contexta Context
fdthe connected socket to use, the socket will be closed automatically on disconnect or error.
propertiesoptional properties, ownership of the properties is taken.
user_data_sizeextra 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
contexta Context to connect to
propertiesoptional properties, ownership of the properties is taken.
user_data_sizeextra user data size
Returns
a Core on success or NULL with errno set on error
Examples
internal.c, and local-v4l2.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
corethe core
typethe type of object
propsextra properties
objectobject to export
user_data_sizeextra user data
Examples
bluez-session.c, export-sink.c, export-source.c, export-spa-device.c, export-spa.c, and local-v4l2.c.