Core

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

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,
			...
	)		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

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,
			...
	)		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,
			...
	)		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,
			...
	)		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  )

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

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  )

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

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

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, export-spa.c, and local-v4l2.c.