Description of XML-tags in XBSMP
--------------------------------

File Information Tags
---------------------

Following section describes the XML holding the information of the
directory entry (e.g. directory or file).  If needed, entire file
information lock can be enclosed with DIRECTORYITEM tag.

  NAME (mandatory)

     - Contains a string that is a free form string representation of 
       the name of the item
     - Name doesn't have to be unique within the directory (i.e. it
       doesn't have to map directly to the actual name of the file
     - Name should be used for example in menus
     - Name must not be used in further accessing the file but instead
       the real filename (acquired outside this XML) should be used

  PATHNAME (optional)

     - Section contains a real pathname of the item (relative to
       server root)
     - PATHNAME components are splitted to COMPONENT sections
     - PATHNAME section has a DEPTH argument with integer value
       that tells how many components are present in the PATHNAME
     - Each COMPONENT section has a LEVEL argument with integer
       value telling which level of the hierarchy, COMPONENT
       describes.
     - COMPONENT for each level from 1 to DEPTH has to be present.
     - Filename in COMPONENT has to be quoted so that it does not 
       break XML syntax.

  ATTRIB (mandatory)

     - Contains one string from following set:

         tag value         description
        ----------------------------------------------------------
         directory         item is a directory
         file              item is a regular file
         stream            item is a data stream
         option            item is a configuration option that can be 
                           updated by the client
         readonlyoption    item is a configuration option that can't be
                           updated by the client

     - If multiple attributes applies to single item, multiple
       ATTRIB tags can be present

  INFO (optional)

     - Contains a free form textual information of the item.

  SIZE (optional)

     - Contains one nonnegative integer that is the size of item.
     - Relevant only if the item is a regular file

  TIME (optional)

     - Contains information about file access times.
     - Each subtag holds one integer that represents seconds that has
       passed from Jan 1 1970 00:00 UTC excluding leap seconds.
       Negative values are legal but should not be used.
     - Subtag names are
         o ACCESS       - Last time the file was accessed (read)
         o MODIFICATION - Last time the file was modified (write)
         o CHANGE       - Last time the file metadata was
                          modified (e.g. chmod)

  OPTIONVALUE (optional)

     - Contains the value of the configuration option, given that
       ATTRIB is option or readonlyoption.
     - Option value string has to be quoted so that it does not
       break XML syntax.

  LEGALOPTIONVALUES (optional)

     - Contains the set of legal option value for the given option,
       given that ATTRIB value "option" is present.
     - Each possible option value is in OPTIONVALUE subtag.


DTD for DIRECTORYITEM XML
-------------------------

<?xml version="1.0"?>
<!DOCTYPE DIRECTORYITEM [
  <!ELEMENT DIRECTORYITEM      (NAME,
                                PATHNAME?,
                                ATTRIB+,
                                SIZE?,
                                TIME?,
                                OPTIONVALUE?,
                                LEGALOPTIONVALUES?,
                                INFO?)>
  <!ELEMENT NAME               (#PCDATA)>
  <!ELEMENT PATHNAME           (COMPONENT*)>
    <!ATTLIST PATHNAME DEPTH CDATA "0">
  <!ELEMENT COMPONENT          (#PCDATA)>
    <!ATTLIST COMPONENT LEVEL CDATA "0">
  <!ELEMENT ATTRIB             (#PCDATA)>
  <!ELEMENT SIZE               (#PCDATA)>
  <!ELEMENT TIME               (ACCESS?,
                                MODIFICATION?,
                                CHANGE?)>
  <!ELEMENT ACCESS             (#PCDATA)>
  <!ELEMENT MODIFICATION       (#PCDATA)>
  <!ELEMENT CHANGE             (#PCDATA)>
  <!ELEMENT OPTIONVALUE        (#PCDATA)>
  <!ELEMENT LEGALOPTIONVALUES  (OPTIONVALUE+)>
  <!ELEMENT INFO               (#PCDATA)>
]>


Examples
--------

  File:

    <DIRECTORYITEM>
      <NAME>Good Movie, Part 1</NAME>
      <PATHNAME DEPTH="3">
        <COMPONENT LEVEL="1">movies</COMPONENT>
        <COMPONENT LEVEL="2">good_movie</COMPONENT>
        <COMPONENT LEVEL="3">good_movie_part_1.avi</COMPONENT>
      </PATHNAME>
      <ATTRIB>file</ATTRIB>
      <SIZE>787123245</SIZE>
      <TIME>
        <ACCESS>1034854552</ACCESS>
        <MODIFICATION>1034012491</MODIFICATION>
        <CHANGE>1034012491</CHANGE>
      </TIME>
      <INFO>The First part of the imaginary film.</INFO>
    </DIRECTORYITEM>

  Root directory can be simply:

    <DIRECTORYITEM>
      <NAME>-</NAME>
      <PATHNAME DEPTH="0">
      </PATHNAME>
      <ATTRIB>directory</ATTRIB>
      <INFO></INFO>
    </DIRECTORYITEM>

  Some other directory:

    <DIRECTORYITEM>
      <NAME>Mp3</NAME>
      <PATHNAME DEPTH="1">
        <COMPONENT LEVEL="1">mp3</COMPONENT>
      </PATHNAME>
      <ATTRIB>directory</ATTRIB>
      <INFO>Mp3 Repository</INFO>
    </DIRECTORYITEM>

  Fixed configuration option might be

    <DIRECTORYITEM>
      <NAME>Server data directory</NAME>
      <PATHNAME DEPTH="2">
        <COMPONENT LEVEL="1">configuration</COMPONENT>
        <COMPONENT LEVEL="2">datadir</COMPONENT>
      </PATHNAME>
      <ATTRIB>readonlyoption</ATTRIB>
      <OPTIONVALUE>/usr/data/video/shared</OPTIONVALUE>
      <INFO>Server has its data files in this directory.</INFO>
    </DIRECTORYITEM>

  Fixed configuration option server option might be:

    <DIRECTORYITEM>
      <NAME>Autoshutdown</NAME>
      <PATHNAME DEPTH="2">
        <COMPONENT LEVEL="1">configuration</COMPONENT>
        <COMPONENT LEVEL="2">autoshutdown</COMPONENT>
      </PATHNAME>
      <ATTRIB>option</ATTRIB>
      <OPTIONVALUE>NO</OPTIONVALUE>
      <LEGALOPTIONVALUES>
        <OPTIONVALUE>YES</OPTIONVALUE>
        <OPTIONVALUE>NO</OPTIONVALUE>
      </LEGALOPTIONVALUES>
      <INFO>Shut down the server after this connection
            terminates</INFO>
    </DIRECTORYITEM>