FileList

From Tomes Support Wiki

Contents 1 FileList 1.1 Request 1.2 Response 1.2.1 Info Files 1.2.2 Cover & Thumb Art 1.3 Commerce

FileList

FileList provides a paged list of files and directories contained beneath the requested path. Paging size should be 50 items per page. The client will make subsequent requests when it's ready for more.

Request

The request includes the protocol version "sv" parameters, the path parameters "p", with HexEncoding, and the page number paramter "pg", and an optional filter string "f" which causes only matching files and folders to be returned.

Note that filter support is NOT currently implemented in the Tomes GUI, but servers should support it for future enhancement. Filters should also be encoded with HexEncoding.

http://127.0.0.1:8080/FileList?sv=0100&p=2f53616d706c6544617461&pg=0

The client may pass a page of -1 which means all items should be returned. The client uses this functionality to perform a recursive download.

Response

XML like the following:

 
<response xmlns:dc="http://purl.org/dc/elements/1.1/">
  <action>/FileList</action> <!-- echo'd back -->
  <status>200</status><!-- 200 ok, 404 not found, 403 denied, 500 server error -->
  <path>/SampleData</path> <!-- echo'd back -->
  <supports-filter>true</supports-filter> <!-- Indicates that the f (filter) parameter is supported in this location.  False is assumed if tag is absent. -->
  <filter/> <!-- filter echo'd back or empty tag -->
  <count>17</count> <!-- Number of files, directories and links included. -->
  <page>0</page> <!-- current page number (zero-based) -->
  <lastpage>0</lastpage> <!-- final page number (zero-based) -->
  <recursivedl>true</recursivedl> <!-- true if the client should show the recursive download action -->
  <summary>Short summary of directory's contents, text only</summary>
  <files><!-- contains one or more files, directories, or server links.  Will be sorted by name on the client. -->
    <file><!-- A file element -->
      <idx>0</idx> <!-- ever increasing index number for all items in this response -->
      <name>Color_test.pdb</name> <!-- name of the file -->
      <size>321</size> <!-- size in bytes -->
      <info/><!-- Indicates an info (readme) file.  See Info section below for details -->
      <storagepath>local/path/to</storagepath> <!-- Optional path where book will be stored on device (uses location in shelf server tree if not set).  Must not contain filename, must not start with or end with a slash, must not contain the string "..".  If invalid, file will be silently downloaded as if storagepath wasn't set. -->     
      <dc:title>human readable title</dc:title>
      <dc:author>...</dc:author>
      <dc:identifier>http://.../book.html</dc:identifier><!-- link to web page for this book -->
      <dc:language>en</dc:language><!-- Two-letter ISO code -->
      <dc:date>2009</dc:date><!-- Publication year -->
      <dc:description>...</dc:description> <!-- summary of book - may use HTML P or BR tags for new lines.  No other HTML currently supported. -->
      <dc:rights>...</dc:rights><!-- Either standard copyright statement or CC or similar license grant. -->
      <cover>http://..../pic.png</cover><!-- Larger cover image (screen sized) -->
      <thumb>http://..../pic.png</thumb><!-- Tiny (less than 100x100px) pixel image for thumbnail -->    
      <rating>4</rating><!-- 0..5 -->
      <purchase-status>FREE</purchase-status><!-- One of FREE, PAID, BUYNOW -->
      <purchase-price>US$0.00</purchase-price><!-- Purchase price as string, including currency indicator. -->
      <purchase-url>http://example.com/buy/42</purchase-url><!-- URL to hit to trigger sale.  User's credentials will be appended. -->
    </file>
    <dir><!-- a directory component -->
      <idx>1</idx>
      <name>LittleBrotherHTML</name>
      <!-- Directories may optionally contain title, author, etc., up though thumb from above. -->
    </dir>
  </files>
  <link><!-- link to an external shelf server -->
    <idx>2</idx>
    <name>Human readable name</name>
    <url>http://example.com/ShelfServer/</url> <!-- Base URL (where ShelfName.xml is) -->
    <summary>text-only description of what the shelf contains</summary>
  </link>
</response>
 

Notes:

• count is the total number of items available in this directory, not just for the current page. (doesn't change)
• page is the zero-based page number (changes with each request 0..lastpage)
• lastpage is the zero-based last valid page number. (doesn't change)
• page will run from zero to lastpage inclusive. By the time lastpage is requested, count items will be shown

So to use easy numbers.... If you had 35 items and 10 items per page, count=35 and lastpage=3. The phone would pass pg=0..3 to you, 0..2 would give ten items each, 3 would give the last five.

The client on the phone assumes you told it the truth as far as lastpage based on the number of items you're sending on each page. With each subsequent request, the phone appends the list it got onto an array. If you lie and give it less than a full page's worth on another other than the last page, it should technically still work, but the counts on the button at the bottom will probably get screwy.

Info Files

Recent versions of ShelfServer support a file extension of ".info" used to identify a plain-text file which should be presented as a type of "readme" directly within the shelf interface. For these files, the entire contents of the file (keep it short!) is included within the dc:description tag, and the file is reported as if it was a plain-text file. The info tag itself is an empty marker tag only.

Tomes clients which interpret this tag will present the file in a distinct format from normal books. Tapping either the table row OR the details disclosure icon for these books will display the book details screen, where the full text of the file is available to be read without downloading.

Cover & Thumb Art

Artwork images may be specified either as full literal URLs or as filenames. If a filename is found, it will be retrieved by calling the FileSend endpoint passing the filename from this XML appended as a path onto the folder containing the listing. Relative paths are not allowed as they could lead to path injection.

For example, if the book at /books/novels/WarAndPeace.txt has a cover attribute of W+P.jpg, the client will request /books/novels/W+P.jpg from the server.

Commerce

(Note that purchase support is not yet implemented in Issues for v1.4 . It's not yet certain whether it will be ready for Issues for v1.4

or wait for Issues for v1.5

.

The protocol supports passing basic commerce related information for on-device sales. No provision is made for transferring payment information. It is presumed the user has previously established an account through other means and that purchases will be charged to that account.

Three fields are provided for purchase related data.

purchase-status indicates the status of the item. Possible options are:

• FREE - Item is not for sale and available to all.
• PAID - Item has previously been purchased and is available for download now.
• BUYNOW - Item is not purchased by this account and is for sale.

purchase-price indicates the amount that will be charged for this item if purchased. The amount is a free-text string, but it must contain the amount and an indication of the currency in which the amount will be charged. This field is ignored if purchase-status is FREE or PAID.

purchase-url is the HTTP URL which will be accessed to complete a purchase of the item. The request will have the user's username and password appended as usual for ShelfServer URL's. The server response must be XML in the form of:

 
<response>
  <status>200</status><!-- 200 for success, 5xx for failure. -->
  <message>Thanks!</message><!-- A short thank you or error message. -->
</response>
 

After purchase success or failure, the given message will be displayed to the user. For success, the download URL as calculated from the original FileList request will be used to retrieve the purchased content. On failure, the FileList request will be refreshed to retrieve updated information.

As the download URL for purchased content is available to all users before purchase, it is the server's responsibility to deny downloads to purchased content which has not been purchased by the account given in the URL query string.