Module libpulse_binding::context

Expand description

Connection contexts for asynchronous communication with a server.

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

Overview

A context is the basic object for a connection to a PulseAudio server. It multiplexes commands, data streams and events through a single channel.

There is no need for more than one context per application, unless connections to multiple servers are needed.

All operations on the context are performed asynchronously. I.e. the client will not wait for the server to complete the request. To keep track of all these in-flight operations, the application is given an ::operation::Operation object for each asynchronous operation.

There are only two actions (besides reference counting) that can be performed on an ::operation::Operation: querying its state with ::operation::Operation::get_state and aborting it with ::operation::Operation::cancel.

An ::operation::Operation object is reference counted, so an application must make sure to unreference it, even if it has no intention of using it. This however is taken care of automatically in this Rust binding via the implementation of the Drop trait on the object.

Connecting

A context must be connected to a server before any operation can be issued. Calling Context::connect will initiate the connection procedure. Unlike most asynchronous operations, connecting does not result in an ::operation::Operation object. Instead, the application should register a callback using Context::set_state_callback.

Disconnecting

When the sound support is no longer needed, the connection needs to be closed using Context::disconnect. This is an immediate function that works synchronously.

Since the context object has references to other objects it must be disconnected after use or there is a high risk of memory leaks. If the connection has terminated by itself, then there is no need to explicitly disconnect the context using Context::disconnect.