Top | ![]() |
![]() |
![]() |
![]() |
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 |
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 |
enum | MateMixerState |
enum | MateMixerBackendType |
enum | MateMixerBackendFlags |
MateMixerContext | |
struct | MateMixerContextClass |
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.
MateMixerContext *
mate_mixer_context_new (void
);
Creates a new MateMixerContext instance.
a new MateMixerContext instance or NULL
if the library has not
been initialized with mate_mixer_init()
.
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.
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.
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.
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.
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.
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.
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
.
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
.
MateMixerState
mate_mixer_context_get_state (MateMixerContext *context
);
Gets the state of the context
's connection to a sound system.
MateMixerDevice * mate_mixer_context_get_device (MateMixerContext *context
,const gchar *name
);
Gets the device with the given name.
MateMixerStream * mate_mixer_context_get_stream (MateMixerContext *context
,const gchar *name
);
Gets the stream with the given name.
MateMixerStoredControl * mate_mixer_context_get_stored_control (MateMixerContext *context
,const gchar *name
);
Gets the stored control with the given name.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Constants identifying a sound system backend.
Unknown or undefined sound system backend type. |
||
PulseAudio sound system backend. It has the highest priority and
will be the first one to try when you call |
||
The Advanced Linux Sound Architecture sound system. |
||
The Open Sound System. |
||
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. |
Flags describing capabilities of a sound system.
No flags. |
||
The sound system backend includes support for application stream controls, allowing per-application volume control. |
||
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. |
||
The sound system backend is able to change the current default input stream
using the |
||
The sound system backend is able to change the current default output stream
using the |
typedef struct _MateMixerContext MateMixerContext;
The MateMixerContext structure contains only private data and should only be accessed using the provided API.
struct MateMixerContextClass { GObjectClass parent_class; };
The class structure for MateMixerContext.
“app-icon”
property “app-icon” char *
The XDG icon name of the application.
Owner: MateMixerContext
Flags: Read / Write
Default value: NULL
“app-id”
property “app-id” char *
Identifier of the application (e.g. org.example.app).
Owner: MateMixerContext
Flags: Read / Write
Default value: NULL
“app-name”
property “app-name” char *
Localized human readable name of the application.
Owner: MateMixerContext
Flags: Read / Write
Default value: NULL
“app-version”
property “app-version” char *
Version of the application.
Owner: MateMixerContext
Flags: Read / Write
Default value: NULL
“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
“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
“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
“state”
property“state” MateMixerState
The current state of the connection to a sound system.
Owner: MateMixerContext
Flags: Read
Default value: MATE_MIXER_STATE_IDLE
“device-added”
signalvoid 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.
context |
||
name |
name of the added device |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“device-removed”
signalvoid 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()
.
context |
||
name |
name of the removed device |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“stored-control-added”
signalvoid 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.
context |
||
name |
name of the added stored control |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“stored-control-removed”
signalvoid 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()
.
context |
||
name |
name of the removed stored control |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“stream-added”
signalvoid 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.
context |
||
name |
name of the added stream |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“stream-removed”
signalvoid 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.
context |
||
name |
name of the removed stream |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First