MateMixerContext

MateMixerContext — The main class for interfacing with the library

Synopsis

#include <libmatemixer/matemixer.h>

enum                MateMixerState;
enum                MateMixerBackendType;
enum                MateMixerBackendFlags;
                    MateMixerContext;
struct              MateMixerContextClass;
MateMixerContext *  mate_mixer_context_new              (void);
gboolean            mate_mixer_context_set_backend_type (MateMixerContext *context,
                                                         MateMixerBackendType backend_type);
gboolean            mate_mixer_context_set_app_name     (MateMixerContext *context,
                                                         const gchar *app_name);
gboolean            mate_mixer_context_set_app_id       (MateMixerContext *context,
                                                         const gchar *app_id);
gboolean            mate_mixer_context_set_app_version  (MateMixerContext *context,
                                                         const gchar *app_version);
gboolean            mate_mixer_context_set_app_icon     (MateMixerContext *context,
                                                         const gchar *app_icon);
gboolean            mate_mixer_context_set_server_address
                                                        (MateMixerContext *context,
                                                         const gchar *address);
gboolean            mate_mixer_context_open             (MateMixerContext *context);
void                mate_mixer_context_close            (MateMixerContext *context);
MateMixerState      mate_mixer_context_get_state        (MateMixerContext *context);
MateMixerDevice *   mate_mixer_context_get_device       (MateMixerContext *context,
                                                         const gchar *name);
MateMixerStream *   mate_mixer_context_get_stream       (MateMixerContext *context,
                                                         const gchar *name);
MateMixerStoredControl * mate_mixer_context_get_stored_control
                                                        (MateMixerContext *context,
                                                         const gchar *name);
const GList *       mate_mixer_context_list_devices     (MateMixerContext *context);
const GList *       mate_mixer_context_list_streams     (MateMixerContext *context);
const GList *       mate_mixer_context_list_stored_controls
                                                        (MateMixerContext *context);
MateMixerStream *   mate_mixer_context_get_default_input_stream
                                                        (MateMixerContext *context);
gboolean            mate_mixer_context_set_default_input_stream
                                                        (MateMixerContext *context,
                                                         MateMixerStream *stream);
MateMixerStream *   mate_mixer_context_get_default_output_stream
                                                        (MateMixerContext *context);
gboolean            mate_mixer_context_set_default_output_stream
                                                        (MateMixerContext *context,
                                                         MateMixerStream *stream);
const gchar *       mate_mixer_context_get_backend_name (MateMixerContext *context);
MateMixerBackendType mate_mixer_context_get_backend_type
                                                        (MateMixerContext *context);
MateMixerBackendFlags mate_mixer_context_get_backend_flags
                                                        (MateMixerContext *context);

Object Hierarchy

  GObject
   +----MateMixerContext

Properties

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

Signals

  "device-added"                                   : Run First
  "device-removed"                                 : Run First
  "stored-control-added"                           : Run First
  "stored-control-removed"                         : Run First
  "stream-added"                                   : Run First
  "stream-removed"                                 : Run First

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.

Details

enum MateMixerState

typedef enum {
    MATE_MIXER_STATE_IDLE,
    MATE_MIXER_STATE_CONNECTING,
    MATE_MIXER_STATE_READY,
    MATE_MIXER_STATE_FAILED,
    MATE_MIXER_STATE_UNKNOWN
} MateMixerState;

State of a connection to a sound system.

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

typedef enum {
    MATE_MIXER_BACKEND_UNKNOWN,
    MATE_MIXER_BACKEND_PULSEAUDIO,
    MATE_MIXER_BACKEND_ALSA,
    MATE_MIXER_BACKEND_OSS,
    MATE_MIXER_BACKEND_NULL
} MateMixerBackendType;

Constants identifying a sound system backend.

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

typedef enum {
 /*< flags >*/
    MATE_MIXER_BACKEND_NO_FLAGS                      = 0,
    MATE_MIXER_BACKEND_HAS_APPLICATION_CONTROLS      = 1 << 0,
    MATE_MIXER_BACKEND_HAS_STORED_CONTROLS           = 1 << 1,
    MATE_MIXER_BACKEND_CAN_SET_DEFAULT_INPUT_STREAM  = 1 << 2,
    MATE_MIXER_BACKEND_CAN_SET_DEFAULT_OUTPUT_STREAM = 1 << 3
} MateMixerBackendFlags;

Flags describing capabilities of a sound system.

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.

GObjectClass parent_class;

The parent class.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

context :

a MateMixerContext

Returns :

the capability flags.

Property Details

The "app-icon" property

  "app-icon"                 gchar*                : Read / Write

The XDG icon name of the application.

Default value: NULL


The "app-id" property

  "app-id"                   gchar*                : Read / Write

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

Default value: NULL


The "app-name" property

  "app-name"                 gchar*                : Read / Write

Localized human readable name of the application.

Default value: NULL


The "app-version" property

  "app-version"              gchar*                : Read / Write

Version of the application.

Default value: NULL


The "default-input-stream" property

  "default-input-stream"     MateMixerStream*      : Read / Write

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.


The "default-output-stream" property

  "default-output-stream"    MateMixerStream*      : Read / Write

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.


The "server-address" property

  "server-address"           gchar*                : Read / Write

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.

Default value: NULL


The "state" property

  "state"                    MateMixerState        : Read

The current state of the connection to a sound system.

Default value: MATE_MIXER_STATE_IDLE

Signal Details

The "device-added" signal

void                user_function                      (MateMixerContext *context,
                                                        gchar            *name,
                                                        gpointer          user_data)      : Run First

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.

context :

a MateMixerContext

name :

name of the added device

user_data :

user data set when the signal handler was connected.

The "device-removed" signal

void                user_function                      (MateMixerContext *context,
                                                        gchar            *name,
                                                        gpointer          user_data)      : Run First

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

context :

a MateMixerContext

name :

name of the removed device

user_data :

user data set when the signal handler was connected.

The "stored-control-added" signal

void                user_function                      (MateMixerContext *context,
                                                        gchar            *name,
                                                        gpointer          user_data)      : Run First

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

Use mate_mixer_context_get_stored_control() to get the MateMixerStoredControl.

context :

a MateMixerContext

name :

name of the added stored control

user_data :

user data set when the signal handler was connected.

The "stored-control-removed" signal

void                user_function                      (MateMixerContext *context,
                                                        gchar            *name,
                                                        gpointer          user_data)      : Run First

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

context :

a MateMixerContext

name :

name of the removed stored control

user_data :

user data set when the signal handler was connected.

The "stream-added" signal

void                user_function                      (MateMixerContext *context,
                                                        gchar            *name,
                                                        gpointer          user_data)      : Run First

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.

context :

a MateMixerContext

name :

name of the added stream

user_data :

user data set when the signal handler was connected.

The "stream-removed" signal

void                user_function                      (MateMixerContext *context,
                                                        gchar            *name,
                                                        gpointer          user_data)      : Run First

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.

context :

a MateMixerContext

name :

name of the removed stream

user_data :

user data set when the signal handler was connected.