hal/doc/spec hal-spec.xml.in,1.70,1.71

[David Zeuthen]

Update of /cvs/hal/hal/doc/spec
In directory kemper:/tmp/cvs-serv21468/doc/spec

Modified Files:
	hal-spec.xml.in 
Log Message:
2006-04-26  David Zeuthen  <davidz at redhat.com>

        Patch from Gabriel Burt <gabriel.burt at gmail.com>.

        After some further consideration, I think the
        portable_audio_player.filepath_format property should be removed
        and a new property, folder_depth, should be created.  The main
        point of the filepath_format property was to convey whether the
        device only supported a limited file hierarchy, but it ended up
        conveying much more than that - specifying exactly what directory
        structure the music files should go in, when that's really not
        appropriate (since the hardware doesn't care except in the
        hierarchy depth case).  The folder to write files out to can be
        taken from the first entry in the audio_folders property.  This
        change will allow the application to choose the appropriate
        directory structure (/podcasts/NPR/****, /Artist/Album/00 - Title,
        etc). I've attached a patch that make this change in the
        hal-spec.xml.in as well as another patch that adds some of these
        new properties for a few audio devices.

        * doc/spec/hal-spec.xml.in: Update spec

        * fdi/information/10freedesktop/10-usb-music-players.fdi: Update
        to reflect new spec



Index: hal-spec.xml.in
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.xml.in,v
retrieving revision 1.70
retrieving revision 1.71
diff -u -d -r1.70 -r1.71
--- hal-spec.xml.in	17 Apr 2006 14:59:51 -0000	1.70
+++ hal-spec.xml.in	26 Apr 2006 15:00:38 -0000	1.71
@@ -3844,18 +3844,16 @@
             </row>
 
             <row>
-              <entry><literal>portable_audio_player.filepath_format</literal> (string)</entry>
-              <entry>examples: MUSIC/%Track or %Artist/%Album/%Track or mp3s/%Artist/%Album - %Track</entry>
+              <entry><literal>portable_audio_player.folder_depth </literal> (int)</entry>
+              <entry>example: 1 (If the device only supports one sub-folder)</entry>
               <entry>No</entry>
               <entry>
                 If portable_audio_player.access_method = "storage",
-                this may contain a string that will be used to format the file's name
-                and path before writing it to the device.  If audio files must be placed
-                in a particular subdirectory, or the device only allows one
-                sub-directory deep hierarchies, that information should be embedded
-                here. The variables available for this string are %Artist, %Album, and %Track.
-                Applications using this key are responsible for substituting the
-                appropriate values for these variables when formatting the file's path.
+                this tells applications how deep of directory hierarchies
+                files can be placed in.  If all files are put in a
+                sub-folder (with the audio_folders property), that folder
+                should not be included in the folder_depth.  If the device
+                does not have a limit, do not set this property.
 	          </entry>
             </row>
 
@@ -3866,7 +3864,14 @@
               <entry>
                 If portable_audio_player.access_method = "storage",
                 this may contain a string list of folders in which music
-                can be found.  Paths are relative to the mount point of the device.
+                can be found.  Paths are relative to the mount point of the
+                device. If there is one or more entry in this property, the
+                first one is where files will be written to by applications.
+
+                Do not enter a folder and a parent of that folder.
+
+                If the device places files in its root directory, then do not
+                set this property.
 	          </entry>
             </row>