Connection contexts for asynchronous communication with a server. More...

Typedefs
typedef struct pa_context	pa_context
	An opaque connection context to a daemon.
typedef void(*)	pa_context_notify_cb_t(pa_context c, void userdata)
	Generic notification callback prototype.
typedef void(*)	pa_context_success_cb_t(pa_context c, int success, void userdata)
	A generic callback for operation completion.
typedef void(*)	pa_context_event_cb_t(pa_context c, const char name, pa_proplist p, void userdata)
	A callback for asynchronous meta/policy event messages.

Functions
pa_context *	pa_context_new (pa_mainloop_api mainloop, const char name)
	Instantiate a new connection context with an abstract mainloop API and an application name.
pa_context *	pa_context_new_with_proplist (pa_mainloop_api mainloop, const char name, const pa_proplist *proplist)
	Instantiate a new connection context with an abstract mainloop API and an application name, and specify the initial client property list.
void	pa_context_unref (pa_context *c)
	Decrease the reference counter of the context by one.
pa_context *	pa_context_ref (pa_context *c)
	Increase the reference counter of the context by one.
void	pa_context_set_state_callback (pa_context c, pa_context_notify_cb_t cb, void userdata)
	Set a callback function that is called whenever the context status changes.
void	pa_context_set_event_callback (pa_context p, pa_context_event_cb_t cb, void userdata)
	Set a callback function that is called whenever a meta/policy control event is received.
int	pa_context_errno (const pa_context *c)
	Return the error number of the last failed operation.
int	pa_context_is_pending (const pa_context *c)
	Return non-zero if some data is pending to be written to the connection.
pa_context_state_t	pa_context_get_state (const pa_context *c)
	Return the current context status.
int	pa_context_connect (pa_context c, const char server, pa_context_flags_t flags, const pa_spawn_api *api)
	Connect the context to the specified server.
void	pa_context_disconnect (pa_context *c)
	Terminate the context connection immediately.
pa_operation *	pa_context_drain (pa_context c, pa_context_notify_cb_t cb, void userdata)
	Drain the context.
pa_operation *	pa_context_exit_daemon (pa_context c, pa_context_success_cb_t cb, void userdata)
	Tell the daemon to exit.
pa_operation *	pa_context_set_default_sink (pa_context c, const char name, pa_context_success_cb_t cb, void *userdata)
	Set the name of the default sink.
pa_operation *	pa_context_set_default_source (pa_context c, const char name, pa_context_success_cb_t cb, void *userdata)
	Set the name of the default source.
int	pa_context_is_local (const pa_context *c)
	Returns 1 when the connection is to a local daemon.
pa_operation *	pa_context_set_name (pa_context c, const char name, pa_context_success_cb_t cb, void *userdata)
	Set a different application name for context on the server.
const char *	pa_context_get_server (const pa_context *c)
	Return the server name this context is connected to.
uint32_t	pa_context_get_protocol_version (const pa_context *c)
	Return the protocol version of the library.
uint32_t	pa_context_get_server_protocol_version (const pa_context *c)
	Return the protocol version of the connected server.
pa_operation *	pa_context_proplist_update (pa_context c, pa_update_mode_t mode, const pa_proplist p, pa_context_success_cb_t cb, void *userdata)
	Update the property list of the client, adding new entries.
pa_operation *	pa_context_proplist_remove (pa_context c, const char const keys[], pa_context_success_cb_t cb, void *userdata)
	Update the property list of the client, remove entries.
uint32_t	pa_context_get_index (const pa_context *s)
	Return the client index this context is identified in the server with.
pa_time_event *	pa_context_rttime_new (const pa_context c, pa_usec_t usec, pa_time_event_cb_t cb, void userdata)
	Create a new timer event source for the specified time (wrapper for mainloop->time_new).
void	pa_context_rttime_restart (const pa_context c, pa_time_event e, pa_usec_t usec)
	Restart a running or expired timer event source (wrapper for mainloop->time_restart).
size_t	pa_context_get_tile_size (const pa_context c, const pa_sample_spec ss)
	Return the optimal block size for passing around audio buffers.
int	pa_context_load_cookie_from_file (pa_context c, const char cookie_file_path)
	Load the authentication cookie from a file.

Detailed Description

Connection contexts for asynchronous communication with a server.

A pa_context object wraps a connection to a PulseAudio server using its native protocol.

Typedef Documentation

◆ pa_context

typedef struct pa_context pa_context

An opaque connection context to a daemon.

◆ pa_context_event_cb_t

typedef void(*) pa_context_event_cb_t(pa_context *c, const char *name, pa_proplist *p, void *userdata)

A callback for asynchronous meta/policy event messages.

The set of defined events can be extended at any time. Also, server modules may introduce additional message types so make sure that your callback function ignores messages it doesn't know.

Since: 0.9.15

◆ pa_context_notify_cb_t

typedef void(*) pa_context_notify_cb_t(pa_context *c, void *userdata)

Generic notification callback prototype.

◆ pa_context_success_cb_t

typedef void(*) pa_context_success_cb_t(pa_context *c, int success, void *userdata)

A generic callback for operation completion.

Function Documentation

◆ pa_context_connect()

int pa_context_connect	(	pa_context *	c,
		const char *	server,
		pa_context_flags_t	flags,
		const pa_spawn_api *	api )

Connect the context to the specified server.

If server is NULL, connect to the default server. This routine may but will not always return synchronously on error. Use pa_context_set_state_callback() to be notified when the connection is established. If flags doesn't have PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or accessible a new daemon is spawned. If api is non-NULL, the functions specified in the structure are used when forking a new child process. Returns negative on certain errors such as invalid state or parameters.

References pa_context_connect().

Referenced by pa_context_connect().

◆ pa_context_disconnect()

void pa_context_disconnect ( pa_context * c )

Terminate the context connection immediately.

References pa_context_disconnect().

Referenced by pa_context_disconnect().

◆ pa_context_drain()

pa_operation * pa_context_drain	(	pa_context *	c,
		pa_context_notify_cb_t	cb,
		void *	userdata )

Drain the context.

If there is nothing to drain, the function returns NULL

References pa_context_drain().

Referenced by pa_context_drain().

◆ pa_context_errno()

int pa_context_errno ( const pa_context * c )

Return the error number of the last failed operation.

References pa_context_errno().

Referenced by pa_context_errno().

◆ pa_context_exit_daemon()

pa_operation * pa_context_exit_daemon	(	pa_context *	c,
		pa_context_success_cb_t	cb,
		void *	userdata )

Tell the daemon to exit.

The returned operation is unlikely to complete successfully, since the daemon probably died before returning a success notification

References pa_context_exit_daemon().

Referenced by pa_context_exit_daemon().

◆ pa_context_get_index()

uint32_t pa_context_get_index ( const pa_context * s )

Return the client index this context is identified in the server with.

This is useful for usage with the introspection functions, such as pa_context_get_client_info(). Returns PA_INVALID_INDEX on error.

Since: 0.9.11

References pa_context_get_index().

Referenced by pa_context_get_index().

◆ pa_context_get_protocol_version()

uint32_t pa_context_get_protocol_version ( const pa_context * c )

Return the protocol version of the library.

References pa_context_get_protocol_version().

Referenced by pa_context_get_protocol_version().

◆ pa_context_get_server()

const char * pa_context_get_server ( const pa_context * c )

Return the server name this context is connected to.

References pa_context_get_server().

Referenced by pa_context_get_server().

◆ pa_context_get_server_protocol_version()

uint32_t pa_context_get_server_protocol_version ( const pa_context * c )

Return the protocol version of the connected server.

Returns PA_INVALID_INDEX on error.

References pa_context_get_server_protocol_version().

Referenced by pa_context_get_server_protocol_version().

◆ pa_context_get_state()

pa_context_state_t pa_context_get_state ( const pa_context * c )

Return the current context status.

References pa_context_get_state().

Referenced by pa_context_get_state().

◆ pa_context_get_tile_size()

size_t pa_context_get_tile_size	(	const pa_context *	c,
		const pa_sample_spec *	ss )

Return the optimal block size for passing around audio buffers.

It is recommended to allocate buffers of the size returned here when writing audio data to playback streams, if the latency constraints permit this. It is not recommended writing larger blocks than this because usually they will then be split up internally into chunks of this size. It is not recommended writing smaller blocks than this (unless required due to latency demands) because this increases CPU usage. If ss is NULL you will be returned the byte-exact tile size. if ss is invalid, (size_t) -1 will be returned. If you pass a valid ss, then the tile size will be rounded down to multiple of the frame size. This is supposed to be used in a construct such as pa_context_get_tile_size(pa_stream_get_context(s), pa_stream_get_sample_spec(ss));

Since: 0.9.20

References pa_context_get_tile_size().

Referenced by pa_context_get_tile_size().

◆ pa_context_is_local()

int pa_context_is_local ( const pa_context * c )

Returns 1 when the connection is to a local daemon.

Returns negative when no connection has been made yet.

References pa_context_is_local().

Referenced by pa_context_is_local().

◆ pa_context_is_pending()

int pa_context_is_pending ( const pa_context * c )

Return non-zero if some data is pending to be written to the connection.

References pa_context_is_pending().

Referenced by pa_context_is_pending().

◆ pa_context_load_cookie_from_file()

int pa_context_load_cookie_from_file	(	pa_context *	c,
		const char *	cookie_file_path )

Load the authentication cookie from a file.

This function is primarily meant for PulseAudio's own tunnel modules, which need to load the cookie from a custom location. Applications don't usually need to care about the cookie at all, but if it happens that you know what the authentication cookie is and your application needs to load it from a non-standard location, feel free to use this function.

Since: 5.0

References pa_context_load_cookie_from_file().

Referenced by pa_context_load_cookie_from_file().

◆ pa_context_new()

pa_context * pa_context_new	(	pa_mainloop_api *	mainloop,
		const char *	name )

Instantiate a new connection context with an abstract mainloop API and an application name.

It is recommended to use pa_context_new_with_proplist() instead and specify some initial properties.

References pa_context_new().

Referenced by pa_context_new().

◆ pa_context_new_with_proplist()

pa_context * pa_context_new_with_proplist	(	pa_mainloop_api *	mainloop,
		const char *	name,
		const pa_proplist *	proplist )

Instantiate a new connection context with an abstract mainloop API and an application name, and specify the initial client property list.

Since: 0.9.11

References pa_context_new_with_proplist().

Referenced by pa_context_new_with_proplist().

◆ pa_context_proplist_remove()

pa_operation * pa_context_proplist_remove	(	pa_context *	c,
		const char *const	keys[],
		pa_context_success_cb_t	cb,
		void *	userdata )

Update the property list of the client, remove entries.

Since: 0.9.11

References pa_context_proplist_remove().

Referenced by pa_context_proplist_remove().

◆ pa_context_proplist_update()

pa_operation * pa_context_proplist_update	(	pa_context *	c,
		pa_update_mode_t	mode,
		const pa_proplist *	p,
		pa_context_success_cb_t	cb,
		void *	userdata )

Update the property list of the client, adding new entries.

Please note that it is highly recommended to set as many properties initially via pa_context_new_with_proplist() as possible instead a posteriori with this function, since that information may then be used to route streams of the client to the right device.