From f9c693e602231e77eee94580addf60eff095b2de Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@duempel.org>
Date: Mon, 19 Jan 2009 19:09:49 +0100
Subject: command: added "sticker" command

The "sticker" command allows clients to query or manipulate the
sticker database.  This patch implements the sub-commands "get" and
"set"; more will follow soon (enumeration), as well as extended
"lsinfo" / "playlistinfo" versions.
---
 doc/protocol.xml | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

(limited to 'doc')

diff --git a/doc/protocol.xml b/doc/protocol.xml
index ff5d4838f..36ee3c35d 100644
--- a/doc/protocol.xml
+++ b/doc/protocol.xml
@@ -1155,6 +1155,73 @@ OK
       </variablelist>
     </section>
 
+    <section>
+      <title>Stickers</title>
+
+      <para>
+        "Stickers" are pieces of information attached to existing MPD
+        objects (e.g. song files, directories, albums).  Clients can
+        create arbitrary name/value pairs.  MPD itself does not assume
+        any special meaning in them.
+      </para>
+
+      <para>
+        The goal is to allow clients to share additional (possibly
+        dynamic) information about songs, which is neither stored on
+        the client (not available to other clients), nor stored in the
+        song files (MPD has no write access).
+      </para>
+
+      <para>
+        Client developers should create a standard for common sticker
+        names, to ensure interoperability.
+      </para>
+
+      <para>
+        Objects which may have stickers are addressed by their object
+        type ("song" for song objects) and their URI (the path within
+        the database for songs).
+      </para>
+
+      <variablelist>
+        <varlistentry id="command_sticker_get">
+          <term>
+            <cmdsynopsis>
+              <command>sticker</command>
+              <arg choice="plain">get</arg>
+              <arg choice="req"><replaceable>TYPE</replaceable></arg>
+              <arg choice="req"><replaceable>URI</replaceable></arg>
+              <arg choice="req"><replaceable>NAME</replaceable></arg>
+            </cmdsynopsis>
+          </term>
+          <listitem>
+            <para>
+              Reads a sticker value for the specified object.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry id="command_sticker_set">
+          <term>
+            <cmdsynopsis>
+              <command>sticker</command>
+              <arg choice="plain">set</arg>
+              <arg choice="req"><replaceable>TYPE</replaceable></arg>
+              <arg choice="req"><replaceable>URI</replaceable></arg>
+              <arg choice="req"><replaceable>NAME</replaceable></arg>
+              <arg choice="req"><replaceable>VALUE</replaceable></arg>
+            </cmdsynopsis>
+          </term>
+          <listitem>
+            <para>
+              Adds a sticker value to the specified object.  If a
+              sticker item with that name already exists, it is
+              replaced.
+            </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </section>
+
     <section>
       <title>Connection settings</title>
 
-- 
cgit v1.2.3