Specification for the DAISY Online Delivery Protocol v1

Archived document. For the latest version information visit the DODP Standards area.

Approved May 29, 2010 by the DAISY Consortium Board

This version as a zip archive:

https://dl.daisy.org/standards/DODP/do-spec-20100402.zip

Editors:

(Co-Chair) Kenny Johar, Vision Australia

(Co-Chair) Markus Gylling, DAISY Consortium

Matt Garrish, CNIB

Geoff Gilmour-Taylor, CNIB

Jelle Martijn Kok, Solutions Radio

Nick Williamson, RNIB

Simon Roy, HumanWare

Johan Abbors, Pratsam

Abstract

The DAISY Online Delivery protocol is a web service API that facilitates the delivery of digital resources from service providers to end users. The protocol features a core set of operations that can be configured to enable a variety of different download models, making it a flexible and lightweight solution to the growing need for online delivery of published content.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current DAISY publications and the latest revision of this specification can be found in the DAISY projects index at http://www.daisy.org/projects/.

This document was developed by the DAISY Online Working Group as a part of its activities. For a complete list of members at the time of publication, please refer to Appendix B, Acknowledgments.

This document is a Technical Recommendation of the DAISY Consortium and developed by the DAISY Online Working Group operating under the DAISY Online Delivery Project Charter.

Please report errors in this document and suggestions for future versions of the protocol to the Working Group through the public feedback form available on the DAISY site at http://www.daisy.org/contact.

The English version of this specification is the only normative version.

Table of Contents

1. Introduction

2. Terminology

3. Underlying Technologies

3.1. HTTP

3.1.1. HTTP Cookies
3.1.2. HTTPS
3.1.3. HTTP Basic Authentication
3.1.4. HTTP Range Headers

3.2. WS-I

3.2.1. Basic Profile 1.1
3.2.2. WSDL Binding Style

4. Protocol Fundamentals

4.1. Service Models

4.1.1. Lending Model
4.1.2. Acquisition Model

4.2. User Authentication and Session Management

4.2.1. Session Initialization
4.2.2. Session Duration

4.3. Content Selection Methods

4.3.1. Out-of-band Content Selection Method
4.3.2. Browse Content Selection Method

4.4. Issuing and Transfer of Content

4.4.1. Content Retrieval Sequence
4.4.2. Downloading and Streaming of Content
4.4.3. Publishing Updates and Installments
4.4.4. Content Synchronization sequence
4.4.5. Rights management

4.5. Service Announcements

4.5.1. New Announcements
4.5.2. Read Announcements

4.6. Bookmarks

4.7. Dynamic Menus

4.7.1. Support
4.7.2. Root Question
4.7.3. Navigation
4.7.4. Question Types
4.7.5. End Points
4.7.6. Reserved IDs

5. API Reference

5.1. Required Operations

5.1.1. The logOn Operation
5.1.2. The logOff Operation
5.1.3. The setReadingSystemAttributes Operation
5.1.4. The issueContent Operation
5.1.5. The getContentMetadata Operation
5.1.6. The getContentResources Operation
5.1.7. The getServiceAttributes Operation
5.1.8. The getContentList Operation

5.2. Optional Operations

5.2.1. The getServiceAnnouncements Operation
5.2.2. The markAnnouncementsAsRead Operation
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

5.3. Faults

5.3.1. The internalServerError Fault
5.3.2. The noActiveSession Fault
5.3.3. The operationNotSupported Fault
5.3.4. The invalidOperation Fault
5.3.5. The invalidParameter Fault

6. Type Reference

6.1. The announcements Type

6.1.1. announcements Examples

6.2. The bookmarkSet Type

6.3. The contentList Type

6.3.1. contentList Examples

6.4. The contentMetadata Type

6.4.1. contentMetadata Examples

6.5. The KeyExchange Type

6.6. The keyRing Type

6.7. The questions Type

6.8. The read Type

6.9. The readingSystemAttributes Type

6.9.1. readingSystemAttributes Examples

6.10. The resources Type

6.10.1. resources Examples

6.11. The serviceAttributes Type

6.11.1. serviceAttributes Examples

6.12. The userResponses Type

6.13. Element Reference

References

A. WSDL Abstract Definition

B. Acknowledgments

List of Examples

6.1. announcements
6.2. A complete contentList with audio labels
6.3. A partial contentList
6.4. Example contentMetadata
6.5. readingSystemAttributes for a portable audio-centric Reading System
6.6. readingSystemAttributes for a more functional Reading System
6.7. A resources instance using script URIs
6.8. serviceAttributes for a minimal library Service
6.9. serviceAttributes for a fuller Service
A.1. An example published WSDL document

1. Introduction

This section is informative

The DAISY Online Delivery protocol grew out of the need for DAISY producers to be able to deliver content to clients and users in a timely and cost-effective way. The challenges associated with distributing content in physical mediums make these solutions difficult to implement, cumbersome to maintain and environmentally unfriendly.

Although DAISY Digital Talking Books are the primary component of the DAISY standard, the standard itself is evolving and the need to distribute various types of accessible media is one that is already faced by many members of the DAISY Consortium. As a result, the service architecture development for this protocol was done with the goal of getting resources from a provider to a reading system, a design principle that should also make the protocol useful as a content delivery mechanism beyond the sphere of accessible publishing.

The second main development objective was to ensure that the protocol was flexible enough to allow it to be customized and tailored to the delivery needs of any individual or organization. The minimal core functionality facilitates the development of simple services that can, for example, allow users to plug their reading system in at night and automatically download their new content. The expanded set of functionality allows for richer and more interactive models where users can browse for and download their own content.

The protocol was also engineered to facilitate the lending of content, not just its delivery. Libraries and other organizations that require a means to deliver content to users for a limited period of time will find a number of features that facilitate this kind of delivery model. The protocol also enables the use of the PDTB2 content protection scheme where explicit digital rights management issues are a concern.

The protocol has been built on a strong foundation of established technologies to reduce the implementation and maintenance costs for individuals and organizations looking to implement this content delivery model: the interaction between reading systems and services is carried out by SOAP messages over the HTTP protocol; the service operations are all defined by a normative WSDL document; and the protocol itself is compliant with WS-I Basic Profile 1.1.

One feature that could not be tackled in this version of the protocol is the discovery of DAISY Online Delivery services. The DAISY Consortium may develop a system and specification for tracking and locating online services at a later date, but currently no such functionality exists that could be integrated with this protocol.

2. Terminology

This section is normative

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119].

In addition, the following terms are used throughout this document with the meanings outlined in this section.

Borrowable Content: Content that may be lent to a User, and must be returned after being lent. The ownership of the Content does not pass to the User. Borrowable Content includes Content that may be rented for a fee.
Content: A resource or resources made available by a Service Provider through a Service, such as DAISY Digital Talking Books. (Singular: Content item.)
Content Identifier: The unique identifier assigned to a Content item. This identifier is defined by the Service and is exposed in the [Dublin Core] identifier field of the contentMetadata type. The identifier must be unique within the scope of the Service and it must not change over time.

Note:

The Content Identifier is not required to match any identifiers used in the Content item (for example, the identifier in a DAISY Digital Talking Book’s metadata).
Download: Transfer of Content from the Service to the Reading System, which the Reading System stores in non-volatile memory.

Note:

Download and Streaming are Reading System behaviors, not aspects of this protocol.
Fault: A [SOAP 1.1] Fault. A Fault carries error and/or status information in a SOAP message. Section 5.3, “Faults” defines the Faults used in this protocol.
Interface: A [WSDL 1.1] port type. A set of Operations supported by the Service.
Issue Content: Grant access to a Content item. A Reading System uses the issueContent operation to request access from the Service.
Operation: A [WSDL 1.1] operation. An action supported by the Service.
Purchasable Content: Content that may be sold to a User, and should not be returned. The ownership of the Content may or may not pass to the User. Purchasable Content includes Content that is offered without charge. It includes any Content that does not require return, such as Content protected by DRM which expires without the need for return.
Reading System: A combination of hardware and/or software that accesses a Service and renders Content to the User. A Reading System may be implemented entirely on one device or it may be split among several. Corresponds to a [WS-I Basic Profile 1.1 Conformance Targets] consumer.
Return Content: Give up access to a Content item. A Content item is returned when the Reading System has removed any locally-stored data and called the returnContent operation to notify the Service to revoke access and remove from the User’s collection of issued Content. This term applies only to Borrowable Content, not Purchasable Content.
Service: A web service that implements the DAISY Online Delivery Protocol. Corresponds to a [WS-I Basic Profile 1.1 Conformance Targets] instance.
Service Delegate: A file hosting server that is not under the control of the Service Provider.
Service Provider: The person(s) or organization(s) who own a Service. The Service Provider may or may not be the same entity who owns the servers the Service runs on.
Session: A sequence of Operations between one Reading System and one Service using a unique identifier defined by the Service. A session may persist across several HTTP connections. Session identifiers may be reused at the Service’s discretion. Session identifiers are sent to the Reading System using [HTTP Cookies].
Streaming: Transfer of Content from the Service to the Reading System, which the Reading System renders immediately and stores only temporarily.

Note:

Download and Streaming are Reading System behaviors, not aspects of this protocol.
Type: An [XML Schema 2] datatype.
User: A person who interacts with a Service using a Reading System and/or or accesses Content from the Service.

3. Underlying Technologies

This section is normative

3.1. HTTP

The DAISY Online Delivery protocol uses [HTTP 1.1]:

as the transport layer for all SOAP messages sent and received by a Service; and
for the transfer of Content data.

Reading Systems must support [HTTP 1.1] and secure HTTP (HTTPS) through either [SSL 3.0] or [TLS 1.0].

The use of HTTP must conform to [HTTP 1.1] and [RFC 2617].

Services and Reading Systems must support HTTP sessions as specified in [RFC 2109].

Note:

An established HTTP session is not in itself a valid indicator that a Reading System has successfully logged on to the Service (refer to Section 4.2, “User Authentication and Session Management”).

A Service must return the appropriate HTTP status code in the HTTP response (as specified by [HTTP 1.1], Section 10) to all HTTP and HTTPS requests sent by a Reading System.

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

The use of HTTPS for all transactions with a Service is recommended as the data being exchanged may contain confidential information. HTTPS also allows a Reading System to verify the identity of the Service through the use of certificates.

Security Considerations

It is recommended when implementing HTTPS that all certificates be registered with a certificate authority and not be self-signed.

All URIs that identify resources served over HTTPS must use the standard URI prefix https:.

A compliant Reading System must support HTTPS. Support for HTTPS is recommended for Services.

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

Security Consideration

[RFC 2396] recommends against the use of the userid:password scheme as it may result in the transmission of passwords in the clear and is known to be a security risk in all cases. A Service should only use this scheme over a secure connection such as HTTPS and Reading Systems should be developed to avoid the known exploits of this method.
The current best practice for the storage of passwords is to only store a cryptographic hash of each password in case a database is compromised. A Service, however, may need to retrieve the unencrypted authentication credentials for a User in order to supply them in the userinfo field. Services implementing Basic Authentication using this scheme consequently risk compromising the security of their databases unless secure retrieval methods are implemented.

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.

Note:

HTTP Basic Authentication credentials must not be used to log on to a Service. For authenticating a SOAP session, refer to Session Initialization Sequence.

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. WS-I

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. Protocol Fundamentals

This section is normative

4.1. Service Models

The DAISY Online Delivery protocol supports two basic service models:

a lending model, where the Service offers Borrowable Content; and
an acquisition model, where the Service offers Purchasable Content.

A Service may offer Borrowable Content, Purchasable Content or both.

To provide identical Content under both service models, a Service must supply two Content items with different Content Identifiers. The Content items may have the same set of resources.

A Service must use the requiresReturn attribute of the Content item’s contentMetadata to indicate the model it will issue the Content item under. If requiresReturn is true, the Content item is borrowable. If requiresReturn is false, the Content item is purchasable.

Once a Content item is issued, the Service must not change the value of the requiresReturn attribute.

4.1.1. Lending Model

4.1.1.1. Service Requirements

Services offering Borrowable Content must:

implement the returnContent operation; and
offer the issued contentList

The following conditions apply to any item of Borrowable Content:

the requiresReturn attribute of the Content item’s contentMetadata must be set to true;
if issued, the Content item must be listed in either the User’s issued or expired contentList until it is returned; and
the Service must allow the Reading System to call returnContent at any time during any Session to return the issued Content item.

4.1.1.2. Reading System Requirements

The Reading System must not call returnContent with a Content Identifier of a Content item unless all local copies of that Content item have been removed.

4.1.1.3. Content Expiry

This protocol defines two methods to assist in the automatic return of Content by a Reading System: the returnBy attribute of the resources type, and the expired contentList. This protocol does not require the enforcement of these methods on the Reading System. Service Providers should investigate other methods for protecting Content that must expire at a specific time (for example DRM schemes like [PDTB2]).

The returnBy attribute indicates the time before which the User should return the Content item. If it has a real-time clock, a Reading System should delete the Content item at the specified time and return the Content item to the Service at the next Session. Reading Systems should communicate the due date provided in the returnBy attribute to the User.

The expired contentList may be populated by a Service with Borrowable Content items that have been issued to indicate that the Service Provider wants the Content items to be returned. If a Reading System has any items of Borrowable Content, it should call getContentList with an id parameter of expired to retrieve this list at least once in each Session, and should return the Content items indicated. Content items on the expired contentList are still issued.

Note:

Service Providers should use the expired contentList only in exceptional cases. Users should be notified that a Content item has expired and will be deleted.

4.1.2. Acquisition Model

4.1.2.1. Service Requirements

The following conditions apply to any item of Purchasable Content:

The requiresReturn attribute of the Content item’s contentMetadata must be set to false.
If issued, the Content item may be listed in the User’s issued contentList but must not be listed in the expired contentList. This specification does not specify the lifetime of Purchasable Content’s availability in the issued contentList.

4.1.2.2. Reading System Requirements

The Reading System must not call returnContent with a Content Identifier of a Content item whose contentMetadata‘s requiresReturn attribute is false.

4.2. User Authentication and Session Management

Before a Reading System can interact with a Service to obtain Content, it must successfully authenticate itself and establish a valid Session. The following subsections outline the steps in this process.

4.2.1. Session Initialization

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

The Service Provider is responsible for stipulating and supplying the User with the credentials required to authenticate a Reading System. A Service may provide credentials per User, per group or class of User, per Reading System or by any other method.

The Reading System must pass the User’s login credentials to the Service by calling the logOn operation.
The Service must verify the provided credentials and, if valid, issue a cookie with a unique identifier for the Session. The Service must send the cookie to the Reading System when returning a successful response to the logOn operation.

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

getServiceAttributes must be called to discover necessary information about the Service.
setReadingSystemAttributes must be called to provide information about the Reading System’s capabilities to the Service. If this call is successful, the Service must return true ([XML Schema 2]).

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.

Note:

A Service may issue a cookie even if logOn fails.

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. Content Selection Methods

The DAISY Online Delivery protocol supports two content selection methods:

an out-of-band method, where a User’s Content is selected or assigned through an out-of-band mechanism like a web interface or automatic content distribution system; and
a browse method, where a User can browse a Service’s collection using Operations defined by this protocol.

A Service Provider must offer Users at least one content selection method.

A Reading System should support both content selection methods for maximum interoperability, but is only required to support one method for conformance.

4.3.1. Out-of-band Content Selection Method

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

provides one or more out-of-band mechanisms for the selection/assignment of Content;
declares support for the Out-of-band Content Selection Method in the supportedContentSelectionMethods element of its serviceAttributes; and
exposes selected Content items to the Reading System through the new contentList.

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:

provides one or more browse mechanisms using the Dynamic Menus protocol feature; and
declares support for the Browse Content Selection Method in the supportedContentSelectionMethods element of its serviceAttributes.

4.4. Issuing and Transfer of Content

The steps for a Reading System to request that a Service issue Content and to Download or begin Streaming the Content are outlined in the following sections.

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.

All of the Operations identified in this section take a Content Identifier as a parameter.

getContentMetadata must be called to obtain information about the Content item. The returned metadata includes publication information, file format, the return status and size.
issueContent must be called to inform the Service that the Reading System intends to access the Content item. This operation constitutes the formal request for access. The Service must return true in order to proceed to the next step.If a Service returns false or a Fault, then the Content item has not been issued. A Reading System must not proceed to the next step unless the Service returns true.
getContentResources must be called to obtain the URIs of all the resources that constitute the Content item. A Service may allow more than one call to getContentResources for each issued Content item.Services must return an invalidParameter Fault when a Reading System calls getContentResources for a Content item that has not been issued.A Service should allow calls to getContentResources for the same Content item over more than one Session.

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.

Note:

The requirement for the Reading System to call issueContent does not require a Service to track any information about the request. For example, a Service may return true to all requests, if the Service Provider wishes.

4.4.2. Downloading and Streaming of Content

Once the Reading System has retrieved the list of resources for a Content item, the Reading System may begin downloading or streaming the resources using the URIs supplied in the resource elements.

The resource type has both a uri attribute and a localURI attribute. localURI is a local name for the Reading System to use to reference the resource, while uri is the location of the resource’s data. This system lets a Service provide resources with arbitrary URIs (such as those served by a script), while allowing Reading Systems to follow internal links in a Content item, such as in a DAISY DTB. The localURI path is relative to the root path of the Content item.

A Reading System should not use the uri attribute to name resources locally, as the URIs may resolve to scripts or other content delivery mechanisms.

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”.

Note:

A Service should allow a Reading System to access resources outside of an active Session.

4.4.3. Publishing Updates and Installments

This section explains how Service Providers can publish updates to Content items using this protocol.

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

This section is informative

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.

If the User has chosen to return any Content while the Reading System was offline, the Reading System calls returnContent(itemid) for each Content item.
The Reading System calls getContentList("expired", 0, -1).
The Reading System returns each Content item in the expired list.
The Reading System calls getContentList("new", 0, -1).
For each Content item in the new list, the Reading System calls getContentMetadata(itemid), then issueContent(itemid), then getContentResources(itemid), as described in Section 4.4.1, “Content Retrieval Sequence”.
The Reading System calls getContentList("issued", 0, -1).
For each Content item in the issued list, the Reading System calls getContentResources(itemid).

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.

Note:

This protocol does not provide any trust mechanism; there is no method for Reading Systems to provide their public keys to a Service using this protocol. Services supporting PDTB2 must use some out-of-band method to register keys from Reading System manufacturers.

There is no mechanism for expiring keys in this protocol.

4.4.5.1. Declaring PDTB2 Support

If a Reading System supports PDTB2, it should inform the Service by including a supportedContentProtectionFormats element with the value PDTB2, and a keyRing element listing the names of the keys in its key ring, in its readingSystemAttributes. The key names provided may be some or all of the public keys the Reading System supports.

To indicate that a Service supports PDTB2 key exchange, the Service must include an operation element with the value PDTB2_KEY_PROVISION in its serviceAttributes.

4.4.5.2. Identifying PDTB2 Content

If a Content item is protected using PDTB2, a Service must include a meta element in its contentMetadata named pdtb2:specVersion with the value 2005-1.

In addition, the mimeTypes of protected resources in the resources list must be as defined in section 4.1.1, “Package file”, of the [PDTB2] specification. Those MIME types begin with application/x-pdtb….

4.4.5.3. Accessing PDTB2 Content

Any Reading System may access Content items marked as PDTB2-protected. Reading Systems that do not support PDTB2 will not be able to render some or all of the resources.

A PDTB2-protected Content item must have an Authorization Object (AO) in its resources. The Reading System can inspect the AO for the name of the key that secures the key required to decrypt the Content item. If the Reading System does not have the key to access an encrypted section of an AO, it may request a Key Exchange Object (KXO) from the Service.

To obtain a KXO, a Reading System must call the getKeyExchangeObject operation with the name of the requested key.

The Service may choose any of the keys supplied in the readingSystemAttributes to encrypt the KXO. If the Service does not have any of the keys or if the User is not authorized to access the Content item, then the Service must reply with an invalidParameter Fault.

If the Reading System receives a valid KXO from the Service, the Reading System can then use that KXO to access the key in the AO that unlocks the protected Content item.

4.5. Service Announcements

The DAISY Online Delivery protocol allows Service Providers to deliver service announcements to a User’s Reading System. A service announcement is a short message in text and/or audio format that conveys information, such as an alert about expected Service down time or a warning about overdue Content items, to the User.

To indicate that a Service supports service announcements, the Service must include an operation element with the value SERVICE_ANNOUNCEMENTS in its serviceAttributes.

Services are not required to support service announcements. Reading Systems should be able to retrieve and render text and audio service announcements for maximum interoperability.

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.

This section is normative

The DAISY Online Delivery protocol defines two types of questions for navigating a menu system:

Multiple Choice Questions

Multiple choice questions are a set of options to pick from. A multiple choice question is represented by the multipleChoiceQuestion child element of the questions type.

Input Questions

Input questions allow the User to respond with text and/or audio input. An input question is represented by the inputQuestion child element of the questions type.

A Service must specify if an input question requires a numeric, alphanumeric or audio-based response in the inputTypes child element of the inputQuestion type. Multiple input types means that any one of the types specified may be used.

4.7.5. End Points

This section is normative

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:

a label, which may provide an informative or concluding statement for the User, such as confirmation of a purchase or thanks for completing a survey; or
a contentListRef containing the ID of a contentList, when the menu sequence has resulted in the generation of a list of Content items that the User may then access.

4.7.6. Reserved IDs

This section is normative

There are three reserved question identifier values:

default

Indicates that the Reading System is requesting the root question. Refer to Section 4.7.2, “Root Question”.

search

Indicates that the Reading System is requesting the search menu.

A Service must explicitly declare whether or not it supports this value with the supportsSearch element of its serviceAttributes.

back

Indicates that the Reading System has requested to step back one menu in the sequence.

A Service must explicitly declare whether or not it supports this value with the supportsServerSideBack element of its serviceAttributes.

A Service must return an invalidParameter Fault if a Reading System calls the getQuestions operation with the back value when no prior call has been made to this operation in the active session.

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. API Reference

This section is normative

5.1. Required Operations

This section documents the protocol operations that all Services must support.

5.1.1. The `logOn` Operation

Logs a Reading System on to a Service.

Request parameters

username

Type: xs:string [XML Schema 2]

The account name used to access the Service.

password

Type: xs:string [XML Schema 2]

The account’s password.

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the logon was successful.

Faults

Retrieves Service properties, including information on which optional Operations the Service supports.

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.

Request parameters

getServiceAttributes takes no parameters.

Response

Type: serviceAttributes

Contains the attributes of the Service.

Faults

internalServerError, invalidOperation, noActiveSession

5.1.8. The `getContentList` Operation

Retrieves a list of Content items.

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.)

Request parameters

id

Type: xs:NMTOKEN [XML Schema 2]

The identifier for the content list to retrieve.

The following three values are reserved and must not be used as identifiers except as defined below.

issued

Refers to a list of Content items that the Service currently has recorded as issued to the User (refer to issueContent).

The list must include all Borrowable Content items that have been issued regardless of whether they have been downloaded or not. The list may include Purchasable Content items that have been issued. The list excludes Content items that have expired.

Services that provide Borrowable Content must recognize this identifier.

new

Refers to a list of Content items available to issue to a User.

The list excludes all Content items that are issued.

Services that support the Out-of-band Content Selection Method must recognize this identifier.

expired

Refers to a list of Content items that have been issued to the User but have expired.

firstItem

Type: xs:int [XML Schema 2]

When retrieving a subset of a contentList, contains the index of the first item in the subset to retrieve. The first item in the list has the index 0.

lastItem

Type: xs:int [XML Schema 2]

When retrieving a subset of a contentList, contains the index of the last item in the subset to retrieve. The value -1 indicates a request to retrieve all items from firstItem to the end of the list.

Response

Type: contentList

Contains the requested Content list (or a segment of the list).

The value of the id attribute of the returned contentList must match the value of the id parameter passed to the getContentList operation.

If the value of the firstItem and/or lastItem parameters is invalid, a service must return an empty contentList with the value of its totalItems attribute set to the total number of items in the entire contentList.

Faults

internalServerError, invalidOperation, invalidParameter, noActiveSession

5.2. Optional Operations

This section documents additional protocol operations that a Service may support. Refer to Content Selection Methods for conditions when certain of these optional operations become required.

5.2.1. The `getServiceAnnouncements` Operation

Retrieves any announcements from the Service that a User has not yet read.

Request parameters

getServiceAnnouncements takes no parameters.

Response

Type: announcements

Contains the announcements from the Service.

Faults

internalServerError, invalidOperation, operationNotSupported, noActiveSession

5.2.2. The `markAnnouncementsAsRead` Operation

Marks the specified announcement(s) as read.

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

Request parameters

read

Type: read

Contains the IDs of the announcements to mark as read.

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the announcements were successfully marked as read by the Service.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.3. The `returnContent` Operation

Notifies the Service that the specified Content item has been deleted from the Reading System.

The specified Content item is no longer issued to the User after a successful call to this operation.

A Reading System must not call this function for a Content item that has a requiresReturn attribute with a value of false.

A Reading System must delete the Content item before calling returnContent. A Reading System must not call returnContent for a Content item that was not issued to the User on that Reading System.

Note:

This protocol cannot guarantee that a Reading System has actually deleted the Content item before calling returnContent. The Service receiving a call to this operation does not constitute proof that the Content item has been removed. A DRM solution should be used when Service Providers require a copy prevention mechanism.

Request parameters

contentID

Type: xs:string [XML Schema 2]

The Content Identifier of the Content item being returned.

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the Content item was returned successfully.

returnContent must either return true or a Fault; it must not return false.

A Service must return true if the Content item has already been returned prior to this call.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.4. The `setBookmarks` Operation

Requests that a Service store the supplied bookmarks for a Content item.

This operation only supports the storage of bookmarks for one Content item at a time.

Request parameters

contentID

Type: xs:string [XML Schema 2]

The Content Identifier of the Content item the bookmarks are associated with.

bookmarkSet

Type: bookmarkSet

Contains the bookmarks to store.

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the Service successfully saved the bookmarks.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.5. The `getBookmarks` Operation

Retrieves the bookmarks for a Content item from a Service.

Request parameters

contentID

Type: xs:string [XML Schema 2]

The Content Identifier of the Content item the bookmarks are being retrieved for.

Response

Type: bookmarkSet

Contains the bookmarks for the Content item.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.6. The `getQuestions` Operation

Retrieves a question from the series of questions that comprise the dynamic menu system.

Request parameters

userResponses

Type: userResponses

Contains the response to a question, or, as defined in userResponse, one of the three reserved IDs: default, search or back.

Response

Type: questions

Contains one or more multiple choice or input questions. May also contain a Label or contentListRef child elements.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.7. The `getKeyExchangeObject` Operation

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

Request parameters

requestedKeyName

Type: xs:string [XML Schema 2]

The identifier of the requested key.

Response

Type: KeyExchange

A [PDTB2] Key Exchange Object, containing the requested key encrypted using one of the keys identified in the Reading System’s key ring.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.3. Faults

When a Service responds to an operation with a SOAP Fault, an instance of one of the following types must be the child of the detail element.

Each of these Fault types has a reason child element, a string which can be used to send debugging information to the Reading System. This information should not be rendered to the User in most circumstances.

More than one Fault condition may be triggered when an operation is called. For example, an unsupported operation may be called outside of an active Session. In the case of two or more Fault conditions being applicable, the Fault that appears first in the fault precedence listed below must be issued. The fault precedence is as follows:

internalServerError
noActiveSession
operationNotSupported
invalidOperation
invalidParameter

5.3.1. The internalServerError Fault

Condition: an internal server error occurred on the Service and the execution of the operation was halted.

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

Condition: the operation is not allowed when there is no active session.

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

Condition: the operation is not supported by the Service.

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

5.3.4. The invalidOperation Fault

Condition: the operation is not valid in the current context

This Fault is issued when a Reading System during an active Session calls an operation at a stage when the call of another operation, or a set of other operations, is required.

5.3.5. The invalidParameter Fault

Condition: an invalid parameter was passed with the operation request.

This Fault is issued when a Reading System calls an operation with a parameter that the Service does not recognize, allow, or support.

6. Type Reference

This section is normative

The following sections describe the elements defined in the [XML Schema 1] schema do-types-10.xsd, which is a normative part of the abstract WSDL document (refer to Appendix A, WSDL Abstract Definition).

Note:

The following simplified set of SGML syntax rules has been used throughout this section to define the content models:

parentheses are used to group sets of elements and/or other groups;
within groups, a comma ‘,’ indicates required sequences and a pipe ‘|’ indicates optional sequences; and
a question mark ‘?’ after a group or element indicates the item must occur zero or one times, a plus sign ‘+’ indicates one or more, an asterisk ‘*’ zero or more and no modifier means the element or group must occur exactly once.

In the case of any discrepancies between the descriptions in this specification and the definitions in do-types-10.xsd, the latter shall be taken as authoritative.

6.1. The announcements Type

A list of Service announcements.

Used By

getServiceAnnouncements (response)

Content Model

( announcement* )

6.1.1. announcements Examples

Example 6.1. announcements

<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.2. The bookmarkSet Type

Used By

setBookmarks (parameter)getBookmarks (response)

Content Model

( title, uid, lastmark?, ( bookmark | hilite )* )

6.3. The contentList Type

A full or partial list of Content items.

Used By

getContentList (response)

Content Model

( label?, contentItem* )

Attributes

totalItems

The total number of contentItems in the whole list. If this is just a part of the list, then totalItems will be greater than the number of contentItems returned; otherwise, they will be equal.

Use: required

Data type: xs:int

firstItem

The 0-based index of the first contentItem in this contentList within the whole list. This attribute must be provided if this is a partial list. If this attribute is present, the lastItem attribute must also be present.

Use: optional

Data type: xs:int

lastItem

The 0-based index of the last contentItem in this contentList within the whole list. This attribute must be provided if this is a partial list. If this attribute is present, the firstItem attribute must also be present.

Use: optional

Data type: xs:int

id

The identifier of the contentList.

The identifier may be one of the three reserved values, new, issued or expired, or may be an arbitrary value, typically exposed in a contentListRef at an end point in a dynamic menu operation sequence.

Services should persist contentList identifiers for the duration of a Session. Services must not expose multiple contentLists with the same arbitrary identifier during the same session.

Use: required

Data type: xs:NMTOKEN

6.3.1. contentList Examples

Example 6.2. A complete contentList with audio labels

This example shows a complete contentList (the firstItem and lastItem attributes are not present in the root element).

<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>

Example 6.3. A partial contentList

This example shows a partial contentList (firstItem and lastItem attributes specify which of the items are included in this segment).

<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. The contentMetadata Type

The metadata of a Content item.

Used By

getContentMetadata (response)

Content Model

( sample?, metadata )

Attributes

category

The publication category of the Content item.

Reading Systems may use the value provided here to categorize or sort Content items.

Any value is allowed. The values BOOK, MAGAZINE, NEWSPAPER and OTHER are recommended for those Content items which match one of these terms.

Use: optional

Data type: xs:string

requiresReturn

Specifies whether the Service requires this Content item to be returned.

If this attribute is true, it is a contract from the Service to the Reading System that, if the Content item is issued, the Reading System will at some point return the Content item.

Reading Systems should present Users with appropriate prompts if they try to return a Purchasable Content item.

Use: required

Data type: xs:boolean

6.4.1. contentMetadata Examples

Example 6.4. Example contentMetadata

This example shows the contentMetadata for a borrowed book that is [PDTB2] protected (see Section 4.4.5, “Rights management”).

<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.5. The KeyExchange Type

Used By

getKeyExchangeObject (response)

Content Model

( Issuer, ( ds:KeyInfo | Keys )+ )

6.6. The keyRing Type

A list of key names.

Used By

Content Model

( item* )

6.7. The questions Type

A sequence of questions.

The questions element must contain either:

exactly one contentListRef; or
exactly one label; or
one or more multipleChoiceQuestions and/or inputQuestions, in any order.

If the questions element contains a contentListRef or a label child element, it is an endpoint to the sequence of questions that comprise a dynamic menu.

For informative examples on the usage of the questions type, refer to the [Dynamic Menus Primer].

Used By

getQuestions (response)

Content Model

( ( multipleChoiceQuestion | inputQuestion )+ | contentListRef | label )

6.8. The read Type

A list of announcement identifiers.

Used By

markAnnouncementsAsRead (parameter)

Content Model

( item* )

6.9. The readingSystemAttributes Type

Specifies Reading System properties.

The properties specified are valid until the end of the Session.

Used By

setReadingSystemAttributes (parameter)

Content Model

( manufacturer, model, serialNumber?, version, config )

This element is extensible.

6.9.1. readingSystemAttributes Examples

Example 6.5. readingSystemAttributes for a portable audio-centric Reading System

This example shows readingSystemAttributes for a small portable audio-centric Reading System (single format support, numeric input, no text-to-speech capabilities, PDTB2 support).

<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>

Example 6.6. readingSystemAttributes for a more functional Reading System

This example shows the readingSystemAttributes for a more functional Reading System, such as a software Reading System (multi-format support, full keyboard input, built-in text-to-speech capabilities but in this case no PDTB2 support).

<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. The resources Type

A list of all the resources that constitute the Content item.

Used By

getContentResources (response)

Content Model

( resource+ )

Attributes

returnBy

Specifies the time when the Service Provider requires this Content item to be returned.

This attribute may be present when the requiresReturn attribute of this Content item’s contentMetadata is true, and must not be present when that attribute is false.

This attribute may not change value while the Content item is issued.

Unlike the requiresReturn attribute of contentMetadata, this attribute does not constitute a contract.

Use: optional

Data type: xs:dateTime

lastModifiedDate

The last modified time of the Content item.

Use: optional

Data type: xs:dateTime

6.10.1. resources Examples

Example 6.7. A resources instance using script URIs

This example shows a resources instance where the uri attribute refers to a script that does not expose the names of the resources.

<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. The serviceAttributes Type

Properties of the Service.

The properties specified must be constant for the duration of the Session.

Used By

getServiceAttributes (response)

Content Model

( serviceProvider?, service?, supportedContentSelectionMethods, supportsServerSideBack, supportsSearch, supportedUplinkAudioCodecs, supportsAudioLabels, supportedOptionalOperations )

6.11.1. serviceAttributes Examples

Example 6.8. serviceAttributes for a minimal library Service

This example shows the serviceAttributes for a Service that only supports the out-of-band Content selection method.

<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>

Example 6.9. serviceAttributes for a fuller Service

This example shows the serviceAttributes for a Service that supports both Content Selection Methods and provides some or all of its Content protected using [PDTB2].

<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>

6.12. The userResponses Type

A set of User responses to questions provided by the Service.

For informative examples of the userResponses type, refer to the [Dynamic Menus Primer].

Used By

getQuestions (parameter)

Content Model

( userResponse+ )

6.13. Element Reference

additionalTransferProtocols

Specifies any additional transfer protocols that are supported by the Reading System, beyond HTTP and HTTPS.

Properties

Content model: ( protocol+ )

Parent(s): config

announcement

A Service announcement.

Properties

Content model: ( label )

Parent(s): announcements

Attributes

id

The identifier of this announcement. This identifier is only valid for the duration of a Session.

Use: required

Data type: xs:NMTOKEN

type

A value that indicates the nature of this announcement.

Use: optional

Enumeration:

WARNING
ERROR
INFORMATION
SYSTEM

Default Value: INFORMATION

priority

The priority of this announcement. 1 is the highest priority and 3 is the lowest.

Use: optional

Integer Set:

minimum value: 1
maximum value: 3

Default Value: 3

audio

Properties

Content model: empty element

Parent(s): label

Attributes

uri

The URI of the audio component of the label.

Use: required

Data type: xs:anyURI

rangeBegin

The byte offset of the start of the audio label in the resource named in the uri attribute. If the rangeBegin attribute is not present, the start offset is 0.

Use: optional

Data type: xs:long

rangeEnd

The byte offset of the end of the audio label in the resource named in the uri attribute. If the rangeEnd attribute is not present, the end is the last byte of the resource.

Use: optional

Data type: xs:long

size

The size, in bytes, of the label’s audio data.

Use: optional

Data type: xs:long

bandwidth

An estimate of the bandwidth that the Reading System allocates for the Session, in kilobits per second.

Properties

Data type: xs:int

Parent(s): config

choice

Properties

Content model: ( label )

Parent(s): choices

Attributes

id

Use: required

Data type: xs:NMTOKEN

choices

Properties

Content model: ( choice+ )

Parent(s): multipleChoiceQuestion

codec

The codec’s [MIME] type.

Properties

Data type: xs:string

Parent(s): supportedUplinkAudioCodecs

id

The Content Identifier of this Content item.

Use: required

Data type: xs:string

lastModifiedDate

The last modified time of the Content item.

Use: optional

Data type: xs:dateTime

contentListRef

The identifier of a contentList.

A contentListRef as a child of the questions element indicates an endpoint of the sequence of questions that comprise a dynamic menu.

Properties

Data type: xs:NMTOKEN

Parent(s): questions

data

The base64-encoded data of an audio User response.

Services must accept audio in the [RIFF WAVE] format. Services may support additional audio formats, and must specify those formats in serviceAttributes.

Properties

Allowed values: xs:base64Binary

Parent(s): userResponse

input

Properties

Content model: empty element

Parent(s): inputTypes, supportedInputTypes

Attributes

type

Use: required

Enumeration:

TEXT_NUMERICThe Reading System supports numeric input.The Service allows numeric-only responses to the question.
TEXT_ALPHANUMERICThe Reading System supports text and numeric input.The Service allows text and numeric responses to the question.
AUDIOThe Reading System supports audio input.The Service allows audio responses to the question.

inputQuestion

An input field that accepts a text or audio response.

Properties

Content model: ( inputTypes, label )

Parent(s): questions

Attributes

id

Use: required

Data type: xs:NMTOKEN

inputTypes

Specifies which input types the Service will accept in response to the question.

Properties

Content model: ( input+ )

Parent(s): inputQuestion

item

Properties

Data type: xs:string

Parent(s): keyRing, read

label

A multi-purpose label, containing text and optionally audio.

To achieve maximum interoperability, Services should support the provision of audio labels, as Reading Systems may require them in order to render Service messages to the user.

Properties

Content model: ( text, audio? )

Parent(s): announcement, choice, contentItem, contentList, inputQuestion, multipleChoiceQuestion, questions, service, serviceProvider

Attributes

xml:lang

The language of the label.

Use: required

dir

The direction of the text.

Use: optional

Enumeration:

ltrLeft-to-right.
rtlRight-to-left.

manufacturer

The manufacturer of the Reading System.

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

metadata

Bibliographic and other metadata of the Content item.

Elements in the Dublin Core namespace are normatively defined by [Dublin Core]. The value of the Dublin Core identifier element must match the Content Identifier of the Content item.

Additional, non-Dublin Core metadata may be provided using the generic meta element.

The prefix pdtb2: in the name attribute of a meta element is reserved to refer to properties of [PDTB2].

The value pdtb2:specVersion in the name attribute of a meta element means that the Content item is protected using [PDTB2]

Properties

Content model: ( dc:title, dc:identifier, dc:publisher?, dc:format, dc:date?, dc:source?, dc:type*, dc:subject*, dc:rights*, dc:relation*, dc:language*, dc:description*, dc:creator*, dc:coverage*, dc:contributor*, narrator*, size, meta* )

This element is extensible.

Parent(s): contentMetadata

method

Properties

Allowed values:

OUT_OF_BAND
This Service supports the Out-of-band Content Selection Method.
BROWSE
This Service supports the Browse Content Selection Method.

Parent(s): supportedContentSelectionMethods

mimeType

Properties

Content model: empty element

Parent(s): supportedMimeTypes

Attributes

type

A [MIME] type.

Use: required

Data type: xs:string

xml:lang

Use: optional

model

The model name or designation of the Reading System.

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

multipleChoiceQuestion

Properties

Content model: ( label, choices )

Parent(s): questions

Attributes

id

Use: required

Data type: xs:NMTOKEN

allowMultipleSelections

Specifies whether multiple selections are allowed in the User response to this question.

Use: optional

Data type: xs:boolean

Default Value: false

narrator

In the case of audio Content, the name of the narrator.

Properties

Data type: xs:string

Parent(s): metadata

operation

One of the optional operations or groups of optional operations defined below.

Properties

Allowed values:

SET_BOOKMARKS
This Service supports the setBookmarks operation.
GET_BOOKMARKS
This Service supports the getBookmarks operation.
DYNAMIC_MENUS
This Service supports the getQuestions operation.
SERVICE_ANNOUNCEMENTS
This Service supports the getServiceAnnouncements and markAnnouncementsAsRead operations.
PDTB2_KEY_PROVISION
This Service supports the getKeyExchangeObject operation.

Parent(s): supportedOptionalOperations

preferredUILanguage

The user’s preferred language of communication with the Service.

Properties

Data type: xs:language

Parent(s): config

protectionFormat

Properties

Allowed values:

PDTB2
This Reading System supports DAISY Protected Digital Talking Book 2.

Parent(s): supportedContentProtectionFormats

protocol

The [MIME] type of the resource.

Use: required

Data type: xs:string

size

The size of the resource in bytes.

Use: required

Data type: xs:long

localURI

The local relative path of the resource.

The value of this attribute is a URI relative to the Content item’s root directory.

Use: required

Data type: xs:anyURI

lastModifiedDate

The last modified time of the resource.

Use: optional

Data type: xs:dateTime

sample

A sample of the Content item that the User may retrieve without the Content item being issued.

Properties

Content model: empty element

Parent(s): contentMetadata

Attributes

id

The Content Identifier of the sample.

Reading Systems may retrieve the sample’s resource list by calling getContentResources with this identifier as the parameter. Reading Systems must not call issueContent using the identifier of a sample.

Use: required

Data type: xs:string

serialNumber

The serial number of the Reading System, if such is available.

Properties

supportedContentProtectionFormats

Specifies which Content protection (Digital Rights Management) standards the Reading System supports, if any.

Properties

Content model: ( protectionFormat* )

Parent(s): config

supportedContentSelectionMethods

A list of Content Selection Methods supported by this Service. A Service must support at least one of the two methods.

Properties

Content model: ( method{1, 2} )

Parent(s): serviceAttributes

supportedInputTypes

The means of User input to the Service that the Reading System supports.

If the Reading System does not support any means of input, the inputTypes element must be empty.

Properties

Content model: ( input* )

Parent(s): config

supportedMimeTypes

Specifies which [MIME] types the Reading System supports.

This applies to both Content and Service messages (labels).

Specifies whether this Service supports the inclusion of audio in labels.

If the value of this element is true and the requiresAudioLabels element of readingSystemAttributes is true in the Reading System’s most recent call to setReadingSystemAttributes, then the Service must include the audio element in each label it provides.

Properties

Data type: xs:boolean

Parent(s): serviceAttributes

supportsMultipleSelections

Specifies whether the Reading System supports multiple selections for a multipleChoiceQuestion.

A response to a question. Either the value attribute (for inputQuestion or multipleChoiceQuestion responses) or the data element (for audio-based responses) must be present, unless a the questionID attribute’s value is one of the reserved identifiers given below.

If a userResponses element is a response to a multipleChoiceQuestion where multiple selections are allowed, then multiple userResponse elements must be used to represent each selection (where each userResponse refers to the same question via the questionID attribute).

Properties

Content model: ( data? )

Parent(s): userResponses

Attributes

questionID

The identifier of the question being answered.

The following three values of this attribute are reserved for use as defined below:

defaultThe root question (main menu) from the Service. (This value is used to initiate a dynamic menu operation sequence, and does not reflect an answered question.)A Service that supports Dynamic Menus must support this reserved identifier.
searchThe Service’s search menu.A Service is not required to support the search reserved identifier. A Service must explicitly declare whether it supports this identifier in serviceAttributes.
backThe previous question from the Service during a dynamic menu operation sequence.A Service is not required to support the back reserved identifier. A Service must explicitly declare whether it supports this identifier in serviceAttributes.

Use: required

Data type: xs:NMTOKEN

value

In the case of an inputQuestion, this attribute contains the textual response. In the case of a multipleChoiceQuestion, it contains the ID of the choice.

Use: optional

Data type: xs:string

version

The version of the Reading System.

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

References

Normative References

[DAISY 2.02] DAISY 2.02 Specification . Markus Gylling, et al. 28 February 2001.

[Document-Literal Conformance] Child Element for Document-Literal Bindings (part of [WS-I Basic Profile 1.1]) . Keith Ballinger, et al. 24 August 2004.

[Dublin Core] Dublin Core Metadata Element Set, Version 1.1 . Dublin Core Metadata Initiative. 14 January 2008.

[HTTP 1.1] HyperText Transfer Protocol 1.1, RFC 2616 . R. Fielding, et al. June 1999.

[HTTP Cookies] HTTP cookies in WS-I Basic Profile 1.1 (part of [WS-I Basic Profile 1.1]) . Keith Ballinger, et al. 24 August 2004.

[ISO 3166] ISO 3166-1 – Codes for the representation of names of countries and their subdivisions – Part 1: Country codes . ISO – International Organization for Standardization.

[MIME] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, RFC 2046 . N. Freed, et al. November 1996.

[MTOM] SOAP Message Transmission Optimization Mechanism . M. Gudgin, et al. January 2005.

[PDTB2] DAISY Protected Digital Talking Book 2 . Neil Bernstein. George Kerscher. January 2005.

[RFC 2109] HTTP State Management Mechanism . D. Kristol. L. Montulli. February 1997.

[RFC 2119] Key words for use in RFCs to Indicate Requirement Levels . S. Bradner. March 1997.

[RFC 2396] Uniform Resource Identifiers (URI): Generic Syntax . T. Berners-Lee, et al. August 1998.

[RFC 2617] HTTP Authentication: Basic and Digest Access Authentication . J. Franks, et al. June 1999.

[RIFF WAVE] Multimedia Programming Interface and Data Specifications 1.0 (Unofficial transcript) . IBM Corporation. Microsoft Corporation. August 1991.

[SOAP 1.1] Simple Object Access Protocol 1.1 . Don Box, et al. 8 May 2000.

[SSL 3.0] Secure Sockets Layer 3.0 . Alan O. Freier, et al. 18 November 1996.

[TLS 1.0] Transport Layer Security 1.0, RFC 2246 . T. Dierks. C. Allen. January 1999.

[WS-I Basic Profile 1.1] WS-I Basic Profile 1.1 . Keith Ballinger, et al. 24 August 2004.

[WS-I Basic Profile 1.1 Conformance Targets] WS-I Basic Profile 1.1 Conformance Targets (part of [WS-I Basic Profile 1.1]) . Keith Ballinger, et al. 24 August 2004.

[WSDL 1.1] Web Services Definition Language 1.1 . Erik Christensen, et al. 15 March 2001.

[XML Schema 1] XML Schema Part 1: Structures Second Edition . Henry S. Thompson, et al. 28 October 2004.

[XML Schema 2] XML Schema Part 2: Datatypes Second Edition . P. V. Biron. Ashok Malhotra. 28 October 2004.

[Z39-86.2005] ANSI/NISO Z39-86.2005 – Specifications for the Digital Talking Book . Michael Moodie, et al. 21 April 2005.

[Z39-86.2005-BOOKMARKS] Portable Bookmarks and Highlights (part of [Z39-86.2005]) . Michael Moodie, et al. 21 April 2005.

Informative References

[Dynamic Menus Primer] DAISY Online Delivery Protocol – Dynamic Menus Primer . Kenny Johar, et al. 2 April 2010.

[Z39-86.2002] ANSI/NISO Z39-86.2002 – Specifications for the Digital Talking Book . Michael Moodie, et al. 6 March 2002.

Appendix A. WSDL Abstract Definition

This appendix is normative

The [WSDL 1.1] entities defined in the accompanying do-wsdl-10.wsdl document constitute the abstract Web Service contract that all compliant Services must adhere to.

The Service Provider must publish a WSDL document at some URI. The WSDL document must import http://www.daisy.org/projects/daisy-online-delivery/do-wsdl-10.wsdl into the namespace http://www.daisy.org/ns/daisy-online/. It must define a service with one port bound to DaisyOnlineService in the http://www.daisy.org/ns/daisy-online/ namespace.

Example A.1. An example published WSDL document

<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://www.daisy.org/ns/daisy-online/"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             targetNamespace="http://www.daisy.org/ns/daisy-online/">

  <import namespace="http://www.daisy.org/ns/daisy-online/"
          location="http://www.daisy.org/projects/daisy-online-delivery/do-wsdl-10.wsdl"/>
  
  <service name="example">
    <documentation>
      Example DAISY Online Service
    </documentation>

    <port name="examplePort" binding="tns:DaisyOnlineService">
      <soap:address location="http://example.org/daisy-online/"/>
    </port>
  </service>
</definitions>

Appendix B. Acknowledgments

This appendix is informative

The following individuals were members in good standing of the DAISY Online Working Group at the time of the publication of this specification:

Johan Abbors, Pratsam
Hiro Fujimori, Plextor
Geoff Gilmour-Taylor, CNIB
Markus Gylling, DAISY Consortium (co-chair)
Kenny Johar, Vision Australia (co-chair)
Jelle Martijn Kok, Solutions Radio
Simon Roy, HumanWare
Nick Williamson, RNIB

The following individuals are acknowledged for their contribution, either as former members of the DAISY Online Working Group, or as individual contributors:

David Andrews, Minnesota State Services for the Blind
Neil Bernstein, NLS
Sean Brooks, CNIB
Ed Chandler, RNIB
Gerry Chevalier, HumanWare
Andrew Furlong, Vision Australia
Matt Garrish, CNIB
Leon Gulikers, Dedicon
Kathy Kahl, DAISY
Dinesh Kaushal, Code Factory
Mattias Karlsson, Dolphin
Greg Kearney, Individual Supporter
George Kerscher, DAISY
Dominic Labbé, HumanWare
Clive Lansink, RNZFB
Lynn Leith, DAISY
Tatsu Nishizawa, Plextor
Peter Osborne, RNIB
James Pritchett, RFB/D
Karel Raven, Solutions Radio
Ron Stewart, Dolphin US
Marc Van der Aa, Plextor Europe
Markus Wildi, Swiss Library for the Blind

Specification for the DAISY Online Delivery Protocol v1

Specification for the DAISY Online Delivery Protocol v1

Status of this Document

1. Introduction

2. Terminology

Note:

Note:

Note:

3. Underlying Technologies

3.1. HTTP

Note:

3.1.1. HTTP Cookies

3.1.2. HTTPS

Security Considerations

3.1.3. HTTP Basic Authentication

Security Consideration

Note:

3.1.4. HTTP Range Headers

3.2. WS-I

3.2.1. Basic Profile 1.1

3.2.2. WSDL Binding Style

4. Protocol Fundamentals

4.1. Service Models

4.1.1. Lending Model

4.1.1.1. Service Requirements

4.1.1.2. Reading System Requirements

4.1.1.3. Content Expiry

Note:

4.1.2. Acquisition Model

4.1.2.1. Service Requirements

4.1.2.2. Reading System Requirements

4.2. User Authentication and Session Management

4.2.1. Session Initialization

Note:

4.2.2. Session Duration

4.3. Content Selection Methods

4.3.1. Out-of-band Content Selection Method

4.3.2. Browse Content Selection Method

4.4. Issuing and Transfer of Content

4.4.1. Content Retrieval Sequence

Note:

4.4.2. Downloading and Streaming of Content

Note:

4.4.3. Publishing Updates and Installments

4.4.4. Content Synchronization sequence

4.4.5. Rights management

Note:

4.4.5.1. Declaring PDTB2 Support

4.4.5.2. Identifying PDTB2 Content

4.4.5.3. Accessing PDTB2 Content

4.5. Service Announcements

4.5.1. New Announcements

4.5.2. Read Announcements

4.6. Bookmarks

Note:

4.7. Dynamic Menus

4.7.1. Support

4.7.2. Root Question

4.7.3. Navigation

4.7.4. Question Types

4.7.5. End Points

4.7.6. Reserved IDs

5. API Reference

5.1. Required Operations

5.1.1. The logOn Operation

5.1.2. The logOff Operation

5.1.3. The setReadingSystemAttributes Operation

5.1.4. The issueContent Operation

5.1.5. The getContentMetadata Operation

5.1.6. The getContentResources Operation

5.1.7. The getServiceAttributes Operation

5.1.8. The getContentList Operation

5.2. Optional Operations

5.2.1. The getServiceAnnouncements Operation

5.2.2. The markAnnouncementsAsRead Operation

5.2.3. The returnContent Operation

Note:

5.2.4. The setBookmarks Operation

5.2.5. The getBookmarks Operation

5.2.6. The getQuestions Operation

5.1.1. The `logOn` Operation

5.1.2. The `logOff` Operation

5.1.3. The `setReadingSystemAttributes` Operation

5.1.4. The `issueContent` Operation

5.1.5. The `getContentMetadata` Operation

5.1.6. The `getContentResources` Operation

5.1.7. The `getServiceAttributes` Operation

5.1.8. The `getContentList` Operation

5.2.1. The `getServiceAnnouncements` Operation

5.2.2. The `markAnnouncementsAsRead` Operation

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