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.


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);
}