[gnome-settings-daemon] media-keys: Add some D-Bus API documentation

[Bastien Nocera <hadess src gnome org>]

commit 92561b405109d5583cd48b9afd1259efe55e600a
Author: Bastien Nocera <hadess hadess net>
Date:   Mon Oct 3 17:04:01 2011 +0100

    media-keys: Add some D-Bus API documentation

 plugins/media-keys/README.media-keys-API |   51 ++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)
---
diff --git a/plugins/media-keys/README.media-keys-API b/plugins/media-keys/README.media-keys-API
new file mode 100644
index 0000000..55d1a59
--- /dev/null
+++ b/plugins/media-keys/README.media-keys-API
@@ -0,0 +1,51 @@
+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.
+