ShelfServerProtocol
From Tomes Support Wiki
Contents |
Shelf Server Protocol
The ShelfServer protocol consists of a set of end points and XML messages passed from a ShelfClient such as Tomes to a ShelfServer running on a desktop computer or server. While the version of ShelfServer provided for use with Tomes adds some rather complicated HTML "fixing" routines to clean up poorly formed HTML files found on the Net, a basic implementation of the protocol to provide already clean HTML or Palm files to an iPhone should be trivial to implement in most any web accessible language.
Each ShelfServer starts with a base URL under which all other end points lie. The ShelfServer endpoints are:
- BaseUrl ('/') - an optional endpoint provided by the reference implementation. The page which answers directly and the ShelfServer Base URL should provide a shelfserver:... URL to allow users reaching the site in MobileSafari to easily add the server to their favorites list.
- ShelfName.xml - an (optionally static) XML file which lists the name of the server, any security requirements, and an optional redirect to where the dynamic portions (all other endpoints) of the protocol reside. The ShelfClient calls this end point when a ShelfServer is first added and each time the user attempts to connect. Any of the items returned by this call may change over time and will automatically be refreshed.
- DirectorySize - retrieves a listing of the number and total size in bytes of the files contained in a given path. The reported totals must recursively include all sub-directories. The ShelfClient calls this end point before beginning a recursive download to ensure that sufficient space is available to hold all of the requested files.
- FileList - Lists the files and directories contained within a given path. Provides paging support to allow retrieval of the list in smaller, phone manageable pieces.
- FileSend - Sends the contents of a book file, optionally applying any necessary fixes to its contents. This end point will be called repeatedly during a recursive download.
UrlScheme
In addition to the above endpoints, the Tomes application also supports a UrlScheme to allow easily adding ShelfServer favorites. To create an appropriate URL, start with the http link of the base URL for the server and add shelfserver: to the beginning.
Compression
All ShelfServer responses should be compressed with gzip or deflate if the client indicated support in the Accept-Encoding request header. If content is so compressed, it must be indicated in the Content-Encoding response header.
File Formats
The above specs are designed for sending over PalmOS based file formats, primarily. For other file formats, please see FormatConversions for important details on the on-device file requirements.
