Server Query and Control

Overview

Sometimes it is necessary to query and modify global settings in the server. For this, PulseAudio has the introspection API. It can list sinks, sources, samples and other aspects of the server. It can also modify the attributes of the server that will affect operations on a global level, and not just the application's context.

Querying

All querying is done through callbacks. This design is necessary to maintain an asynchronous design. The client will request the information and some time later, the server will respond with the desired data.

Some objects can have multiple entries at the server. When requesting all of these at once, the callback will be called multiple times, once for each object. When the list has been exhausted, the callback will be called without an information structure and the eol parameter set to a positive value.

Note that even if a single object is requested, and not the entire list, the terminating call will still be made.

If an error occurs, the callback will be called without and information structure and eol set to a negative value..

Data members in the information structures are only valid during the duration of the callback. If they are required after the callback is finished, a deep copy must be performed.

Server Information

The server can be queried about its name, the environment it's running on and the currently active global defaults. Calling pa_context_get_server_info() will get access to a pa_server_info structure containing all of these.

Memory Usage

Statistics about memory usage can be fetched using pa_context_stat(), giving a pa_stat_info structure.

Sinks and Sources

The server can have an arbitrary number of sinks and sources. Each sink and source have both an index and a name associated with it. As such there are three ways to get access to them:

• By index - pa_context_get_sink_info_by_index() / pa_context_get_source_info_by_index()
• By name - pa_context_get_sink_info_by_name() / pa_context_get_source_info_by_name()
• All - pa_context_get_sink_info_list() / pa_context_get_source_info_list()

All three method use the same callback and will provide a pa_sink_info or pa_source_info structure.

Sink Inputs and Source Outputs

Sink inputs and source outputs are the representations of the client ends of streams inside the server. I.e. they connect a client stream to one of the global sinks or sources.

Sink inputs and source outputs only have an index to identify them. As such, there are only two ways to get information about them:

• By index - pa_context_get_sink_input_info() / pa_context_get_source_output_info()
• All - pa_context_get_sink_input_info_list() / pa_context_get_source_output_info_list()

The structure returned is the pa_sink_input_info or pa_source_output_info structure.

Samples

The list of cached samples can be retrieved from the server. Three methods exist for querying the sample cache list:

• By index - pa_context_get_sample_info_by_index()
• By name - pa_context_get_sample_info_by_name()
• All - pa_context_get_sample_info_list()

Note that this only retrieves information about the sample, not the sample data itself.

Driver Modules

PulseAudio driver modules are identified by index and are retrieved using either pa_context_get_module_info() or pa_context_get_module_info_list(). The information structure is called pa_module_info.

Clients

PulseAudio clients are also identified by index and are retrieved using either pa_context_get_client_info() or pa_context_get_client_info_list(). The information structure is called pa_client_info.

Control

Some parts of the server are only possible to read, but most can also be modified in different ways. Note that these changes will affect all connected clients and not just the one issuing the request.

Sinks and Sources

The most common change one would want to do to sinks and sources is to modify the volume of the audio. Identical to how sinks and sources can be queried, there are two ways of identifying them:

• By index - pa_context_set_sink_volume_by_index() / pa_context_set_source_volume_by_index()
• By name - pa_context_set_sink_volume_by_name() / pa_context_set_source_volume_by_name()

It is also possible to mute a sink or source:

• By index - pa_context_set_sink_mute_by_index() / pa_context_set_source_mute_by_index()
• By name - pa_context_set_sink_mute_by_name() / pa_context_set_source_mute_by_name()

Sink Inputs and Source Outputs

If an application desires to modify the volume of just a single stream (commonly one of its own streams), this can be done by setting the volume of its associated sink input, using pa_context_set_sink_input_volume().

There is no support for modifying the volume of source outputs.

It is also possible to remove sink inputs and source outputs, terminating the streams associated with them:

• Sink input - pa_context_kill_sink_input()
• Source output - pa_context_kill_source_output()

Driver Modules

Server modules can be remotely loaded and unloaded using pa_context_load_module() and pa_context_unload_module().

Clients

The only operation supported on clients, is the possibility of kicking them off the server using pa_context_kill_client().