MateMixerContext

MateMixerContext — The main class for interfacing with the library

Functions

Properties

char * app-icon Read / Write
char * app-id Read / Write
char * app-name Read / Write
char * app-version Read / Write
MateMixerStream * default-input-stream Read / Write
MateMixerStream * default-output-stream Read / Write
char * server-address Read / Write
MateMixerState state Read

Signals

void device-added Run First
void device-removed Run First
void stored-control-added Run First
void stored-control-removed Run First
void stream-added Run First
void stream-removed Run First

Types and Values

Object Hierarchy

    GObject
    ╰── MateMixerContext

Includes

#include <libmatemixer/matemixer.h>

Description

After the library is initialized, a context should be created to gain access to a sound system.

To create a new context, use the mate_mixer_context_new() function.

The mate_mixer_context_set_backend_type() function can be used to associate the context with a particular type of sound system. Using this function is not necessary, by default the context will select a working sound system backend automatically.

To connect to a sound system, use mate_mixer_context_open().

When the connection is established, it is possible to query a list of sound devices with mate_mixer_context_list_devices() and streams with mate_mixer_context_list_streams().

A device represents a hardware or software sound device in the system, typically a sound card.

A stream is an input or output channel that may exist either as a part of a sound device, or independently. Streams essentially serve as containers for volume controls and switches, for example a sound card with microphone and line-in connectors may have an input stream containing volume controls for each of these connectors and possibly a switch allowing to change the active connector.

Streams may also exist independently as the sound system may for example allow audio streaming over a network.

For a more thorough description of devices and streams, see MateMixerDevice and MateMixerStream.

Devices and streams (as almost all other elements in the library) may appear and disappear at any time, for example when external sound cards are plugged and unplugged. The application should connect to the appropriate signals to handle these events.

Functions

mate_mixer_context_new ()

MateMixerContext *
mate_mixer_context_new (void);

Creates a new MateMixerContext instance.

Returns

a new MateMixerContext instance or NULL if the library has not been initialized with mate_mixer_init().


mate_mixer_context_set_backend_type ()

gboolean
mate_mixer_context_set_backend_type (MateMixerContext *context,
                                     MateMixerBackendType backend_type);

Makes the MateMixerContext use the given MateMixerBackendType.

By default the backend type is determined automatically. This function can be used to alter this behavior and make the context use the selected sound system.

Setting the backend type only succeeds if the selected backend module is available in the target system.

If you have used this function before and want restore the default automatic backend type discovery, set the backend type to MATE_MIXER_BACKEND_UNKNOWN.

This function must be used before opening a connection to a sound system with mate_mixer_context_open(), otherwise it will fail.

Parameters

context

a MateMixerContext

 

backend_type

the sound system backend to use

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_set_app_name ()

gboolean
mate_mixer_context_set_app_name (MateMixerContext *context,
                                 const gchar *app_name);

Sets the name of your application. This information may be used when registering with the sound system.

This function must be used before opening a connection to a sound system with mate_mixer_context_open(), otherwise it will fail.

Parameters

context

a MateMixerContext

 

app_name

the name of your application, or NULL to unset

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_set_app_id ()

gboolean
mate_mixer_context_set_app_id (MateMixerContext *context,
                               const gchar *app_id);

Sets the identifier of your application (e.g. org.example.app). This information may be used when registering with the sound system.

This function must be used before opening a connection to a sound system with mate_mixer_context_open(), otherwise it will fail.

Parameters

context

a MateMixerContext

 

app_id

the identifier of your application, or NULL to unset

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_set_app_version ()

gboolean
mate_mixer_context_set_app_version (MateMixerContext *context,
                                    const gchar *app_version);

Sets the version of your application. This information may be used when registering with the sound system.

This function must be used before opening a connection to a sound system with mate_mixer_context_open(), otherwise it will fail.

Parameters

context

a MateMixerContext

 

app_version

the version of your application, or NULL to unset

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_set_app_icon ()

gboolean
mate_mixer_context_set_app_icon (MateMixerContext *context,
                                 const gchar *app_icon);

Sets the XDG icon name of your application. This information may be used when registering with the sound system.

This function must be used before opening a connection to a sound system with mate_mixer_context_open(), otherwise it will fail.

Parameters

context

a MateMixerContext

 

app_icon

the XDG icon name of your application, or NULL to unset

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_set_server_address ()

gboolean
mate_mixer_context_set_server_address (MateMixerContext *context,
                                       const gchar *address);

Sets the address of the sound server. This feature is only supported in the PulseAudio backend. If the address is not set, the default PulseAudio sound server will be used, which is normally the local daemon.

This function must be used before opening a connection to a sound system with mate_mixer_context_open(), otherwise it will fail.

Parameters

context

a MateMixerContext

 

address

the address of the sound server to connect to or NULL

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_open ()

gboolean
mate_mixer_context_open (MateMixerContext *context);

Opens connection to a sound system. Unless the sound system backend type was chosen manually with mate_mixer_context_set_backend_type(), the library will find a working sound system automatically.

This function can complete the operation either synchronously or asynchronously and it may go through a series of connection “state” transitions.

If this function returns TRUE, the connection has either been established, or it hasn't been established yet and the result will be determined asynchronously. You can differentiate between these two possibilities by checking the connection “state” after this function returns.

The MATE_MIXER_STATE_READY state indicates that the connection has been established successfully.

The MATE_MIXER_STATE_CONNECTING state is reached when the connection has not been established yet and you should wait for the state to change to either MATE_MIXER_STATE_READY or MATE_MIXER_STATE_FAILED. It is required to have a main loop running to allow an asynchronous connection to proceed. The library will use the thread's default main context for this purpose.

If this function returns FALSE, it was not possible to connect to a sound system and the “state” will be set to MATE_MIXER_STATE_FAILED.

Parameters

context

a MateMixerContext

 

Returns

TRUE on success or if the result will be determined asynchronously, or FALSE on failure.


mate_mixer_context_close ()

void
mate_mixer_context_close (MateMixerContext *context);

Closes an open connection to the sound system. The “state” will be set to MATE_MIXER_STATE_IDLE.

Parameters

context

a MateMixerContext

 

mate_mixer_context_get_state ()

MateMixerState
mate_mixer_context_get_state (MateMixerContext *context);

Gets the state of the context 's connection to a sound system.

Parameters

context

a MateMixerContext

 

Returns

the connection state.


mate_mixer_context_get_device ()

MateMixerDevice *
mate_mixer_context_get_device (MateMixerContext *context,
                               const gchar *name);

Gets the device with the given name.

Parameters

context

a MateMixerContext

 

name

a device name

 

Returns

a MateMixerDevice or NULL if there is no such device.


mate_mixer_context_get_stream ()

MateMixerStream *
mate_mixer_context_get_stream (MateMixerContext *context,
                               const gchar *name);

Gets the stream with the given name.

Parameters

context

a MateMixerContext

 

name

a stream name

 

Returns

a MateMixerStream or NULL if there is no such stream.


mate_mixer_context_get_stored_control ()

MateMixerStoredControl *
mate_mixer_context_get_stored_control (MateMixerContext *context,
                                       const gchar *name);

Gets the stored control with the given name.

Parameters

context

a MateMixerContext

 

name

a stored control name

 

Returns

a MateMixerStoredControl or NULL if there is no such stored control.


mate_mixer_context_list_devices ()

const GList *
mate_mixer_context_list_devices (MateMixerContext *context);

Gets a list of devices. Each item in the list is a MateMixerDevice representing a sound device in the system.

The returned GList is owned by the library and may be invalidated at any time.

Parameters

context

a MateMixerContext

 

Returns

a GList of all devices in the system or NULL if there are none or you are not connected to a sound system.


mate_mixer_context_list_streams ()

const GList *
mate_mixer_context_list_streams (MateMixerContext *context);

Gets a list of streams. Each item in the list is a MateMixerStream representing an input or output stream.

Note that the list will contain streams which belong to devices as well as streams which do not. If you are only interested in streams of a specific device, use mate_mixer_device_list_streams().

The returned GList is owned by the library and may be invalidated at any time.

Parameters

context

a MateMixerContext

 

Returns

a GList of all streams in the system or NULL if there are none or you are not connected to a sound system.


mate_mixer_context_list_stored_controls ()

const GList *
mate_mixer_context_list_stored_controls
                               (MateMixerContext *context);

Gets a list of stored controls. Each item in the list is a MateMixerStoredControl.

The returned GList is owned by the library and may be invalidated at any time.

Parameters

context

a MateMixerContext

 

Returns

a GList of stored controls or NULL if there are none or you are not connected to a sound system.


mate_mixer_context_get_default_input_stream ()

MateMixerStream *
mate_mixer_context_get_default_input_stream
                               (MateMixerContext *context);

Gets the default input stream. The returned stream is where sound input most likely comes from by default.

Parameters

context

a MateMixerContext

 

Returns

a MateMixerStream or NULL if there is no default input stream.


mate_mixer_context_set_default_input_stream ()

gboolean
mate_mixer_context_set_default_input_stream
                               (MateMixerContext *context,
                                MateMixerStream *stream);

Changes the default input stream. The given stream must be an input stream.

Changing the default input stream may not be supported by the sound system. Use mate_mixer_context_get_backend_flags() to find out.

Parameters

context

a MateMixerContext

 

stream

a MateMixerStream to set as the default input stream

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_get_default_output_stream ()

MateMixerStream *
mate_mixer_context_get_default_output_stream
                               (MateMixerContext *context);

Gets the default output stream. The returned stream is where sound output is most likely directed to by default.

Parameters

context

a MateMixerContext

 

Returns

a MateMixerStream or NULL if there are no output streams in the system.


mate_mixer_context_set_default_output_stream ()

gboolean
mate_mixer_context_set_default_output_stream
                               (MateMixerContext *context,
                                MateMixerStream *stream);

Changes the default output stream. The given stream must be an output stream.

Changing the default output stream may not be supported by the sound system. Use mate_mixer_context_get_backend_flags() to find out.

Parameters

context

a MateMixerContext

 

stream

a MateMixerStream to set as the default output stream

 

Returns

TRUE on success or FALSE on failure.


mate_mixer_context_get_backend_name ()

const gchar *
mate_mixer_context_get_backend_name (MateMixerContext *context);

Gets the name of the currently used sound system backend.

This function will not work until the context is connected to a sound system.

Parameters

context

a MateMixerContext

 

Returns

the name or NULL on error.


mate_mixer_context_get_backend_type ()

MateMixerBackendType
mate_mixer_context_get_backend_type (MateMixerContext *context);

Gets the type of the currently used sound system backend.

This function will not work until the context is connected to a sound system.

Parameters

context

a MateMixerContext

 

Returns

the backend type or MATE_MIXER_BACKEND_UNKNOWN on error.


mate_mixer_context_get_backend_flags ()

MateMixerBackendFlags
mate_mixer_context_get_backend_flags (MateMixerContext *context);

Gets the capability flags of the currently used sound system backend.

This function will not work until the context is connected to a sound system.

Parameters

context

a MateMixerContext

 

Returns

the capability flags.

Types and Values

enum MateMixerState

State of a connection to a sound system.

Members

MATE_MIXER_STATE_IDLE

Not connected.

 

MATE_MIXER_STATE_CONNECTING

Connection is in progress.

 

MATE_MIXER_STATE_READY

Connected.

 

MATE_MIXER_STATE_FAILED

Connection has failed.

 

MATE_MIXER_STATE_UNKNOWN

Unknown state. This state is used as an error indicator.

 

enum MateMixerBackendType

Constants identifying a sound system backend.

Members

MATE_MIXER_BACKEND_UNKNOWN

Unknown or undefined sound system backend type.

 

MATE_MIXER_BACKEND_PULSEAUDIO

PulseAudio sound system backend. It has the highest priority and will be the first one to try when you call mate_mixer_context_open(), unless you select a specific sound system to connect to.

 

MATE_MIXER_BACKEND_ALSA

The Advanced Linux Sound Architecture sound system.

 

MATE_MIXER_BACKEND_OSS

The Open Sound System.

 

MATE_MIXER_BACKEND_NULL

Fallback backend which never fails to initialize, but provides no functionality. This backend has the lowest priority and will be used if you do not select a specific backend and it isn't possible to use any of the other backends.

 

enum MateMixerBackendFlags

Flags describing capabilities of a sound system.

Members

MATE_MIXER_BACKEND_NO_FLAGS

No flags.

 

MATE_MIXER_BACKEND_HAS_APPLICATION_CONTROLS

The sound system backend includes support for application stream controls, allowing per-application volume control.

 

MATE_MIXER_BACKEND_HAS_STORED_CONTROLS

The sound system backend includes support for stored controls. See the MateMixerStoredControl description for more information. The presence of this flag does not guarantee that this feature is enabled in the sound system's configuration.

 

MATE_MIXER_BACKEND_CAN_SET_DEFAULT_INPUT_STREAM

The sound system backend is able to change the current default input stream using the mate_mixer_context_set_default_input_stream() function.

 

MATE_MIXER_BACKEND_CAN_SET_DEFAULT_OUTPUT_STREAM

The sound system backend is able to change the current default output stream using the mate_mixer_context_set_default_output_stream() function.

 

MateMixerContext

typedef struct _MateMixerContext MateMixerContext;

The MateMixerContext structure contains only private data and should only be accessed using the provided API.


struct MateMixerContextClass

struct MateMixerContextClass {
    GObjectClass parent_class;
};

The class structure for MateMixerContext.

Members

Property Details

The “app-icon” property

  “app-icon”                 char *

The XDG icon name of the application.

Owner: MateMixerContext

Flags: Read / Write

Default value: NULL


The “app-id” property

  “app-id”                   char *

Identifier of the application (e.g. org.example.app).

Owner: MateMixerContext

Flags: Read / Write

Default value: NULL


The “app-name” property

  “app-name”                 char *

Localized human readable name of the application.

Owner: MateMixerContext

Flags: Read / Write

Default value: NULL


The “app-version” property

  “app-version”              char *

Version of the application.

Owner: MateMixerContext

Flags: Read / Write

Default value: NULL


The “default-input-stream” property

  “default-input-stream”     MateMixerStream *

The stream sound input most likely comes from by default.

See mate_mixer_context_set_default_input_stream() for more information about changing the default input stream.

Owner: MateMixerContext

Flags: Read / Write


The “default-output-stream” property

  “default-output-stream”    MateMixerStream *

The stream sound output is most likely directed to by default.

See mate_mixer_context_set_default_output_stream() for more information about changing the default output stream.

Owner: MateMixerContext

Flags: Read / Write


The “server-address” property

  “server-address”           char *

Address of the sound server to connect to.

This feature is only supported by the PulseAudio sound system. There is no need to specify an address in order to connect to the local PulseAudio daemon.

Owner: MateMixerContext

Flags: Read / Write

Default value: NULL


The “state” property

  “state”                    MateMixerState

The current state of the connection to a sound system.

Owner: MateMixerContext

Flags: Read

Default value: MATE_MIXER_STATE_IDLE

Signal Details

The “device-added” signal

void
user_function (MateMixerContext *context,
               char             *name,
               gpointer          user_data)

The signal is emitted each time a device is added to the system.

Use mate_mixer_context_get_device() to get the MateMixerDevice.

Note that at the time this signal is emitted, the streams and switches of the device may not yet be known.

Parameters

context

a MateMixerContext

 

name

name of the added device

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “device-removed” signal

void
user_function (MateMixerContext *context,
               char             *name,
               gpointer          user_data)

The signal is emitted each time a device is removed from the system.

When this signal is emitted, the device is no longer known to the library, it will not be included in the device list provided by the mate_mixer_context_list_devices() function and it is not possible to get the device with mate_mixer_context_get_device().

Parameters

context

a MateMixerContext

 

name

name of the removed device

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “stored-control-added” signal

void
user_function (MateMixerContext *context,
               char             *name,
               gpointer          user_data)

The signal is emitted each time a stored control is added.

Use mate_mixer_context_get_stored_control() to get the MateMixerStoredControl.

Parameters

context

a MateMixerContext

 

name

name of the added stored control

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “stored-control-removed” signal

void
user_function (MateMixerContext *context,
               char             *name,
               gpointer          user_data)

The signal is emitted each time a stored control is removed.

When this signal is emitted, the stored control is no longer known to the library, it will not be included in the stream list provided by the mate_mixer_context_list_stored_controls() function and it is not possible to get the stored control with mate_mixer_context_get_stored_control().

Parameters

context

a MateMixerContext

 

name

name of the removed stored control

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “stream-added” signal

void
user_function (MateMixerContext *context,
               char             *name,
               gpointer          user_data)

The signal is emitted each time a stream is added.

This signal is emitted for streams which belong to devices as well as streams which do not. If you are only interested in streams of a specific device, the signal is also available in MateMixerDevice.

Note that at the time this signal is emitted, the controls and switches of the stream may not yet be known.

Parameters

context

a MateMixerContext

 

name

name of the added stream

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “stream-removed” signal

void
user_function (MateMixerContext *context,
               char             *name,
               gpointer          user_data)

The signal is emitted each time a stream is removed.

When this signal is emitted, the stream is no longer known to the library, it will not be included in the stream list provided by the mate_mixer_context_list_streams() function and it is not possible to get the stream with mate_mixer_context_get_stream().

This signal is emitted for streams which belong to devices as well as streams which do not. If you are only interested in streams of a specific device, the signal is also available in MateMixerDevice.

Parameters

context

a MateMixerContext

 

name

name of the removed stream

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First