Module libpulse_binding::context

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.

Operations

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 object for each asynchronous operation.

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

An 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 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().

Functions

The sound server’s functionality can be divided into a number of subsections:

• stream
• context::scache
• context::introspect
• context::subscribe

Modules

• ext_device_manager
  Routines for controlling module-device-manager.
• ext_device_restore
  Routines for controlling module-device-restore.
• ext_stream_restore
  Routines for controlling module-stream-restore.
• flagsDeprecated
  Some special flags for contexts.
• introspect
  Routines for daemon introspection.
• scache
  Sample cache mechanism.
• subscribe
  Daemon introspection event subscription subsystem.

Structs

• Context
  An opaque connection context to a daemon.
• FlagSet
  Context flag set.

Enums

• State
  The state of a connection context.