README

Nemo Mobile Audio Resource API
==============================

This library provides a way to acquire audio resources for playback on Nemo
Mobile and Sailfish, as well as a way to get notified when audio resources
have been released, in which case audio playback must be stopped.

Audio resources for your application might be released in case of an incoming
call, alarm sound, other applications playing music, etc.. - by only playing
back audio when the resource is acquired, an application developer can make
sure that the application is well-behaving, and also react to these events in
the user interface (e.g. by simulating a "pause" press in a player UI).

For actually playing back audio, use libpulse or libpulse-simple.

Third party applications that expect a stable API/ABI for resource management
should use this library - lower-level libraries such as libresource (which this
library currently uses as its backend) are considered an implementation detail
and could be replaced or removed in the future.

Please note that you need to have a GLib main loop running to use the functions
of libaudioresource, as it's asynchronous and uses GLib in the backend. If your
application is a Qt application, it automatically has a GLib main loop. If your
application doesn't use a GLib main loop, you can use:

    // ...
    audioresource_acquire(resource);
    while (!got_reply) {
        g_main_context_iteration(NULL, false);
    }
    // ...

And in the callback, set the "got_reply" variable to true, so you know when
the reply is done. If you don't want to wait for a reply, you can also add
the following to your custom main loop, once per iteration:

    g_main_context_iteration(NULL, false);


Example Usage
-------------

#include <audioresource.h>

void on_acquired(audioresource_t *audio_resource, bool acquired, void *user_data)
{
    if (acquired) {
        // start playback here
    } else {
        // stop playback here
    }
}

int main(int argc, char *argv[])
{
    audioresource_t *resource;

    // You can pass in a application-specific pointer that will be
    // provided as "user_data" to the on_acquired() callback above
    void *user_data = NULL;

    // Initialize the resource for a game
    resource = audioresource_init(AUDIO_RESOURCE_GAME, on_acquired, user_data);

    // When you want to start playback
    audioresource_acquire(resource);

    while (true) {
        // game loop, etc..
    }

    // When you want to stop playback
    audioresource_release(resource);

    // When you close your application
    audioresource_free(resource);
}