Specification for the DAISY Online Delivery Protocol

3.1.1. HTTP Cookies

The DAISY Online Delivery protocol requires the use of [HTTP Cookies] (as defined in [WS-I Basic Profile 1.1]) to maintain stateful sessions.

A Reading System must be able to receive and send any cookies that are transmitted to it by a Service. As per the [WS-I Basic Profile 1.1], a compliant Reading System must not process or manipulate the cookies.

A compliant Service must be able to manage HTTP Cookies.

3.1.2. HTTPS

3.1.3. HTTP Basic Authentication

The HTTP Basic Authentication Scheme described in [RFC 2617] may be used to secure Content against unauthorized access.

When using Basic Authentication, a Service must supply the credentials in the server component field of the URI. The scheme for the userinfo field (as given in [RFC 2396], Section 3.2.2) is: userinfo@host:port

If the credentials also require a password, then the userinfo field must be of the form: userid:password@host:port

When retrieving a resource, a Reading System must only send Basic Authentication credentials when they are supplied in the URI returned by a Service.

The credentials required to access Content are not required to be the same as the credentials supplied to the logOn operation.

A compliant Reading System must support Basic Authentication. Service support for Basic Authentication is recommended.

3.1.4. HTTP Range Headers

When using HTTP or HTTPS for serving resources, a Service must honor Range Retrieval Requests (as described in section 14.35 of RFC 2616).

Services must use correct status codes and Content-Range and Content-Length headers when serving partial content (as described in section 14.16 of RFC 2616).

As it is not possible to require support for range headers on Service Delegates, Reading Systems must be able to handle servers that do not support range headers.

3.2.1. Basic Profile 1.1

The DAISY Online Delivery protocol is compliant with the requirements of [WS-I Basic Profile 1.1]. All conformant implementations of this protocol must also be compliant with [WS-I Basic Profile 1.1].

3.2.2. WSDL Binding Style

The WSDL binding style used in the abstract WSDL document in Appendix A, WSDL Abstract Definition is wrapped document-literal. The wrapped document-literal style is a subset of the document-literal style and satisfies normative requirement R2712 of [WS-I Basic Profile 1.1].

Conformant Services must use the wrapped document-literal binding style.

4.1.1. Lending Model

4.1.2. Acquisition Model

4.2.1. Session Initialization

The following steps must be followed when starting a Session to authenticate a Reading System to a Service:

After receiving a successful logon response, the Reading System must call the following Operations in the given sequence:

If a Service returns a Fault during any of the initialization steps, or if a required return value is not provided, a Reading System may attempt to re-initialize the Session or abort the logon process. A Reading System may alert the user, attempt to reconnect automatically or take any action, particular to that device.

A Service must return an invalidOperation Fault if a Reading System attempts to call any Operation other than the ones outlined in this section before successfully completing the full initialization sequence. The only exception to this rule is the logOff operation that may be called anywhere within the initialization sequence.

After completing a successful logon and initialization sequence, a Reading System may call any Operations defined by this specification, but must complete the initialization sequence outlined in this section again if calling logOn.

4.2.2. Session Duration

A Session begins after a successful logOn operation. The Session must remain active until the Reading System successfully calls logOff or the Service terminates it. This protocol does not define behaviors relating to the termination of Sessions. Time out intervals, reasons for forced termination and related aspects are defined by the implementation.

A Service should persist a Session across multiple HTTP connections by a Reading System so long as the Session is still active. A Service may allow multiple concurrent connections with the same session ID.

4.3.1. Out-of-band Content Selection Method

A Service offering the Out-of-band Content Selection Method is compliant if it:

A Reading System may also make use of the issued contentList, if available, to access Content items that have already been issued.

For automated downloading scenarios using the out-of-band selection method, the Reading System must also execute the steps outlined in Section 4.4, “Issuing and Transfer of Content”, to obtain the Content.

4.3.2. Browse Content Selection Method

A Service offering the Browse Content Selection Method is compliant if it:

4.4.1. Content Retrieval Sequence

In order to download a Content item from a Service, a Reading System must first call the following Operations in the given order. The Operations do not need to be called immediately one after the other (other Operations may be called for other Content items), but the order must be maintained.

A Reading System will generally retrieve a contentList from a Service using one of the methods described in Content Selection Methods prior to requesting that the Service issue any items.

4.4.2. Downloading and Streaming of Content

Reading Systems may use the [MIME] type information in the mimeType attribute of a resource to order the transfer of resources. For example, a Streaming Reading System may retrieve the OPF, NCX and SMIL files of a DAISY Digital Talking Book to provide the User full navigation before downloading any audio data.

Resources may be stored on servers belonging to a Service Delegate. A Service must provide the Reading System any credentials required to access content stored on a Service Delegate's servers. The URI of each resource secured with Basic Authentication must include the credentials required to access that resource. Refer to Section 3.1.3, “HTTP Basic Authentication”.

4.4.3. Publishing Updates and Installments

The resources type and each contentItem in a contentList have an optional lastModifiedDate attribute that indicates the last time the Content item was modified. A Reading System can use this information to determine if the Content item on the Service has been updated since the last time it was accessed. Each resource in the resources list also has an optional lastModifiedDate attribute that the Reading System may use to determine which specific resources have been updated.

The functionality detailed in this section can also be used to publish Content in installments by progressively updating the same Content item as new sections of the Content item are authored.

4.4.4. Content Synchronization sequence

In the Out-of-band Content Selection Method, a Reading System can automatically synchronize the Content it stores locally with the Content available to the User on the Service. The following sequence of steps can be taken to synchronize the Content. A Session must be initialized, but other Operations may be called before synchronization.

At this point, the Reading System will have the contentMetadata and resources for every Content item available to the User. It can begin downloading new and updated Content, or it can offer the titles to the User for streaming, or it can continue calling Operations.

Since a Service is free to return a partial contentList, the getContentList operation may need to be called several times with the appropriate index parameters to retrieve the full lists.

Faults may occur in this sequence. For instance, a Service may offer many Content items in its new contentList, but only allow a few to be issued at a time.

4.4.5. Rights management

The [PDTB2] format may be used to protect Content. This protocol provides a key exchange mechanism, the getKeyExchangeObject operation, to allow Reading Systems to request keys from Services to access encrypted Content.

Reading Systems and Services are not required to support PDTB2. Services may provide PDTB2-protected Content without supporting getKeyExchangeObject when alternate means of key provision have been implemented, for example when keys are provided with the Reading System.

4.5.1. New Announcements

A Reading System may check for new messages at any time when connected to a Service by calling the getServiceAnnouncements operation. It is recommended that Reading Systems check for announcements immediately after completing the initialization of a new Session.

The Service can set the importance level for each announcement from a level of 1 (most important) to 3 (least important) and specify the type of announcement as one of ERROR, SYSTEM, WARNING or INFORMATION to assist Reading Systems in ordering the announcements for rendering to the User.

A Service may remove unread announcements from the Service at any time and for any reason. To avoid potential retrieval conflicts, a Reading System must treat the announcement IDs as valid for no longer than the duration of the active Session.

If a Service does not support service announcements, the Service must return an operationNotSupported Fault when a Reading System calls getServiceAnnouncements.

4.5.2. Read Announcements

After rendering announcements to a User, a Reading System may call the markAnnouncementsAsRead operation to inform the Service not to send the announcement again the next time the User connects to the Service.

To prevent conflicts arising from announcements that have been removed from the Service, a Reading System must only pass identifier values obtained from the last call to getServiceAnnouncements during the active Session to markAnnouncementsAsRead.

If a Reading System calls markAnnouncementsAsRead, and a Service returns false, then the announcement has already been marked as read. If a Service returns an invalidParameter Fault, then the announcement identifier does not exist on the Service.

A Reading System may mark more than one announcement as read in the same call to markAnnouncementsAsRead. If an invalidParameter Fault is returned, the Reading System must call markAnnouncementsAsRead sequentially for each announcement to determine which identifier caused the Fault.

4.7.1. Support

To support dynamic menus, a Reading System or Service must implement the getQuestions operation.

To indicate that a Service supports dynamic menus, the Service must include an operation element with the value DYNAMIC_MENUS in its serviceAttributes.

A Reading System that supports dynamic menus must declare which input types it supports in its readingSystemAttributes. A Service should not send any question which requires an input type not supported by the Reading System. If the Reading System declares no input types, then the Service should only send multipleChoiceQuestions.

Services that support the Browse Content Selection Method must also support dynamic menus to allow a User to select Content. Services that only support the Out-of-band Content Selection Method may support dynamic menus for other interaction purposes, but are not required to.

4.7.2. Root Question

The first call to getQuestions in a Session must be with a single userResponse whose questionID is default, to retrieve the root question.

4.7.3. Navigation

getQuestions takes one parameter: userResponses. The userResponses type either contains a response to a previous question(s) or has a questionID set to one of the three reserved keywords defined in Section 4.7.6, “Reserved IDs”.

A User navigates a menu system by repeatedly selecting answers to the questions returned from calls to getQuestions until one of the end points outlined in Section 4.7.5, “End Points”, is reached.

A Service may send more than one question in response to any call to getQuestions. A Reading System should collect the responses to each question before calling getQuestions again and each response must be contained in a separate userResponse element.

4.7.4. Question Types

4.7.5. End Points

A questions element, received through a call of getQuestions, containing one of the following as its child indicates an end point of the menu sequence:

4.7.6. Reserved IDs

Reading Systems that support dynamic menus must support the default value; search and back are optional.

A Service must return an invalidParameter Fault if a Reading System calls the getQuestions operation with the search or back values when these values are not supported by the Service.

5.1.1. The logOn Operation

5.1.2. The logOff Operation

5.1.3. The setReadingSystemAttributes Operation

A Reading System must call this operation as part of the Session Initialization Sequence. The operation may be called additional times during a Session to record dynamic changes in a Reading System's properties.

5.1.4. The issueContent Operation

5.1.5. The getContentMetadata Operation

Retrieves the contentMetadata of the specified Content item.

This operation must be called as part of the Content Retrieval Sequence.

5.1.6. The getContentResources Operation

Retrieves the resources list for the specified Content item.

The Content item must be issued before this operation is called. If not, the Service shall respond with an invalidParameter Fault.

5.1.7. The getServiceAttributes Operation

A Reading System must call this operation as part of the Session Initialization Sequence and may call the operation to retrieve information on possible changes to Service properties at any other time during a Session.

5.1.8. The getContentList Operation

The list returned by the Service can be pre-composed, in which case it is retrieved by passing one of the three reserved values defined in the id parameter below. (Refer to 4, Protocol Fundamentals for information on the contexts in which these reserved values are used.)

The list can also be dynamic (e.g., the result of a dynamic menu search operation sequence). In this case, the id value used to refer to the list is provided in the return value of a previous call to getQuestions. (Refer to the questions type for more information.)

5.2.1. The getServiceAnnouncements Operation

5.2.2. The markAnnouncementsAsRead Operation

This operation is only valid if a previous call to getServiceAnnouncements has been made during the Session.

5.2.3. The returnContent Operation

5.2.4. The setBookmarks Operation

5.2.5. The getBookmarks Operation

5.2.6. The getQuestions Operation

5.2.7. The getKeyExchangeObject Operation

Requests a [PDTB2] Key Exchange Object from a Service.

5.3.1. The internalServerError Fault

This Fault is issued when errors occur that are not described by the invalidOperation, invalidParameter, operationNotSupported and noActiveSession Faults. At the event of this Fault being issued, Reading Systems may attempt to call the operation that failed again.

5.3.2. The noActiveSession Fault

This Fault is issued on all operation calls except those in the operation sequence defined by the Session Initialization Sequence when a Session has either expired or not been successfully initialized.

5.3.3. The operationNotSupported Fault

This Fault is issued when a Reading System calls an optional operation that the Service does not support.

5.3.4. The invalidOperation Fault

5.3.5. The invalidParameter Fault

6.1.1. announcements Examples

<announcements xmlns="http://www.daisy.org/ns/daisy-online/">
  <announcement id="downtime" priority="1" type="WARNING">
    <label xml:lang="en">
      <text>The Service will not be available on Friday the 10th of September due to
        maintenance.</text>
      <audio uri="http://example.com/content/messages/current.mp3" rangeBegin="0" rangeEnd="65856"
        size="65856"/>
    </label>
  </announcement>
  <announcement id="survey" priority="2" type="INFORMATION">
    <label xml:lang="en">
      <text>A new survey is available, fill it in online at our home page, or use your Daisy Online
        Reading System if it has the required capabilities. Chance to win a Phantom Pocket
        Reader!</text>
      <audio uri="http://example.com/content/messages/current.mp3" rangeBegin="65857" size="92112"/>
    </label>
  </announcement>
</announcements>

6.3.1. contentList Examples

<contentList xmlns="http://www.daisy.org/ns/daisy-online/" 
    id="cl123" totalItems="2">
    <label xml:lang="en">
        <text>Please select from these publications.</text>
        <audio uri="http://example.com/static/PleaseChooseFrom.mp3" size="12342"/>
    </label>
    <contentItem id="com-example-001">
        <label xml:lang="en">
            <text>Harry Potter and the Chamber of Secrets</text>
            <audio uri="http://example.com/content/titles/hp_cs.mp3" size="130821"/>
        </label>
    </contentItem>
    <contentItem id="com-example-002">
        <label xml:lang="en">
            <text>Harry Potter and the Goblet of Fire</text>
            <audio uri="http://example.com/content/titles/hp_gf.mp3" size="130821"/>
        </label>
    </contentItem>
</contentList>

<contentList xmlns="http://www.daisy.org/ns/daisy-online/" 
    id="cl125" firstItem="0" lastItem="1" totalItems="25">
    <label xml:lang="en">
        <text>Please select from these publications.</text>
    </label>
    <contentItem id="com-example-001">
        <label xml:lang="en">
            <text>Harry Potter and the Chamber of Secrets</text>
        </label>
    </contentItem>
    <contentItem id="com-example-002">
        <label xml:lang="en">
            <text>Harry Potter and the Goblet of Fire</text>
        </label>
    </contentItem>
</contentList>

6.4.1. contentMetadata Examples

<contentMetadata xmlns="http://www.daisy.org/ns/daisy-online/"
  requiresReturn="true" category="BOOK">
  <sample id="hp_cos-sample"/>
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:title>Harry Potter and the Chamber of Secrets</dc:title>
    <dc:identifier>com-example-hp_cos</dc:identifier>
    <dc:format>Daisy 2.02</dc:format>
    <dc:language>en-GB</dc:language>
    <narrator>Mary Svensson</narrator>
    <size>8119213</size>
    <meta name="pdtb2:specVersion" content="2005-1" />
  </metadata>
</contentMetadata>

6.9.1. readingSystemAttributes Examples

<readingSystemAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <manufacturer>ACME Corporation</manufacturer>
  <model>Pocket Phantom</model>
  <serialNumber>123456</serialNumber>
  <version>1.23</version>
  <config>
    <supportsMultipleSelections>false</supportsMultipleSelections>
    <preferredUILanguage>en</preferredUILanguage>
    <bandwidth>8000000</bandwidth>
    <supportedContentFormats>
      <contentFormat>ANSI/NISO Z39.86-2005</contentFormat>
    </supportedContentFormats>
    <supportedContentProtectionFormats>
      <protectionFormat>PDTB2</protectionFormat>
    </supportedContentProtectionFormats>
    <keyRing>
      <item>DAISY.lv-acme.ACME</item>
      <item>DAISY.lv-acme.Phantom-1</item>
      <item>DAISY.lv-acme.SN123456</item>
      <item>DAISY.ca-qqhb.006442</item>
      <item>DAISY.au-atbi.userKey-4C452DB4</item>
    </keyRing>
    <supportedMimeTypes>
      <mimeType type="audio/mpeg"/>
    </supportedMimeTypes>
    <supportedInputTypes>
      <input type="TEXT_NUMERIC" />
    </supportedInputTypes>
    <requiresAudioLabels>true</requiresAudioLabels>
  </config>
</readingSystemAttributes>

<readingSystemAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <manufacturer>ACME Corporation</manufacturer>
  <model>Pro Phantom III</model>
  <serialNumber>64321</serialNumber>
  <version>1.23</version>
  <config>
    <supportsMultipleSelections>true</supportsMultipleSelections>
    <preferredUILanguage>en</preferredUILanguage>
    <supportedContentFormats>
      <contentFormat>ANSI/NISO Z39.86-2005</contentFormat>
      <contentFormat>Daisy 2.02</contentFormat>
    </supportedContentFormats>
    <supportedContentProtectionFormats />
    <supportedMimeTypes>
      <mimeType type="text/plain" xml:lang="en"/>
      <mimeType type="audio/mpeg"/>
    </supportedMimeTypes>
    <supportedInputTypes>
      <input type="TEXT_ALPHANUMERIC"/>
      <input type="AUDIO"/>
    </supportedInputTypes>
  </config>
  <requiresAudioLabels>false</requiresAudioLabels>
</readingSystemAttributes>

6.10.1. resources Examples

<resources xmlns="http://www.daisy.org/ns/daisy-online/">
   <resource mimeType="text/xml" size="123456" 
    uri="https://example.com/content/get.php?a123891"
    localURI="package.opf"/>
  <resource mimeType="application/x-dtbncx+xml" size="123456" 
    uri="https://example.com/content/get.php?a123892"
    localURI="nav.ncx"/>
  <resource mimeType="application/smil" size="567890" 
    uri="https://example.com/content/get.php?a123893"
    localURI="chapter_1.smil"/>
  <resource mimeType="audio/mpeg" size="123456789" 
    uri="https://example.com/content/get.php?a123894"
    localURI="chapter_1.mp3"/>
  <resource mimeType="image/jpeg" size="23456" 
    uri="https://example.com/content/get.php?a123895" 
    localURI="./images/sun001.jpg"/> 
</resources>

6.11.1. serviceAttributes Examples

<serviceAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <serviceProvider id="uk.com.example" />
  <service id="uk.com.example.libraryServiceBasic" />
  <supportedContentSelectionMethods>
    <method>OUT_OF_BAND</method>
  </supportedContentSelectionMethods>
  <supportsServerSideBack>false</supportsServerSideBack>
  <supportsSearch>false</supportsSearch>
  <supportedUplinkAudioCodecs>
    <codec>audio/mpeg</codec>
  </supportedUplinkAudioCodecs>
  <supportsAudioLabels>true</supportsAudioLabels>
  <supportedOptionalOperations>
    <operation>SET_BOOKMARKS</operation>
    <operation>GET_BOOKMARKS</operation>
    <operation>SERVICE_ANNOUNCEMENTS</operation>
  </supportedOptionalOperations>
</serviceAttributes>

<serviceAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <serviceProvider id="gy-zenith" />
  <service id="gy-zenith-libraryServiceDeluxe" />
  <supportedContentSelectionMethods>
    <method>BROWSE</method>
    <method>OUT_OF_BAND</method>
  </supportedContentSelectionMethods>
  <supportsServerSideBack>true</supportsServerSideBack>
  <supportsSearch>true</supportsSearch>
  <supportedUplinkAudioCodecs>
    <codec>audio/mpeg</codec>
  </supportedUplinkAudioCodecs>
  <supportsAudioLabels>true</supportsAudioLabels>
  <supportedOptionalOperations>
    <operation>DYNAMIC_MENUS</operation>
    <operation>SET_BOOKMARKS</operation>
    <operation>GET_BOOKMARKS</operation>
    <operation>SERVICE_ANNOUNCEMENTS</operation>
    <operation>PDTB2_KEY_PROVISION</operation>
  </supportedOptionalOperations>
</serviceAttributes>