MateMixerContext: libmatemixer Reference Manual

## MateMixerContext MateMixerContext — The main class for interfacing with the library |

## Functions

MateMixerContext * | mate_mixer_context_new ()
gboolean | mate_mixer_context_set_backend_type ()
gboolean | mate_mixer_context_set_app_name ()
gboolean | mate_mixer_context_set_app_id ()
gboolean | mate_mixer_context_set_app_version ()
gboolean | mate_mixer_context_set_app_icon ()
gboolean | mate_mixer_context_set_server_address ()
gboolean | mate_mixer_context_open ()
void | mate_mixer_context_close ()
MateMixerState | mate_mixer_context_get_state ()
MateMixerDevice * | mate_mixer_context_get_device ()
MateMixerStream * | mate_mixer_context_get_stream ()
MateMixerStoredControl * | mate_mixer_context_get_stored_control ()
const GList * | mate_mixer_context_list_devices ()
const GList * | mate_mixer_context_list_streams ()
const GList * | mate_mixer_context_list_stored_controls ()
MateMixerStream * | mate_mixer_context_get_default_input_stream ()
gboolean | mate_mixer_context_set_default_input_stream ()
MateMixerStream * | mate_mixer_context_get_default_output_stream ()
gboolean | mate_mixer_context_set_default_output_stream ()
const gchar * | mate_mixer_context_get_backend_name ()
MateMixerBackendType | mate_mixer_context_get_backend_type ()
MateMixerBackendFlags | mate_mixer_context_get_backend_flags ()

## 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

enum | MateMixerState
enum | MateMixerBackendType
enum | MateMixerBackendFlags
| MateMixerContext
struct | MateMixerContextClass

## 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