GSoundContext: GSound Reference Manual

## GSoundContext GSoundContext — GSound context object |

## Functions

#define | GSOUND_ERROR
GQuark | gsound_error_quark ()
GSoundContext * | gsound_context_new ()
gboolean | gsound_context_open ()
gboolean | gsound_context_set_attributes ()
gboolean | gsound_context_set_attributesv ()
gboolean | gsound_context_set_driver ()
gboolean | gsound_context_play_simple ()
gboolean | gsound_context_play_simplev ()
void | gsound_context_play_full ()
void | gsound_context_play_fullv ()
gboolean | gsound_context_play_full_finish ()
gboolean | gsound_context_cache ()
gboolean | gsound_context_cachev ()

## Types and Values

enum | GSoundError
| GSoundContext

## Object Hierarchy

        GObject
        ╰── GSoundContext

## Implemented Interfaces

GSoundContext implements GInitable.

## Description

A GSoundContext is used for playing system sounds. The typical use pattern is:

- Initialize the GSoundContext

- [Optional] Set any global attributes using `gsound_context_set_attributes()`

- [Optional] Cache any frequently-used sounds (for example, sound effects for a game) using `gsound_context_cache()`

- Play sounds using `gsound_context_play_simple()` or `gsound_context_play_full()`

- Close the connection to the sound server and clean up the context using `g_object_unref()`

GSoundContext implements the GInitable interface, so if created with `g_object_new()` (as typically happens with language bindings) then you must call the `g_initable_init()` method before attempting to use it.

### Simple Examples

In C:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    GSoundContext *ctx = NULL;
    GCancellable *cancellable = g_cancellable_new();
    GError *error = NULL;

    ctx = gsound_context_new(cancellable, &error);
    if (error) {
        // handle error
    }

    gsound_context_play_simple(ctx, cancellable, &error,
                               GSOUND_ATTR_EVENT_ID, "phone-incoming-call",
                               // other attributes...
                               NULL);

or, using Python via GObject Introspection:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    from gi.repository import GSound

    ctx = GSound.Context()

    try:
        ctx.init();
        ctx.play_simple({ GSound.ATTR_EVENT_ID : "phone-incoming-call" })
    except:
        # Handle error
        pass

or using Vala:

    1
    2
    3
    4
    5
    6
    try {
        var ctx = new GSound.Context();
        ctx.play_simple(null, GSound.Attribute.EVENT_ID, "phone-incoming-call");
    } catch (Error e) {
        // handle error
    }

### ``play_simple()`` versus ``play_full()``

The above examples use the `gsound_context_play_simple()` method for playing sounds. This is a "fire and forget" method which returns immediately and does not block your program, and is suitable for most use cases.

If you need to find out when the sound finished (for example to repeat the sound) then you can use the `gsound_context_play_full()` version. This is an asynchronous method using the standard GIO async pattern, which will run the supplied GAsyncReadyCallback when the sound server has finished. It is guaranteed that the callback will be run exactly once.

Note that calling `gsound_context_play_full()` with a `NULL` callback is not equivalent to calling `gsound_context_play_simple()`. When calling `play_simple()`, errors which occur before the sound is passed to the sound server are reported immediately, whereas with ``play_full()`` these are reported in the callback. If you pass a `NULL` callback to `gsound_context_play_full()` you will not be able to receive these errors, so it is strongly recommended to avoid doing this and use `gsound_context_play_simple()` in the case when you don't need to be notified when the sound has finished.

### Passing Attributes

GSound supplies information to the sound server by means of attributes. Attributes can be set on the GSoundContext itself using `gsound_context_set_attributes()`, or supplied in a ``play()`` call. Attributes set on the context will automatically applied to any subsequent ``play()`` calls, unless overridden by that call.

In C and Vala, attributes are passed as `NULL`-terminated list of (attribute, value) pairs. When using GObject introspection, attributes are typically passed using a language-specific associated array, for example a dict in Python or an object in JavaScript.

For the list of attributes supported by GSound, see GSound Attributes.

### Caching

If supported by the sound server, frequently-used sounds may be cached. This may be useful, for example, for sound effects in a game. To cache a sound, either call `gsound_context_cache()`, or pass the special GSOUND_ATTR_CANBERRA_CACHE_CONTROL attribute to one of the ``play()`` functions.

For example, in the startup code for a game you might include something like the following (error checking omitted):

    1
    2
    3
    4
    5
    GSoundContext *ctx = gsound_context_new (NULL, NULL);
    gsound_context_cache(ctx, NULL,
                         GSOUND_ATTR_MEDIA_FILENAME,
                         "/path/to/player-spaceship-fire-laser.ogg",
                         NULL);

There are three caching modes available, "permanent", "volatile" and "never". The default mode when calling `gsound_context_cache()` is "permanent", and the default mode for `gsound_context_play_simple()` and ``play_full()`` is "never".

See the documentation for GSOUND_ATTR_CANBERRA_CACHE_CONTROL for more details.

## Functions

### GSOUND_ERROR

    #define GSOUND_ERROR (gsound_error_quark())

### gsound_error_quark ()

    GQuark
    gsound_error_quark (void);

### gsound_context_new ()

    GSoundContext *
    gsound_context_new (GCancellable *cancellable,
                        GError **error);

Creates and initializes a new GSoundContext. If the an error occured during initialization, NULL is returned and `error` will be set appropriately.

#### Parameters

cancellable | A GCancellable, or `NULL`. | [allow-none]
error | Return location for error |

#### Returns

A new GSoundContext.

[transfer full]

### gsound_context_open ()

    gboolean
    gsound_context_open (GSoundContext *context,
                         GError **error);

Attempts to open a connection to the backend sound driver. It is recommended that you set context attributes with `gsound_context_set_attributes()` before calling this function.

> A connection is automatically opened before playing or caching sounds, so you rarely need to call this yourself.

#### Parameters

context | A GSoundContext |
error | Return location for error |

#### Returns

`TRUE` if the output device was opened successfully, or `FALSE` (populating `error` )

### gsound_context_set_attributes ()

    gboolean
    gsound_context_set_attributes (GSoundContext *context,
                                   GError **error,
                                   ...);

Set attributes or change attributes on `context` . Subsequent calls to this function calling the same attributes will override the earlier values.

Note that GSound will set the GSOUND_ATTR_APPLICATION_NAME and GSOUND_ATTR_APPLICATION_ID for you if using GApplication, so you do not normally need to set these yourself.

[skip]

#### Parameters

context | A GSoundContext |
error | Return location for error |
... | `NULL` terminated list of attribute name-value pairs |

#### Returns

`TRUE` if attributes were updated successfully

### gsound_context_set_attributesv ()

    gboolean
    gsound_context_set_attributesv (GSoundContext *context,
                                    GHashTable *attrs,
                                    GError **error);

Set attributes or change attributes on `context` . Subsequent calls to this function calling the same attributes will override the earlier values.

Note that GSound will set the GSOUND_ATTR_APPLICATION_NAME and GSOUND_ATTR_APPLICATION_ID for you if using GApplication, so you do not normally need to set these yourself.

This function is intented to be used by language bindings.

[rename-to gsound_context_set_attributes]

#### Parameters

context | A GSoundContext |
attrs | Hash table of attributes to set. | [element-type utf8 utf8]
error | Return location for error, or `NULL` |

#### Returns

`TRUE` if attributes were updated successfully

### gsound_context_set_driver ()

    gboolean
    gsound_context_set_driver (GSoundContext *context,
                               const char *driver,
                               GError **error);

Sets the libcanberra driver to `driver` , for example "pulse", "alsa" or "null". You normally do not need to set this yourself.

Note that this function may return `TRUE` even if the specified driver is not available: see the libcanberra documentation for details.

#### Parameters

context | A GSoundContext |
driver | libcanberra driver to use |
error | Return location for error, or `NULL` |

#### Returns

`TRUE` if the libcanberra driver was set successfully

### gsound_context_play_simple ()

    gboolean
    gsound_context_play_simple (GSoundContext *context,
                                GCancellable *cancellable,
                                GError **error,
                                ...);

The basic "fire-and-forget" play command. This function will not block, and just sends a request to the sound server before immediately returning.

If you need to know when a sound finishes playing then you should call `gsound_context_play_full()` instead.

You can cancel playback at any time by calling `g_cancellable_cancel()` on `cancellable` , if supplied.

[skip]

#### Parameters

context | A GSoundContext |
cancellable | A GCancellable, or `NULL`. | [allow-none]
error | Return location for error, or `NULL` |
... | A `NULL`-terminated list of attribute-value pairs |

#### Returns

`TRUE` on success, or `FALSE`, populating `error`

### gsound_context_play_simplev ()

    gboolean
    gsound_context_play_simplev (GSoundContext *context,
                                 GHashTable *attrs,
                                 GCancellable *cancellable,
                                 GError **error);

The basic "fire-and-forget" play command. This function will not block, and just sends a request to the sound server before immediately returning.

If you need to know when a sound finishes playing then you should call `gsound_context_play_full()` instead.

You can cancel playback at any time by calling `g_cancellable_cancel()` on `cancellable` , if supplied.

This function is intented to be used by language bindings.

[rename-to gsound_context_play_simple]

#### Parameters

context | A GSoundContext |
attrs | Attributes. | [element-type utf8 utf8]
cancellable | A GCancellable. | [allow-none]
error | Return location for error |

#### Returns

`TRUE` on success, `FALSE` on error

### gsound_context_play_full ()

    void
    gsound_context_play_full (GSoundContext *context,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data,
                              ...);

Asynchronously request a sound to be played. When playback is finished (or if an error occurs) then `callback` will be called, following the normal GIO async pattern.

If playback is cancelled via `cancellable` , then `callback` will be called with G_IO_ERROR_CANCELLED.

If you do not need notification of when playback is complete, you should use `gsound_context_play_simple()`.

[skip]

#### Parameters

context | A GSoundContext |
cancellable | A GCancellable, or `NULL`. | [allow-none]
callback | callback. | [scope async]
user_data | User data passed to `callback` |
... | A `NULL`-terminated list of attribute-value pairs |

### gsound_context_play_fullv ()

    void
    gsound_context_play_fullv (GSoundContext *context,
                               GHashTable *attrs,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Asynchronously request a sound to be played. When playback is finished (or if an error occurs) then `callback` will be called, following the normal GIO async pattern.

If playback is cancelled via `cancellable` , then `callback` will be called with G_IO_ERROR_CANCELLED.

If you do not need notification of when playback is complete, you should use `gsound_context_play_simple()`.

This function is intented to be used by language bindings.

[rename-to gsound_context_play_full]

#### Parameters

context | A GSoundContext |
attrs | Attributes. | [element-type utf8 utf8]
cancellable | A GCancellable, or `NULL`. | [allow-none]
callback | callback. | [scope async]
user_data | user_data |

### gsound_context_play_full_finish ()

    gboolean
    gsound_context_play_full_finish (GSoundContext *context,
                                     GAsyncResult *result,
                                     GError **error);

Finish an async operation started by `gsound_context_play_full()`. You must call this function in the callback to free memory and receive any errors which occurred.

#### Parameters

context | A GSoundContext |
result | Result object passed to the callback of `gsound_context_play_full()` |
error | Return location for error |

#### Returns

`TRUE` if playing finished successfully

### gsound_context_cache ()

    gboolean
    gsound_context_cache (GSoundContext *context,
                          GError **error,
                          ...);

Requests that a sound be cached on the server. See caching.

[skip]

#### Parameters

context | A GSoundContext |
error | Return location for error |
... | A `NULL`-terminated list of attribute-value pairs |

#### Returns

`TRUE` on success

### gsound_context_cachev ()

    gboolean
    gsound_context_cachev (GSoundContext *context,
                           GHashTable *attrs,
                           GError **error);

Requests that a sound be cached on the server. See caching.

This function is intented to be used by language bindings.

[rename-to gsound_context_cache]

#### Parameters

context | A GSoundContext |
attrs | Hash table of attrerties. | [element-type utf8 utf8]
error | Return location for error, or `NULL` |

## Types and Values

### enum GSoundError

#### Members

GSOUND_ERROR_NOTSUPPORTED |  |
GSOUND_ERROR_INVALID |  |
GSOUND_ERROR_STATE |  |
GSOUND_ERROR_OOM |  |
GSOUND_ERROR_NODRIVER |  |
GSOUND_ERROR_SYSTEM |  |
GSOUND_ERROR_CORRUPT |  |
GSOUND_ERROR_TOOBIG |  |
GSOUND_ERROR_NOTFOUND |  |
GSOUND_ERROR_DESTROYED |  |
GSOUND_ERROR_CANCELED |  |
GSOUND_ERROR_NOTAVAILABLE |  |
GSOUND_ERROR_ACCESS |  |
GSOUND_ERROR_IO |  |
GSOUND_ERROR_INTERNAL |  |
GSOUND_ERROR_DISABLED |  |
GSOUND_ERROR_FORKED |  |
GSOUND_ERROR_DISCONNECTED |  |

### GSoundContext

    typedef struct _GSoundContext GSoundContext;

Wrapper for ca_context.

## See Also

ca_context