Add Playlists interface

2 files changed, 189 insertions, 1 deletions

diff --git a/spec/Playlists.xml b/spec/Playlists.xml
new file mode 100644
index 0000000..4628d3b
--- /dev/null
+++ b/spec/Playlists.xml
@@ -0,0 +1,173 @@
+<?xml version="1.0" ?>
+<node name="/Playlists" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <interface name="org.mpris.MediaPlayer2.Playlists">
+    <tp:docstring>
+      <p>Provides access to the media player's playlists.</p>
+      <p>
+        Since D-Bus does not provide an easy way to check for what interfaces
+        are exported on an object, clients should attempt to get one of the
+        properties on this interface to see if it is implemented.
+      </p>
+    </tp:docstring>
+
+    <tp:simple-type name="Playlist_Id" type="o" array-name="Playlist_Id_List">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Unique playlist identifier.</p>
+        <tp:rationale>
+          <p>
+            Multiple playlists may have the same name.
+          </p>
+          <p>
+            This is a D-Bus object id as that is the definitive way to have
+            unique identifiers on D-Bus.  It also allows for future optional
+            expansions to the specification where tracks are exported to D-Bus
+            with an interface similar to org.gnome.UPnP.MediaItem2.
+          </p>
+        </tp:rationale>
+      </tp:docstring>
+    </tp:simple-type>
+
+    <tp:simple-type name="Uri" type="s" array-name="Uri_List">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A URI.</p>
+      </tp:docstring>
+    </tp:simple-type>
+
+    <tp:struct name="Playlist" array-name="Playlist_List">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A data structure describing a playlist.</p>
+      </tp:docstring>
+      <tp:member type="o" tp:type="Playlist_Id" name="Id">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A unique identifier for the playlist.</p>
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The name of the playlist, typically given by the user.</p>
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" tp:type="Uri" name="Icon">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The URI of an (optional) icon.</p>
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:enum name="Playlist_Ordering" array-name="Playlist_Ordering_List" type="s">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Specifies the ordering of returned playlists.</p>
+      </tp:docstring>
+      <tp:enumvalue suffix="Alphabetical" value="Alphabetical">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Alphabetical ordering by name, ascending.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="CreationDate" value="Created">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Ordering by creation date, oldest first.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="ModifiedDate" value="Modified">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Ordering by last modified date, oldest first.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="LastPlayDate" value="Played">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Ordering by date of last playback, oldest first.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <method name="ActivatePlaylist" tp:name-for-bindings="Activate_Playlist">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>
+          Starts playing the given playlist.
+        </p>
+        <p>
+          Note that this must be implemented.  If the media player does not
+          allow clients to change the playlist, it should not implement this
+          interface at all.
+        </p>
+        <p>
+          It is up to the media player whether this completely replaces the
+          current tracklist, or whether it is merely inserted into the
+          tracklist and the first track starts.  For example, if the media
+          player is operating in a "jukebox" mode, it may just append the
+          playlist to the list of upcoming tracks, and skip to the first
+          track in the playlist.
+        </p>
+      </tp:docstring>
+      <arg direction="in" name="PlaylistId" type="o">
+        <tp:docstring>
+          <p>The id of the playlist to activate.</p>
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <method name="GetPlaylists" tp:name-for-bindings="Get_Playlists">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Gets a set of playlists.</p>
+      </tp:docstring>
+      <arg direction="in" name="Index" type="u">
+        <tp:docstring>
+          <p>The index of the first playlist to be fetched (according to the ordering).</p>
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="MaxCount" type="u">
+        <tp:docstring>
+          <p>The maximum number of playlists to fetch.</p>
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="Order" type="s" tp:type="Playlist_Ordering">
+        <tp:docstring>
+          <p>The ordering that should be used.</p>
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="ReverseOrder" type="b">
+        <tp:docstring>
+          <p>Whether the order should be reversed.</p>
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="Playlists" type="a(oss)" tp:type="Playlist[]">
+        <tp:docstring>
+          <p>A list of (at most MaxCount) playlists.</p>
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <property name="PlaylistCount" type="u" tp:name-for-bindings="Playlist_Count" access="read">
+      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>
+          The number of playlists available.
+        </p>
+        <p>
+          When this property changes, the
+          <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
+          signal is emited with the new value.
+        </p>
+      </tp:docstring>
+    </property>
+
+    <property name="Orderings" tp:name-for-bindings="Orderings" type="as" tp:type="Playlist_Ordering[]" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>
+          The available orderings.  This must include Alphabetical and either
+          Created or Modified at a minimum.
+        </p>
+        <tp:rationale>
+          <p>
+            Media players may not have access to all the data required for some
+            orderings.  For example, creation times are not available on UNIX
+            filesystems (don't let the ctime fool you!).  On the other hand,
+            clients should have some way to get the "most recent" playlists.
+          </p>
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/all.xml b/spec/all.xml
index 883869c..3717b24 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <tp:title>MPRIS D-Bus Interface Specification</tp:title>
-  <tp:version>2.0</tp:version>
+  <tp:version>2.1</tp:version>
 
   <tp:copyright>
     Copyright © 2006-2010 the VideoLAN team
@@ -53,6 +53,15 @@
     </tp:docstring>
   </tp:section>
 
+  <tp:section name="Changes">
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <dl>
+        <dt>From 2.0 to 2.1:</dt>
+        <dd>Added the optional <b>org.mpris.MediaPlayer2.Playlists</b> interface.</dd>
+      </dl>
+    </tp:docstring>
+  </tp:section>
+
   <tp:section name="Bus Name Policy">
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>
@@ -103,6 +112,11 @@
         the <strong>org.mpris.MediaPlayer2.TrackList</strong> interface.
       </p>
 
+      <p>
+        The <strong>/org/mpris/MediaPlayer2</strong> object may implement
+        the <strong>org.mpris.MediaPlayer2.Playlists</strong> interface.
+      </p>
+
     </tp:docstring>
   </tp:section>
 
@@ -124,6 +138,7 @@
     <xi:include href="Root_Node.xml" />
     <xi:include href="TrackList_Node.xml" />
     <xi:include href="Player_Node.xml" />
+    <xi:include href="Playlists.xml" />
   </tp:section>
 
 </tp:spec>