This is very simple documentation to gnome-settings-daemon's
D-Bus API for media players.

gnome-settings-daemon will send key press events from multimedia
keys to applications that register their interest in those events.
This allows the play/pause button to control an audio player that's
not focused for example.

The D-Bus API is described in gsd-media-keys-manager.c (look for
introspection_xml), but a small explanation follows here.

1. Create yourself a proxy object for the remote interface:
Object path: /org/gnome/SettingsDaemon/MediaKeys
D-Bus name: org.gnome.SettingsDaemon.MediaKeys
Interface name: org.gnome.SettingsDaemon.MediaKeys

2. Register your application with gnome-settings-daemon
GrabMediaPlayerKeys ("my-application", 0)
with the second argument being the current time (usually 0,
or the time passed to you from an event, such as a mouse click)

3. Listen to the MediaPlayerKeyPressed() signal

4. When receiving a MediaPlayerKeyPressed() signal,
check whether the first argument (application) matches
the value you passed to GrabMediaPlayerKeys() and apply the
action depending on the key (2nd argument)

Possible values of key are:
- Play
- Pause
- Stop
- Previous
- Next
- Rewind
- FastForward
- Repeat
- Shuffle

5. Every time your application is focused, you should call
GrabMediaPlayerKeys() again, so that gnome-settings-daemon knows
which one was last used. This allows switching between a movie player
and a music player, for example, and have the buttons control the
last used application.

6. When your application wants to stop using the functionality
it can call ReleaseMediaPlayerKeys(). If your application does
not call ReleaseMediaPlayerKeys() and releases its D-Bus connection
then the application will be automatically removed from the list of
applications held by gnome-settings-daemon.

