diff options
| -rw-r--r-- | docs/reference/Makefile.am | 3 | ||||
| -rw-r--r-- | docs/reference/libmatemixer-sections.txt | 8 | ||||
| -rw-r--r-- | libmatemixer/matemixer-app-info.c | 78 | ||||
| -rw-r--r-- | libmatemixer/matemixer-backend-module.c | 2 | ||||
| -rw-r--r-- | libmatemixer/matemixer-context.c | 225 | ||||
| -rw-r--r-- | libmatemixer/matemixer-device.c | 117 | ||||
| -rw-r--r-- | libmatemixer/matemixer-enums.h | 119 | ||||
| -rw-r--r-- | libmatemixer/matemixer-switch.c | 2 | ||||
| -rw-r--r-- | libmatemixer/matemixer.c | 2 |
9 files changed, 467 insertions, 89 deletions
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 4a6e205..fb3db04 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -61,8 +61,7 @@ IGNORE_HFILES= \ matemixer-stream-private.h \ matemixer-switch-option-private.h \ matemixer-switch-private.h \ - matemixer-private.h \ - matemixer-types.h + matemixer-private.h # Images to copy into HTML directory. # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png diff --git a/docs/reference/libmatemixer-sections.txt b/docs/reference/libmatemixer-sections.txt index 46e8a8d..2b901e5 100644 --- a/docs/reference/libmatemixer-sections.txt +++ b/docs/reference/libmatemixer-sections.txt @@ -9,6 +9,7 @@ LIBMATEMIXER_CHECK_VERSION <SECTION> <FILE>matemixer-app-info</FILE> <TITLE>MateMixerAppInfo</TITLE> +MateMixerAppInfo mate_mixer_app_info_get_name mate_mixer_app_info_get_id mate_mixer_app_info_get_version @@ -16,6 +17,7 @@ mate_mixer_app_info_get_icon <SUBSECTION Standard> MATE_MIXER_APP_INFO MATE_MIXER_TYPE_APP_INFO +<SUBSECTION Private> mate_mixer_app_info_get_type </SECTION> @@ -50,7 +52,6 @@ mate_mixer_context_set_default_output_stream mate_mixer_context_get_backend_name mate_mixer_context_get_backend_type mate_mixer_context_get_backend_flags -MateMixerContextPrivate <SUBSECTION Standard> MATE_MIXER_CONTEXT MATE_MIXER_CONTEXT_CLASS @@ -59,6 +60,8 @@ MATE_MIXER_IS_CONTEXT MATE_MIXER_IS_CONTEXT_CLASS MATE_MIXER_TYPE_CONTEXT mate_mixer_context_get_type +<SUBSECTION Private> +MateMixerContextPrivate </SECTION> <SECTION> @@ -73,7 +76,6 @@ mate_mixer_device_get_stream mate_mixer_device_get_switch mate_mixer_device_list_streams mate_mixer_device_list_switches -MateMixerDevicePrivate <SUBSECTION Standard> MATE_MIXER_DEVICE MATE_MIXER_DEVICE_CLASS @@ -82,6 +84,8 @@ MATE_MIXER_IS_DEVICE MATE_MIXER_IS_DEVICE_CLASS MATE_MIXER_TYPE_DEVICE mate_mixer_device_get_type +<SUBSECTION Private> +MateMixerDevicePrivate </SECTION> <SECTION> diff --git a/libmatemixer/matemixer-app-info.c b/libmatemixer/matemixer-app-info.c index 65cba6c..0a32325 100644 --- a/libmatemixer/matemixer-app-info.c +++ b/libmatemixer/matemixer-app-info.c @@ -22,8 +22,20 @@ * SECTION:matemixer-app-info * @short_description: Application information * @include: libmatemixer/matemixer.h + * @see_also: #MateMixerStreamControl + * + * The #MateMixerAppInfo structure describes application properties. + * + * See #MateMixerStreamControl and the mate_mixer_stream_control_get_app_info() + * function for more information. */ +/** + * MateMixerAppInfo: + * + * The #MateMixerAppInfo structure contains only private data and should only + * be accessed using the provided API. + */ G_DEFINE_BOXED_TYPE (MateMixerAppInfo, mate_mixer_app_info, _mate_mixer_app_info_copy, _mate_mixer_app_info_free) @@ -31,6 +43,10 @@ G_DEFINE_BOXED_TYPE (MateMixerAppInfo, mate_mixer_app_info, /** * mate_mixer_app_info_get_name: * @info: a #MateMixerAppInfo + * + * Gets the name of the application described by @info. + * + * Returns: name of the application or %NULL if it is unknown. */ const gchar * mate_mixer_app_info_get_name (MateMixerAppInfo *info) @@ -43,6 +59,11 @@ mate_mixer_app_info_get_name (MateMixerAppInfo *info) /** * mate_mixer_app_info_get_id: * @info: a #MateMixerAppInfo + * + * Gets the identifier of the application described by @info + * (e.g. org.example.app). + * + * Returns: identifier of the application or %NULL if it is unknown. */ const gchar * mate_mixer_app_info_get_id (MateMixerAppInfo *info) @@ -55,6 +76,10 @@ mate_mixer_app_info_get_id (MateMixerAppInfo *info) /** * mate_mixer_app_info_get_version: * @info: a #MateMixerAppInfo + * + * Gets the version of the application described by @info. + * + * Returns: version of the application or %NULL if it is unknown. */ const gchar * mate_mixer_app_info_get_version (MateMixerAppInfo *info) @@ -67,6 +92,10 @@ mate_mixer_app_info_get_version (MateMixerAppInfo *info) /** * mate_mixer_app_info_get_icon: * @info: a #MateMixerAppInfo + * + * Gets the XDG icon name of the application described by @info. + * + * Returns: icon name of the application or %NULL if it is unknown. */ const gchar * mate_mixer_app_info_get_icon (MateMixerAppInfo *info) @@ -76,12 +105,26 @@ mate_mixer_app_info_get_icon (MateMixerAppInfo *info) return info->icon; } +/** + * _mate_mixer_app_info_new: + * + * Creates a new empty #MateMixerAppInfo structure. + * + * Returns: a new #MateMixerAppInfo. + */ MateMixerAppInfo * _mate_mixer_app_info_new (void) { return g_slice_new0 (MateMixerAppInfo); } +/** + * _mate_mixer_app_info_set_name: + * @info: a #MateMixerAppInfo + * @name: the application name to set + * + * Sets the name of the application described by @info. + */ void _mate_mixer_app_info_set_name (MateMixerAppInfo *info, const gchar *name) { @@ -92,6 +135,13 @@ _mate_mixer_app_info_set_name (MateMixerAppInfo *info, const gchar *name) info->name = g_strdup (name); } +/** + * _mate_mixer_app_info_set_id: + * @info: a #MateMixerAppInfo + * @id: the application identifier to set + * + * Sets the identifier of the application described by @info. + */ void _mate_mixer_app_info_set_id (MateMixerAppInfo *info, const gchar *id) { @@ -102,6 +152,13 @@ _mate_mixer_app_info_set_id (MateMixerAppInfo *info, const gchar *id) info->id = g_strdup (id); } +/** + * _mate_mixer_app_info_set_version: + * @info: a #MateMixerAppInfo + * @version: the application version to set + * + * Sets the version of the application described by @info. + */ void _mate_mixer_app_info_set_version (MateMixerAppInfo *info, const gchar *version) { @@ -112,6 +169,13 @@ _mate_mixer_app_info_set_version (MateMixerAppInfo *info, const gchar *version) info->version = g_strdup (version); } +/** + * _mate_mixer_app_info_set_version: + * @info: a #MateMixerAppInfo + * @icon: the application icon name to set + * + * Sets the XDG icon name of the application described by @info. + */ void _mate_mixer_app_info_set_icon (MateMixerAppInfo *info, const gchar *icon) { @@ -122,6 +186,14 @@ _mate_mixer_app_info_set_icon (MateMixerAppInfo *info, const gchar *icon) info->icon = g_strdup (icon); } +/** + * _mate_mixer_app_info_copy: + * @info: a #MateMixerAppInfo + * + * Creates a copy of the #MateMixerAppInfo. + * + * Returns: a copy of the given @info. + */ MateMixerAppInfo * _mate_mixer_app_info_copy (MateMixerAppInfo *info) { @@ -136,6 +208,12 @@ _mate_mixer_app_info_copy (MateMixerAppInfo *info) return info2; } +/** + * _mate_mixer_app_info_free: + * @info: a #MateMixerAppInfo + * + * Frees the #MateMixerAppInfo. + */ void _mate_mixer_app_info_free (MateMixerAppInfo *info) { diff --git a/libmatemixer/matemixer-backend-module.c b/libmatemixer/matemixer-backend-module.c index bd71de0..7981b9f 100644 --- a/libmatemixer/matemixer-backend-module.c +++ b/libmatemixer/matemixer-backend-module.c @@ -213,7 +213,7 @@ mate_mixer_backend_module_get_info (MateMixerBackendModule *module) * * Gets file path to the backend module. * - * Returns: string containing the path. + * Returns: the file path. */ const gchar * mate_mixer_backend_module_get_path (MateMixerBackendModule *module) diff --git a/libmatemixer/matemixer-context.c b/libmatemixer/matemixer-context.c index bb28b18..88b4bf6 100644 --- a/libmatemixer/matemixer-context.c +++ b/libmatemixer/matemixer-context.c @@ -178,12 +178,12 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) /** * MateMixerContext:app-icon: * - * An XDG icon name for the application. + * The XDG icon name of the application. */ properties[PROP_APP_ICON] = g_param_spec_string ("app-icon", "App icon", - "Application icon name", + "Application XDG icon name", NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -192,8 +192,9 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) * * Address of the sound server to connect to. * - * This feature is only supported in the PulseAudio backend. There is - * no need to specify an address in order to connect to the local daemon. + * 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. */ properties[PROP_SERVER_ADDRESS] = g_param_spec_string ("server-address", @@ -202,6 +203,11 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); + /** + * MateMixerContext:state: + * + * The current state of the connection to a sound system. + */ properties[PROP_STATE] = g_param_spec_enum ("state", "State", @@ -210,6 +216,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) MATE_MIXER_STATE_IDLE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); + /** + * MateMixerContext:default-input-stream: + * + * 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. + */ properties[PROP_DEFAULT_INPUT_STREAM] = g_param_spec_object ("default-input-stream", "Default input stream", @@ -217,6 +231,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) MATE_MIXER_TYPE_STREAM, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); + /** + * MateMixerContext:default-output-stream: + * + * 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. + */ properties[PROP_DEFAULT_OUTPUT_STREAM] = g_param_spec_object ("default-output-stream", "Default output stream", @@ -232,6 +254,11 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) * @name: name of the added device * * 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. */ signals[DEVICE_ADDED] = g_signal_new ("device-added", @@ -251,6 +278,11 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) * @name: name of the removed device * * 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(). */ signals[DEVICE_REMOVED] = g_signal_new ("device-removed", @@ -269,7 +301,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) * @context: a #MateMixerContext * @name: name of the added stream * - * The signal is emitted each time a stream is created. + * 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. */ signals[STREAM_ADDED] = g_signal_new ("stream-added", @@ -289,6 +328,15 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) * @name: name of the removed stream * * 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. */ signals[STREAM_REMOVED] = g_signal_new ("stream-removed", @@ -307,7 +355,9 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) * @context: a #MateMixerContext * @name: name of the added stored control * - * The signal is emitted each time a stored control is created. + * The signal is emitted each time a stored control is added. + * + * Use mate_mixer_context_get_stored_control() to get the #MateMixerStoredControl. */ signals[STORED_CONTROL_ADDED] = g_signal_new ("stored-control-added", @@ -324,9 +374,14 @@ mate_mixer_context_class_init (MateMixerContextClass *klass) /** * MateMixerContext::stored-control-removed: * @context: a #MateMixerContext - * @name: name of the removed control + * @name: name of the removed stored control * - * The signal is emitted each time a control is removed. + * 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(). */ signals[STORED_CONTROL_REMOVED] = g_signal_new ("stored-control-removed", @@ -466,7 +521,7 @@ mate_mixer_context_finalize (GObject *object) * Creates a new #MateMixerContext instance. * * Returns: a new #MateMixerContext instance or %NULL if the library has not - * been initialized using mate_mixer_init(). + * been initialized with mate_mixer_init(). */ MateMixerContext * mate_mixer_context_new (void) @@ -487,12 +542,11 @@ mate_mixer_context_new (void) * Makes the #MateMixerContext use the given #MateMixerBackendType. * * By default the backend type is determined automatically. This function can - * be used before mate_mixer_context_open() to alter this behavior and make the - * @context use the given backend. + * be used to alter this behavior and make the @context use the selected sound + * system. * - * This function will fail if support for the backend is not installed in - * the system or if the current state is either %MATE_MIXER_STATE_CONNECTING or - * %MATE_MIXER_STATE_READY. + * This function must be used before opening a connection to a sound system with + * mate_mixer_context_open(), otherwise it will fail. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -530,12 +584,11 @@ mate_mixer_context_set_backend_type (MateMixerContext *context, * @context: a #MateMixerContext * @app_name: the name of your application, or %NULL to unset * - * Sets the name of the application. This feature is only supported in the - * PulseAudio backend. + * Sets the name of your application. This information may be used when + * registering with the sound system. * - * This function will fail if the current state is either - * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should - * use it before opening a connection to 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -561,12 +614,11 @@ mate_mixer_context_set_app_name (MateMixerContext *context, const gchar *app_nam * @context: a #MateMixerContext * @app_id: the identifier of your application, or %NULL to unset * - * Sets the identifier of the application (e.g. org.example.app). This feature - * is only supported in the PulseAudio backend. + * Sets the identifier of your application (e.g. org.example.app). This + * information may be used when registering with the sound system. * - * This function will fail if the current state is either - * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should - * use it before opening a connection to 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -592,12 +644,11 @@ mate_mixer_context_set_app_id (MateMixerContext *context, const gchar *app_id) * @context: a #MateMixerContext * @app_version: the version of your application, or %NULL to unset * - * Sets the version of the application. This feature is only supported in the - * PulseAudio backend. + * Sets the version of your application. This information may be used when + * registering with the sound system. * - * This function will fail if the current state is either - * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should - * use it before opening a connection to 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -623,12 +674,11 @@ mate_mixer_context_set_app_version (MateMixerContext *context, const gchar *app_ * @context: a #MateMixerContext * @app_icon: the XDG icon name of your application, or %NULL to unset * - * Sets the XDG icon name of the application. This feature is only supported in - * the PulseAudio backend. + * Sets the XDG icon name of your application. This information may be used when + * registering with the sound system. * - * This function will fail if the current state is either - * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should - * use it before opening a connection to 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -658,9 +708,8 @@ mate_mixer_context_set_app_icon (MateMixerContext *context, const gchar *app_ico * PulseAudio backend. If the address is not set, the default PulseAudio sound * server will be used, which is normally the local daemon. * - * This function will fail if the current state is either - * %MATE_MIXER_STATE_CONNECTING or %MATE_MIXER_STATE_READY, therefore you should - * use it before opening a connection to 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -687,24 +736,30 @@ mate_mixer_context_set_server_address (MateMixerContext *context, const gchar *a * mate_mixer_context_open: * @context: a #MateMixerContext * - * Opens connection to a sound system. Unless the backend type was given - * beforehand, the library will find a working sound system automatically. - * If the automatic discovery fails to find a working sound system, it will - * use the "Null" backend, which provides no functionality. + * 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. + * asynchronously and it may go through a series of connection + * #MateMixerContext: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 + * #MateMixerContext:state. * - * In case this function returns %TRUE, you should check the current state of - * the connection using mate_mixer_context_get_state(). If the current state - * is %MATE_MIXER_STATE_READY, the connection has been established successfully. - * Otherwise the state will be set to %MATE_MIXER_STATE_CONNECTING and the - * result of the operation will be determined asynchronously. You should wait - * for the state transition by connecting to the notification signal of the - * #MateMixerContext:state property. + * The %MATE_MIXER_STATE_READY state indicates, that the connection has been + * established successfully. * - * In case this function returns %FALSE, it is not possible to use the selected - * backend and the state will be set to %MATE_MIXER_STATE_FAILED. + * 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 #MateMixerContext:state will be set to %MATE_MIXER_STATE_FAILED. * * Returns: %TRUE on success or if the result will be determined asynchronously, * or %FALSE on failure. @@ -807,8 +862,8 @@ mate_mixer_context_open (MateMixerContext *context) * mate_mixer_context_close: * @context: a #MateMixerContext * - * Closes connection to the currently used sound system. The state will be - * set to %MATE_MIXER_STATE_IDLE. + * Closes an open connection to the sound system. The #MateMixerContext:state + * will be set to %MATE_MIXER_STATE_IDLE. */ void mate_mixer_context_close (MateMixerContext *context) @@ -823,9 +878,9 @@ mate_mixer_context_close (MateMixerContext *context) * mate_mixer_context_get_state: * @context: a #MateMixerContext * - * Gets the current backend connection state of the #MateMixerContext. + * Gets the state of the @context's connection to a sound system. * - * Returns: The current connection state. + * Returns: the connection state. */ MateMixerState mate_mixer_context_get_state (MateMixerContext *context) @@ -884,7 +939,7 @@ mate_mixer_context_get_stream (MateMixerContext *context, const gchar *name) * * Gets the stored control with the given name. * - * Returns: a #MateMixerStoredControl or %NULL if there is no such control. + * Returns: a #MateMixerStoredControl or %NULL if there is no such stored control. */ MateMixerStoredControl * mate_mixer_context_get_stored_control (MateMixerContext *context, const gchar *name) @@ -902,11 +957,10 @@ mate_mixer_context_get_stored_control (MateMixerContext *context, const gchar *n * mate_mixer_context_list_devices: * @context: a #MateMixerContext * - * Gets a list of devices. Each list item is a #MateMixerDevice representing a - * hardware or software sound device in the system. + * 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 #MateMixerContext and may be invalidated - * at any time. + * The returned #GList is owned by the library and may be invalidated at any time. * * Returns: a #GList of all devices in the system or %NULL if there are none or * you are not connected to a sound system. @@ -926,11 +980,14 @@ mate_mixer_context_list_devices (MateMixerContext *context) * mate_mixer_context_list_streams: * @context: a #MateMixerContext * - * Gets a list of streams. Each list item is a #MateMixerStream representing an - * input or output of a sound device. + * 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 #MateMixerContext and may be invalidated - * at any time. + * The returned #GList is owned by the library and may be invalidated at any time. * * Returns: a #GList of all streams in the system or %NULL if there are none or * you are not connected to a sound system. @@ -950,6 +1007,12 @@ mate_mixer_context_list_streams (MateMixerContext *context) * mate_mixer_context_list_stored_controls: * @context: a #MateMixerContext * + * 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. + * + * Returns: a #GList of stored controls or %NULL if there are none or you are not + * connected to a sound system. */ const GList * mate_mixer_context_list_stored_controls (MateMixerContext *context) @@ -966,11 +1029,10 @@ mate_mixer_context_list_stored_controls (MateMixerContext *context) * mate_mixer_context_get_default_input_stream: * @context: a #MateMixerContext * - * Gets the default input stream. The returned stream is where sound input is - * directed to by default. + * Gets the default input stream. The returned stream is where sound input + * most likely comes from by default. * - * Returns: a #MateMixerStream or %NULL if there are no input streams in - * the system. + * Returns: a #MateMixerStream or %NULL if there is no default input stream. */ MateMixerStream * mate_mixer_context_get_default_input_stream (MateMixerContext *context) @@ -988,8 +1050,10 @@ mate_mixer_context_get_default_input_stream (MateMixerContext *context) * @context: a #MateMixerContext * @stream: a #MateMixerStream to set as the default input stream * - * Changes the default input stream in the system. The @stream must be an - * input non-client 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -1016,7 +1080,7 @@ mate_mixer_context_set_default_input_stream (MateMixerContext *context, * @context: a #MateMixerContext * * Gets the default output stream. The returned stream is where sound output is - * directed to by default. + * most likely directed to by default. * * Returns: a #MateMixerStream or %NULL if there are no output streams in * the system. @@ -1037,8 +1101,10 @@ mate_mixer_context_get_default_output_stream (MateMixerContext *context) * @context: a #MateMixerContext * @stream: a #MateMixerStream to set as the default output stream * - * Changes the default output stream in the system. The @stream must be an - * output non-client 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. * * Returns: %TRUE on success or %FALSE on failure. */ @@ -1064,8 +1130,8 @@ mate_mixer_context_set_default_output_stream (MateMixerContext *context, * mate_mixer_context_get_backend_name: * @context: a #MateMixerContext * - * Gets the name of the currently used backend. This function will not - * work until connected to a sound system. + * Gets the name of the currently used sound system backend. This function will + * not work until connected to a sound system. * * Returns: the name or %NULL on error. */ @@ -1084,8 +1150,8 @@ mate_mixer_context_get_backend_name (MateMixerContext *context) * mate_mixer_context_get_backend_type: * @context: a #MateMixerContext * - * Gets the type of the currently used backend. This function will not - * work until connected to a sound system. + * Gets the type of the currently used sound system backend. This function will + * not work until connected to a sound system. * * Returns: the backend type or %MATE_MIXER_BACKEND_UNKNOWN on error. */ @@ -1103,6 +1169,11 @@ mate_mixer_context_get_backend_type (MateMixerContext *context) /** * mate_mixer_context_get_backend_flags: * @context: a #MateMixerContext + * + * Gets the capability flags of the currently used sound system backend. This + * function will not work until connected to a sound system. + * + * Returns: the capability flags. */ MateMixerBackendFlags mate_mixer_context_get_backend_flags (MateMixerContext *context) diff --git a/libmatemixer/matemixer-device.c b/libmatemixer/matemixer-device.c index 8144388..3944af5 100644 --- a/libmatemixer/matemixer-device.c +++ b/libmatemixer/matemixer-device.c @@ -90,6 +90,13 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) object_class->get_property = mate_mixer_device_get_property; object_class->set_property = mate_mixer_device_set_property; + /** + * MateMixerDevice:name: + * + * The name of the device. The name serves as a unique identifier and + * in most cases it is not in a user-readable form. + * + */ properties[PROP_NAME] = g_param_spec_string ("name", "Name", @@ -99,6 +106,12 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * MateMixerDevice:label: + * + * The label of the device. This is a potentially translated string + * that should be presented to users in the user interface. + */ properties[PROP_LABEL] = g_param_spec_string ("label", "Label", @@ -108,10 +121,15 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * MateMixerDevice:icon: + * + * The XDG icon name of the device. + */ properties[PROP_ICON] = g_param_spec_string ("icon", "Icon", - "Name of the sound device icon", + "XDG icon name of the device", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | @@ -119,6 +137,16 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) g_object_class_install_properties (object_class, N_PROPERTIES, properties); + /** + * MateMixerDevice::stream-added: + * @device: a #MateMixerDevice + * @name: name of the added stream + * + * The signal is emitted each time a device stream is added. + * + * Note that at the time this signal is emitted, the controls and switches + * of the stream may not yet be known. + */ signals[STREAM_ADDED] = g_signal_new ("stream-added", G_TYPE_FROM_CLASS (object_class), @@ -131,6 +159,18 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) 1, G_TYPE_STRING); + /** + * MateMixerDevice::stream-removed: + * @device: a #MateMixerDevice + * @name: name of the removed stream + * + * The signal is emitted each time a device 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_device_list_streams() function and it is not possible to get + * the stream with mate_mixer_device_get_stream(). + */ signals[STREAM_REMOVED] = g_signal_new ("stream-removed", G_TYPE_FROM_CLASS (object_class), @@ -143,6 +183,13 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) 1, G_TYPE_STRING); + /** + * MateMixerDevice::switch-added: + * @device: a #MateMixerDevice + * @name: name of the added switch + * + * The signal is emitted each time a device switch is added. + */ signals[SWITCH_ADDED] = g_signal_new ("switch-added", G_TYPE_FROM_CLASS (object_class), @@ -155,6 +202,18 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) 1, G_TYPE_STRING); + /** + * MateMixerDevice::switch-removed: + * @device: a #MateMixerDevice + * @name: name of the removed switch + * + * The signal is emitted each time a device switch is removed. + * + * When this signal is emitted, the switch is no longer known to the library, + * it will not be included in the switch list provided by the + * mate_mixer_device_list_switches() function and it is not possible to get + * the switch with mate_mixer_device_get_switch(). + */ signals[SWITCH_REMOVED] = g_signal_new ("switch-removed", G_TYPE_FROM_CLASS (object_class), @@ -251,6 +310,15 @@ mate_mixer_device_finalize (GObject *object) /** * mate_mixer_device_get_name: * @device: a #MateMixerDevice + * + * Gets the name of the device. The name serves as a unique identifier and + * in most cases it is not in a user-readable form. + * + * The returned name is guaranteed to be unique across all the known devices + * and may be used to get the #MateMixerDevice using + * mate_mixer_context_get_device(). + * + * Returns: the name of the device. */ const gchar * mate_mixer_device_get_name (MateMixerDevice *device) @@ -263,6 +331,11 @@ mate_mixer_device_get_name (MateMixerDevice *device) /** * mate_mixer_device_get_label: * @device: a #MateMixerDevice + * + * Gets the label of the device. This is a potentially translated string + * that should be presented to users in the user interface. + * + * Returns: the label of the device. */ const gchar * mate_mixer_device_get_label (MateMixerDevice *device) @@ -275,6 +348,10 @@ mate_mixer_device_get_label (MateMixerDevice *device) /** * mate_mixer_device_get_icon: * @device: a #MateMixerDevice + * + * Gets the XDG icon name of the device. + * + * Returns: the icon name. */ const gchar * mate_mixer_device_get_icon (MateMixerDevice *device) @@ -288,6 +365,10 @@ mate_mixer_device_get_icon (MateMixerDevice *device) * mate_mixer_device_get_stream: * @device: a #MateMixerDevice * @name: a stream name + * + * Gets the device stream with the given name. + * + * Returns: a #MateMixerStream or %NULL if there is no such stream. */ MateMixerStream * mate_mixer_device_get_stream (MateMixerDevice *device, const gchar *name) @@ -299,6 +380,17 @@ mate_mixer_device_get_stream (MateMixerDevice *device, const gchar *name) * mate_mixer_device_get_switch: * @device: a #MateMixerDevice * @name: a switch name + * + * Gets the device switch with the given name. + * + * Note that this function will only return a switch that belongs to the device + * and not to a stream of the device. See mate_mixer_device_list_switches() for + * information about the difference between device and stream switches. + * + * To get a stream switch, rather than a device switch, use + * mate_mixer_stream_get_switch(). + * + * Returns: a #MateMixerSwitch or %NULL if there is no such device switch. */ MateMixerSwitch * mate_mixer_device_get_switch (MateMixerDevice *device, const gchar *name) @@ -309,6 +401,14 @@ mate_mixer_device_get_switch (MateMixerDevice *device, const gchar *name) /** * mate_mixer_device_list_streams: * @device: a #MateMixerDevice + * + * Gets the list of streams that belong to the device. + * + * The returned #GList is owned by the #MateMixerDevice and may be invalidated + * at any time. + * + * Returns: a #GList of the device streams or %NULL if the device does not have + * any streams. */ const GList * mate_mixer_device_list_streams (MateMixerDevice *device) @@ -328,6 +428,21 @@ mate_mixer_device_list_streams (MateMixerDevice *device) /** * mate_mixer_device_list_switches: * @device: a #MateMixerDevice + * + * Gets the list of switches the belong to the device. + * + * Note that a switch may belong either to a device, or to a stream. Unlike + * stream switches, device switches returned by this function are not classified + * as input or output (as streams are), but they operate on the whole device. + * + * Use mate_mixer_stream_list_switches() to get a list of switches that belong + * to a stream. + * + * The returned #GList is owned by the #MateMixerDevice and may be invalidated + * at any time. + * + * Returns: a #GList of the device switches or %NULL if the device does not have + * any switches. */ const GList * mate_mixer_device_list_switches (MateMixerDevice *device) diff --git a/libmatemixer/matemixer-enums.h b/libmatemixer/matemixer-enums.h index 97d2f26..3f2fa44 100644 --- a/libmatemixer/matemixer-enums.h +++ b/libmatemixer/matemixer-enums.h @@ -26,10 +26,17 @@ /** * MateMixerState: * @MATE_MIXER_STATE_IDLE: + * Not connected. * @MATE_MIXER_STATE_CONNECTING: + * Connection is in progress. * @MATE_MIXER_STATE_READY: + * Connected successfully. * @MATE_MIXER_STATE_FAILED: + * Connection has failed. * @MATE_MIXER_STATE_UNKNOWN: + * Unknown state. This state is used as an error indicator. + * + * State of a connection to a sound system. */ typedef enum { MATE_MIXER_STATE_IDLE, @@ -45,8 +52,8 @@ typedef enum { * Unknown or undefined backend type. * @MATE_MIXER_BACKEND_PULSEAUDIO: * PulseAudio sound system backend. It has the highest priority and - * will be the first one to try unless you select a specific backend - * to connect to. + * 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: @@ -54,8 +61,10 @@ typedef enum { * @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 to connect to and all the - * "real" backends fail to initialize. + * if you do not select a specific backend and it isn't possible to use + * any of the other backends. + * + * Constants identifying a sound system backend. */ typedef enum { MATE_MIXER_BACKEND_UNKNOWN, @@ -77,6 +86,8 @@ typedef enum { * @MATE_MIXER_BACKEND_CAN_SET_DEFAULT_OUTPUT_STREAM: * The backend is able to change the current default output stream using * the mate_mixer_context_set_default_output_stream() function. + * + * Flags describing capabilities of a sound system. */ typedef enum { /*< flags >*/ MATE_MIXER_BACKEND_NO_FLAGS = 0, @@ -93,6 +104,8 @@ typedef enum { /*< flags >*/ * Input direction (recording). * @MATE_MIXER_DIRECTION_OUTPUT: * Output direction (playback). + * + * Sound stream direction. */ typedef enum { MATE_MIXER_DIRECTION_UNKNOWN, @@ -107,17 +120,30 @@ typedef enum { * @MATE_MIXER_STREAM_CONTROL_MUTE_READABLE: * The stream control includes a mute toggle and allows reading the mute state. * @MATE_MIXER_STREAM_CONTROL_MUTE_WRITABLE: + * The stream control includes a mute toggle and allows changing the mute state. * @MATE_MIXER_STREAM_CONTROL_VOLUME_READABLE: + * The stream control includes a volume control and allows reading the volume. * @MATE_MIXER_STREAM_CONTROL_VOLUME_WRITABLE: + * The stream control includes a volume control and allows changing the volume. * @MATE_MIXER_STREAM_CONTROL_CAN_BALANCE: + * The stream control includes the necessary channel positions to allow left/right + * volume balancing. * @MATE_MIXER_STREAM_CONTROL_CAN_FADE: + * The stream control includes the necessary channel positions to allow front/back + * volume fading. * @MATE_MIXER_STREAM_CONTROL_MOVABLE: * It is possible to move the stream control to a different stream using the * mate_mixer_stream_control_set_stream() function. See the function description * for details. * @MATE_MIXER_STREAM_CONTROL_HAS_DECIBEL: + * The stream controls supports decibel values and it is possible to successfully + * use the functions which operate on decibel values. * @MATE_MIXER_STREAM_CONTROL_HAS_MONITOR: + * The stream control supports peak level monitoring. * @MATE_MIXER_STREAM_CONTROL_STORED: + * The stream control is a #MateMixerStoredControl. + * + * Flags describing capabilities and properties of a stream control. */ typedef enum { MATE_MIXER_STREAM_CONTROL_NO_FLAGS = 0, @@ -133,6 +159,35 @@ typedef enum { MATE_MIXER_STREAM_CONTROL_STORED = 1 << 9 } MateMixerStreamControlFlags; +/** + * MateMixerStreamControlRole: + * @MATE_MIXER_STREAM_CONTROL_ROLE_UNKNOWN: + * Unknown role. + * @MATE_MIXER_STREAM_CONTROL_ROLE_MASTER: + * Master volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_APPLICATION: + * Application volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_PCM: + * PCM volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_SPEAKER: + * Speaker volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_MICROPHONE: + * Microphone volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_PORT: + * Volume control for a connector of a sound device. + * @MATE_MIXER_STREAM_CONTROL_ROLE_BOOST: + * Boost control (for example a microphone boost or bass boost). + * @MATE_MIXER_STREAM_CONTROL_ROLE_BASS: + * Bass control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_TREBLE: + * Treble control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_CD: + * CD input volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_VIDEO: + * Video volume control. + * @MATE_MIXER_STREAM_CONTROL_ROLE_MUSIC: + * Music volume control. + */ typedef enum { MATE_MIXER_STREAM_CONTROL_ROLE_UNKNOWN, MATE_MIXER_STREAM_CONTROL_ROLE_MASTER, @@ -149,6 +204,32 @@ typedef enum { MATE_MIXER_STREAM_CONTROL_ROLE_MUSIC } MateMixerStreamControlRole; +/** + * MateMixerStreamControlMediaRole: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN: + * Unknown media role. + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_VIDEO: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_MUSIC: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_GAME: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_EVENT: + * Event sounds. + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_PHONE: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_ANIMATION: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_PRODUCTION: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_A11Y: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_TEST: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_ABSTRACT: + * @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_FILTER: + * + * Constants describing a media role of a control. These constants are mapped + * to PulseAudio media role property and therefore only available when using the + * PulseAudio sound system. + * + * Media roles are commonly set by applications to indicate what kind of sound + * input/output they provide and may be the defining property of stored controls + * (for example an event role stored control can be used to provide a volume + * slider for event sounds). + */ typedef enum { MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN, MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_VIDEO, @@ -164,12 +245,30 @@ typedef enum { MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_FILTER } MateMixerStreamControlMediaRole; +/** + * MateMixerSwitchFlags: + * @MATE_MIXER_SWITCH_NO_FLAGS: + * No flags. + * @MATE_MIXER_SWITCH_TOGGLE: + * The switch is a #MateMixerToggle. + */ typedef enum { /*< flags >*/ MATE_MIXER_SWITCH_NO_FLAGS = 0, MATE_MIXER_SWITCH_TOGGLE = 1 << 0, MATE_MIXER_SWITCH_ALLOWS_NO_ACTIVE_OPTION = 1 << 1 } MateMixerSwitchFlags; +/** + * MateMixerSwitchRole: + * @MATE_MIXER_SWITCH_ROLE_UNKNOWN: + * Unknown switch role. + * @MATE_MIXER_SWITCH_ROLE_DEVICE_PROFILE: + * The switch changes the active sound device profile. + * @MATE_MIXER_SWITCH_ROLE_PORT: + * The switch changes the active port. + * @MATE_MIXER_SWITCH_ROLE_BOOST: + * The switch changes the boost value. + */ typedef enum { MATE_MIXER_SWITCH_ROLE_UNKNOWN, MATE_MIXER_SWITCH_ROLE_DEVICE_PROFILE, @@ -180,18 +279,29 @@ typedef enum { /** * MateMixerChannelPosition: * @MATE_MIXER_CHANNEL_UNKNOWN: + * Unknown channel position. * @MATE_MIXER_CHANNEL_MONO: + * Mono channel. Only used for single-channel controls. * @MATE_MIXER_CHANNEL_FRONT_LEFT: + * Front left channel. * @MATE_MIXER_CHANNEL_FRONT_RIGHT: + * Front right channel. * @MATE_MIXER_CHANNEL_FRONT_CENTER: + * Front center channel. * @MATE_MIXER_CHANNEL_LFE: + * Low-frequency effects channel (subwoofer). * @MATE_MIXER_CHANNEL_BACK_LEFT: + * Back (rear) left channel. * @MATE_MIXER_CHANNEL_BACK_RIGHT: + * Back (rear) right channel. * @MATE_MIXER_CHANNEL_BACK_CENTER: + * Back (rear) center channel. * @MATE_MIXER_CHANNEL_FRONT_LEFT_CENTER: * @MATE_MIXER_CHANNEL_FRONT_RIGHT_CENTER: * @MATE_MIXER_CHANNEL_SIDE_LEFT: + * Side left channel. * @MATE_MIXER_CHANNEL_SIDE_RIGHT: + * Side right channel. * @MATE_MIXER_CHANNEL_TOP_FRONT_LEFT: * @MATE_MIXER_CHANNEL_TOP_FRONT_RIGHT: * @MATE_MIXER_CHANNEL_TOP_FRONT_CENTER: @@ -221,6 +331,7 @@ typedef enum { MATE_MIXER_CHANNEL_TOP_BACK_LEFT, MATE_MIXER_CHANNEL_TOP_BACK_RIGHT, MATE_MIXER_CHANNEL_TOP_BACK_CENTER, + /*< private >*/ MATE_MIXER_CHANNEL_MAX } MateMixerChannelPosition; diff --git a/libmatemixer/matemixer-switch.c b/libmatemixer/matemixer-switch.c index e50d416..a262e88 100644 --- a/libmatemixer/matemixer-switch.c +++ b/libmatemixer/matemixer-switch.c @@ -336,7 +336,7 @@ mate_mixer_switch_set_active_option (MateMixerSwitch *swtch, } /** - * mate_mixer_switch_get_name: + * mate_mixer_switch_list_options: * @swtch: a #MateMixerSwitch */ const GList * diff --git a/libmatemixer/matemixer.c b/libmatemixer/matemixer.c index a5bca6f..ce39ccc 100644 --- a/libmatemixer/matemixer.c +++ b/libmatemixer/matemixer.c @@ -28,8 +28,8 @@ /** * SECTION:matemixer * @short_description: Library initialization and support functions - * @title: MateMixer * @include: libmatemixer/matemixer.h + * @see_also: #MateMixerContext */ static void load_modules (void); |