ShelfName

From Tomes Support Wiki

ShelfName.xml

ShelfName.xml provides information about a ShelfServer to the ShelfClient. Included are the name of the server, whether a username and/or password are required, the version of the protocol spoken by this server, and an optional redirect where the rest of the protocol end points are to be found.

This endpoint may optionally be provided by a static XML file as opposed to the dynamic "scripting" language required to provide the rest of the protocol. This allows placing this file on a public HTML webserver while redirecting dynamic request to other servers for processing. In case this endpoint is provided by a static XML file, version checking behavior will be deleted to the first dynamic call made by the client.

Request

The request will be an HTTP GET request sent by the ShelfClient. The request will contain only the ShelfServerProtocol version spoken by the ShelfClient contained in the "sv" QueryString parameter. See UnhandledVersions for behavior in case of a server/client version mismatch.

http://127.0.0.1:8080/ShelfName.xml?sv=0100

Response

The response is an XML message containing the following: (FIXME: XML Schema)

 
<response>
  <action>/ShelfName.xml</action><!-- Echo the name of the endpoint -->
  <status>200</status><!-- Should always be 200 - OK -->
  <name>ShelfServer on Ringo.local</name> <!-- Name of the server. -->
  <username-required>false</username-required> <!-- True or false -->
  <password-required>false</password-required> <!-- True or false -->
  <credentials-optional>true</credentials-optional>
  <fileops-url/> <!-- Redirect URL.  Use an empty tag if other end points are at the same root as this one, otherwise include the full URL to the new server root. -->
  <shelf-protocol-version>0100</shelf-protocol-version> <!-- Highest protocol version supported by this server. -->
</response>
 

The credentials-optional tag is supported as of Issues for v1.2 . If present and set to true, it will indicate that the server will take credentials (as indicated by username-required and password-required) to unlock additional content. Setting credentials-optional=true indicates that the server will accept a blank or missing user/pass or a correct user/pass. The server should return an error code if incorrect credentials are present, but it should allow the connection if no credentials are present and should unlock additional content for the user if correct credentials are present.