Context

Files
file	context.h
	pipewire/context.h

Data Structures
struct	pw_context_events
	context events emitted by the context object added with pw_context_add_listener More...
struct	pw_export_type
	data for registering export functions More...
struct	pw_context
struct	pw_global
struct	pw_impl_client
struct	pw_impl_node

Macros
#define	PW_VERSION_CONTEXT_EVENTS   1

Functions
struct pw_context *	pw_context_new (struct pw_loop *main_loop, struct pw_properties *props, size_t user_data_size)
	Make a new context object for a given main_loop.
void	pw_context_destroy (struct pw_context *context)
	destroy a context object, all resources except the main_loop will be destroyed
void *	pw_context_get_user_data (struct pw_context *context)
	Get the context user data.
void	pw_context_add_listener (struct pw_context *context, struct spa_hook *listener, const struct pw_context_events *events, void *data)
	Add a new event listener to a context.
const struct pw_properties *	pw_context_get_properties (struct pw_context *context)
	Get the context properties.
int	pw_context_update_properties (struct pw_context *context, const struct spa_dict *dict)
	Update the context properties.
const char *	pw_context_get_conf_section (struct pw_context *context, const char *section)
	Get a config section for this context.
int	pw_context_parse_conf_section (struct pw_context *context, struct pw_properties *conf, const char *section)
	Parse a standard config section for this context.
int	pw_context_conf_update_props (struct pw_context *context, const char *section, struct pw_properties *props)
	update properties from a section into props.
int	pw_context_conf_section_for_each (struct pw_context *context, const char *section, int(*callback)(void *data, const char *location, const char *section, const char *str, size_t len), void *data)
	emit callback for all config sections.
int	pw_context_conf_section_match_rules (struct pw_context *context, const char *section, const struct spa_dict *props, int(*callback)(void *data, const char *location, const char *action, const char *str, size_t len), void *data)
	emit callback for all matched properties.
const struct spa_support *	pw_context_get_support (struct pw_context *context, uint32_t *n_support)
	Get the context support objects.
struct pw_loop *	pw_context_get_main_loop (struct pw_context *context)
	Get the context main loop.
struct pw_data_loop *	pw_context_get_data_loop (struct pw_context *context)
	Get the context data loop.
struct pw_loop *	pw_context_acquire_loop (struct pw_context *context, const struct spa_dict *props)
	Get a data-loop.
void	pw_context_release_loop (struct pw_context *context, struct pw_loop *loop)
	Release a data-loop.
struct pw_work_queue *	pw_context_get_work_queue (struct pw_context *context)
	Get the work queue from the context: Since 0.3.26.
struct pw_mempool *	pw_context_get_mempool (struct pw_context *context)
	Get the memory pool from the context: Since 0.3.74.
int	pw_context_for_each_global (struct pw_context *context, int(*callback)(void *data, struct pw_global *global), void *data)
	Iterate the globals of the context.
struct pw_global *	pw_context_find_global (struct pw_context *context, uint32_t id)
	Find a context global by id.
int	pw_context_add_spa_lib (struct pw_context *context, const char *factory_regex, const char *lib)
	add a spa library for the given factory_name regex
const char *	pw_context_find_spa_lib (struct pw_context *context, const char *factory_name)
	find the library name for a spa factory
struct spa_handle *	pw_context_load_spa_handle (struct pw_context *context, const char *factory_name, const struct spa_dict *info)
	Load a SPA handle from a context.
int	pw_context_register_export_type (struct pw_context *context, struct pw_export_type *type)
	register a type that can be exported on a context_proxy.
const struct pw_export_type *	pw_context_find_export_type (struct pw_context *context, const char *type)
	find information about registered export type
int	pw_context_set_object (struct pw_context *context, const char *type, void *value)
	add an object to the context
void *	pw_context_get_object (struct pw_context *context, const char *type)
	get an object from the context

Detailed Description

The PipeWire context object manages all locally available resources. It is used by both clients and servers.

The context is used to:

• Load modules and extend the functionality. This includes extending the protocol with new object types or creating any of the available objects.
• Create implementations of various objects like nodes, devices, factories, modules, etc.. This will usually also create pw_global objects that can then be shared with clients.
• Connect to another PipeWire instance (the main daemon, for example) and interact with it (See page_core_api).
• Export a local implementation of an object to another instance.

Macro Definition Documentation

PW_VERSION_CONTEXT_EVENTS

#define PW_VERSION_CONTEXT_EVENTS   1

Function Documentation

pw_context_new()

struct pw_context * pw_context_new	(	struct pw_loop *	main_loop,
		struct pw_properties *	properties,
		size_t	user_data_size )

Make a new context object for a given main_loop.

Ownership of the properties is taken, even if the function returns NULL.

Parameters

main_loop	A main loop to run in. This must stay alive unil pw_context_destroy() is called.
props	extra properties
user_data_size	extra user data size

Returns

The context object on success, or NULL on failure, in which case errno is set.

Make a new context object for a given main_loop.

Parameters

main_loop	the main loop to use
properties	extra properties for the context, ownership it taken

Returns

a newly allocated context object

Examples

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

pw_context_destroy()

void pw_context_destroy

(

struct pw_context *

context

)

destroy a context object, all resources except the main_loop will be destroyed

destroy a context object, all resources except the main_loop will be destroyed

Parameters

context

a context to destroy

Examples

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

pw_context_get_user_data()

void * pw_context_get_user_data

(

struct pw_context *

context

)

Get the context user data.

pw_context_add_listener()

void pw_context_add_listener	(	struct pw_context *	context,
		struct spa_hook *	listener,
		const struct pw_context_events *	events,
		void *	data )

Add a new event listener to a context.

pw_context_get_properties()

const struct pw_properties * pw_context_get_properties

(

struct pw_context *

context

)

Get the context properties.

pw_context_update_properties()

int pw_context_update_properties	(	struct pw_context *	context,
		const struct spa_dict *	dict )

Update the context properties.

Update the context properties.

Parameters

context	a context
dict	properties to update

Update the context object with the given properties

pw_context_get_conf_section()

const char * pw_context_get_conf_section	(	struct pw_context *	context,
		const char *	section )

Get a config section for this context.

Since 0.3.22, deprecated, use pw_context_conf_section_for_each().

pw_context_parse_conf_section()

int pw_context_parse_conf_section	(	struct pw_context *	context,
		struct pw_properties *	conf,
		const char *	section )

Parse a standard config section for this context.

Since 0.3.22

pw_context_conf_update_props()

int pw_context_conf_update_props	(	struct pw_context *	context,
		const char *	section,
		struct pw_properties *	props )

update properties from a section into props.

Since 0.3.45

pw_context_conf_section_for_each()

int pw_context_conf_section_for_each	(	struct pw_context *	context,
		const char *	section,
		int(*	callback )(void *data, const char *location, const char *section, const char *str, size_t len),
		void *	data )

emit callback for all config sections.

Since 0.3.45

pw_context_conf_section_match_rules()

int pw_context_conf_section_match_rules	(	struct pw_context *	context,
		const char *	section,
		const struct spa_dict *	props,
		int(*	callback )(void *data, const char *location, const char *action, const char *str, size_t len),
		void *	data )

emit callback for all matched properties.

Since 0.3.46

pw_context_get_support()

const struct spa_support * pw_context_get_support	(	struct pw_context *	context,
		uint32_t *	n_support )

Get the context support objects.

pw_context_get_main_loop()

struct pw_loop * pw_context_get_main_loop

(

struct pw_context *

context

)

Get the context main loop.

Returns the value passed to pw_context_new().

pw_context_get_data_loop()

struct pw_data_loop * pw_context_get_data_loop

(

struct pw_context *

context

)

Get the context data loop.

This loop runs on the realtime thread. This acquires a loop from the generic data.rt class. Use pw_context_acquire_loop() instead. Since 0.3.56

pw_context_acquire_loop()

struct pw_loop * pw_context_acquire_loop	(	struct pw_context *	context,
		const struct spa_dict *	props )

Get a data-loop.

Since 1.1.0

pw_context_release_loop()

void pw_context_release_loop	(	struct pw_context *	context,
		struct pw_loop *	loop )

Release a data-loop.

Since 1.1.0

pw_context_get_work_queue()

struct pw_work_queue * pw_context_get_work_queue

(

struct pw_context *

context

)

Get the work queue from the context: Since 0.3.26.

pw_context_get_mempool()

struct pw_mempool * pw_context_get_mempool

(

struct pw_context *

context

)

Get the memory pool from the context: Since 0.3.74.

pw_context_for_each_global()

int pw_context_for_each_global	(	struct pw_context *	context,
		int(*	callback )(void *data, struct pw_global *global),
		void *	data )

Iterate the globals of the context.

The callback should return 0 to fetch the next item, any other value stops the iteration and returns the value. When all callbacks return 0, this function returns 0 when all globals are iterated.

pw_context_find_global()

struct pw_global * pw_context_find_global	(	struct pw_context *	context,
		uint32_t	id )

Find a context global by id.

Returns

The global on success, or NULL on failure. If id is PW_ID_CORE, this function will always return a non-NULL value.

Parameters

context	the context
id	the global id

pw_context_add_spa_lib()

int pw_context_add_spa_lib	(	struct pw_context *	context,
		const char *	factory_regex,
		const char *	lib )

add a spa library for the given factory_name regex

pw_context_find_spa_lib()

const char * pw_context_find_spa_lib	(	struct pw_context *	context,
		const char *	factory_name )

find the library name for a spa factory

pw_context_load_spa_handle()

struct spa_handle * pw_context_load_spa_handle	(	struct pw_context *	context,
		const char *	factory_name,
		const struct spa_dict *	info )

Load a SPA handle from a context.

On failure returns NULL and sets errno.

Examples

bluez-session.c, and export-spa.c.

pw_context_register_export_type()

int pw_context_register_export_type	(	struct pw_context *	context,
		struct pw_export_type *	type )

register a type that can be exported on a context_proxy.

This is usually used by extension modules

pw_context_find_export_type()

const struct pw_export_type * pw_context_find_export_type	(	struct pw_context *	context,
		const char *	type )

find information about registered export type

pw_context_set_object()

int pw_context_set_object	(	struct pw_context *	context,
		const char *	type,
		void *	value )

add an object to the context

Parameters

context	The context.
type	The type of the object, usually a TYPE_INTERFACE_ value.
value	The object value. Must last as long as the context and must be of the type corresponding to the type.

Returns

A negative number on failure (out of memory).

pw_context_get_object()

void * pw_context_get_object	(	struct pw_context *	context,
		const char *	type )

get an object from the context

Parameters

context	The context.
type	The string corresponding to the object's interface.

Returns

The object, or NULL if the object does not exist.