Specification for the DAISY Online Delivery Protocol V2.0.2

Approved June 9, 2015 by the DAISY Consortium Board.

Minor update issued by the DAISY Online Delivery Working Group October 26, 2015.

This version:

https://daisy.org/activities/standards/dodp/specification-for-the-daisy-online-delivery-protocol-v2-0-2/

Previous versions:

https://daisy.org/activities/standards/dodp/specification-for-the-daisy-online-delivery-protocol-v2-0-1/

https://daisy.org/activities/standards/dodp/specification-for-the-daisy-online-delivery-protocol-v1/

Editors:

Copyright Notice:

All content of the DAISY Structure Guidelines is licensed for others to copy, distribute, and display only verbatim copies. No changes may be made and no derivative works based upon it.
Copyright © by the DAISY Consortium, Creative Commons License: No Derivative Works

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 D, Acknowledgments.

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/support/contactus.php.

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

Table of Contents

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 media 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 content 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 automatically download their new content as a background process. 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.

2. Terminology

This section is normative

The keywords “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.

Access
Access to Content is defined by when a Reading System requests to either Download or Stream a contentItem by calling getContentResources.
Automatic Download
Downloads that are managed automatically by a Reading System often run in the background. For example a Service may support the Automatic Download of newspapers to ensure the Content is available in a timely manner but may not support Automatic Download of audio books to reduce bandwidth usage
Bookshelf
A collection of Content currently assigned and available to a User.
Content
A resource or resources made available by a Service Provider through a Service, such as DAISY files, braille files or EPUB files. (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 contentItem 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.
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.
Operation
A [WSDL 1.1] operation. An action supported by the Service.
Progress State
The state of a given Download or Streaming activity. Valid state values are: START, PAUSE, RESUME, FINISH. These states can be used to monitor content access activity by the Service Provider.
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.
Restricted Download
This is a type of Download that looks to protect Content downloaded to Reading Systems. For example a Reading System supports Restricted Downloads if it can ensure the Content is locked to the Reading System. Examples of this support include;

1. Locking downloaded Content using encryption so it may only be consumed on the given Reading System.
2. Stopping the downloaded Content from being copied to external media. For example a Reading System may not support copying media to external devices and therefore can support Restricted Downloads.

Return Content

Remove access to a Content item on the Reading System. A Content item is returned when the Reading System has denied access to and/or removed any locally-stored data and called the returnContent operation to notify the Service to revoke access and remove from the User’s bookshelf.

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 such as an Online Library. 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.
Terms of Service
The Terms of Service required by some Services that a User must agree to prior to being authorised to access Service functions. These Terms are supplied as text (and optionally audio).
Type
An [XML Schema 2] datatype.
User
A person who interacts with a Service using a Reading System and/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).

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.3, “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.

A Service is recommended to return a 307 Moved Temporarily HTTP status code during Service down time if an alternative temporary hosting location can be provided.

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

1. [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.
2. 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 honour 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).

It is strongly recommended for Services to support range headers as it would otherwise be impossible to provide streaming operations or resume downloads.

However, as it is not possible to require support for range headers on Service Delegates, Reading Systems must be able to handle Services 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 Compliance

A compliant Service must implement all methods defined in this specification but can respond to method calls with the operationNotSupported Fault for one or more methods listed as Optional – See Required Operations / Optional Operations.

4.1.1. Service Requirements

The following conditions apply to any item of Content:

• All borrowed Content items must be listed in the User’s bookshelf contentList until it is returned or has expired; and
• The Service must allow the Reading System to call returnContent at any time during any Session to return a Content item.
• Acquired Content items may be listed in the User’s bookshelf contentList. This specification does not specify the lifetime of such Content in the bookshelf contentList.

4.1.2. Reading System Requirements

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

If a Reading System supports resource packages the supportedContentFormats element needs to contain a contentFormat with the value application/zip among the other supportedContentFormats. See supportedContentFormats element definition for further information.

4.1.3. Content Expiry

This protocol defines the use of the returnBy attribute of the contentItem type to assist in the automatic return of Content by a Reading System, however 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. Services must include time zone information in the returnBy attribute. It is the responsibility of Reading Systems to keep a synchronized reference clock during online operations. Reading Systems should also make a best effort to maintain the accuracy while offline.

Reading Systems should communicate the due date provided in the returnBy attribute to the User.

Reading Systems must not allow changes made to the clock by the User to affect the returnBy date and must not allow access to expired Content.

Reading Systems should notify the User when a Content item has expired.

4.2. Automatic Reading System Configuration

To avoid hardware players requiring manual configuration by technical staff, a standard-based, interoperable (manufacturer-independent) way of registering a Reading System to a Service has been defined that allows a Reading System to obtain the required User credentials.

Automatic Reading System Configuration is supported to allow Service Providers and Reading System manufacturers to develop and deploy Reading Systems that at the time of release are not configured to a specific Service or User.

Automatic Reading System Configuration relies on the use of the DODP Service Discovery file and on the DODP Reading System file which include the types serviceList and readingSystemList respectively.

Support for Automatic Reading System Configuration is broken down in two stages:

1. Service Discovery
   • Make available a list of DODP compliant Services.
2. Reading System Configuration
   • Provide access to User credentials data

4.2.1. Service Discovery

When a Reading System that has no credentials for any online Service attempts to connect online, it may retrieve the DODP Service Discovery file from the DAISY Consortium website and present a list of Services (as defined in the serviceList) to the User to select from. This list should be ordered logically using the Reading System’s current geolocation (if available) and the Reading System’s language.

When a Reading System is already configured with online credentials its default behavior should be to attempt to connect to that service. The Reading System may also present the User with an option to retrieve an updated list with alternative Services to connect to.

Accessing the DODP Service Discovery file

Service Discovery must not be supported by a Service Provider as the list is maintained by the DAISY Consortium and accessing this list is the responsibility of a Reading System.

This file can be accessed without the need to Authenticate – i.e. it is publically available. Its location is defined in Appendix B. Location of the DODP Service Discovery File.

Sample Service List

<serviceList> 
   <!-- Vision Australia -->
   <service id="au.org.visionaustralia.I-AccessOnlineBasic"> 
      <label xml:lang="en">
         <text>Vision Australia</text>
         <audio uri="http://example.com/name.mp3" rangeBegin="0"
          rangeEnd="65856" size="65856"/>
      </label>
      <url>https://something.visionaustralia.org/service.svc</url> 
      <website>http://www.visionaustralia.org/</website>
      <phone>611300654656</phone>
      <countries>
         <country>au</country>
      </countries> 
      <languages> 
         <language>en</language> 
      </languages> 
      <latitude>-37.8471942</latitude>
      <longitude>145.0082843</longitude> 
   </service>
   <!-- Textalk -->
   <service id="se-textalk"> 
      <label xml:lang="en">
         <text>Textalk</text>
      </label>
      <url>https://something.textalk.se/service.php</url> 
      <website>http://www.textalk.se/</website>
      <phone>4631872920</phone>
      <countries>
         <country>se</country>
      </countries> 
      <languages> 
         <language>sv</language> 
      </languages> 
      <latitude>57.6705</latitude>
      <longitude>12.0010</longitude> 
   </service> 
</serviceList>

Managing changes to the DODP Service Discovery File

The DODP Service Discovery file is centrally hosted and maintained by the DAISY Consortium. A Service Provider can apply to the DAISY Consortium to be added to the list, and once the URL and details are confirmed and the Service is verified by the DAISY Consortium, the list will be updated.

4.2.2. Reading System Configuration

Once a Reading System has been configured with a valid Service URL, a method is required to implement Reading System setup without manual steps. This has previously been a significant factor in slowing down delivery and adoption of the online Service.

Reading Systems may be delivered pre-configured to connect with a specific Service or obtain a new service URL using the Service discovery defined above.

When a Service URL is present but no credentials are available, the Reading System may try to obtain the User credentials for the Service by invoking the getUserCredentials operation.

The getUserCredentials operation retrieves the User credentials based on the readingSystemAttributes for the Reading System, which must contain a serial number.

A Reading System may call this operation before the Session Initialization Sequence when the User credentials are not known.

The Service Providers may choose to maintain a database of Reading System serial numbers that are known to belong to a User. If the serial number passed by getUserCredentials is found in the database, the Service should issue a response to the Reading System containing the encrypted User credentials.

Accessing the DODP Reading System file

The Service Provider may retrieve the encryption information for passing the information to the Reading System by comparing the Reading System’s manufacturer (and optionally model) with the list hosted by the DAISY Consortium.

The public key listed for that manufacturer should be used to encrypt the User credentials passed on to the Reading System. The User credentials are encrypted with the [RSAES-OAEP] scheme and encoded using base64 before being passed on to the Reading System.

The DODP Reading System file is maintained by the DAISY Consortium and its location is defined in Appendix C. Location of the DODP Reading System File. It contains details of compliant Reading Systems (readingSystemList) and their public keys that are used to encrypt User credentials when transmitting to the Reading System. This file can be accessed without the need to Authenticate – i.e. it is publically available.

Sample Reading System List

<readingSystemList>
   <readingSystem>
      <manufacturer>Shinano Kenshi Co.,Ltd.</manufacturer>
      <model>PTX1Pro</model>
      <publicKey>http://daisy.plextalk.com/key</publicKey>
   </readingSystem>
</readingSystemList>

Managing changes to the DODP Reading System file

The DODP Reading System file is centrally hosted and maintained by the DAISY Consortium. A Reading System manufacturer can apply to the DAISY Consortium to be added to the list, and once the details are confirmed and the Reading System is verified by the DAISY Consortium, the list will be updated.

4.3. 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.3.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.

1. The Reading System must pass the User’s login credentials and information about the Reading System’s capabilities to the Service by calling the logOn operation.
2. The Service must verify the provided parameters 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.

Upon a successful logOn operation, the Reading System is provided with all necessary information about the Service in the response to the logOn call.

If a Service returns a Fault to the logOn operation, 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 Reading System.

After completing a successful logon, a Reading System may call any Operations defined by this specification.

Note:

A Service may issue a cookie even if logOn fails.

4.3.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 behaviours 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 as long as the Session is still active. A Service may allow multiple concurrent connections with the same session ID.

4.3.3. Guest Account Access

Service Providers may allow guests to use their Services for example to listen to sample books or browse titles via Dynamic Menus. The username and password for guest accounts must be fixed to guest so that Reading Systems by default can try to access Services with the guest account.

4.4. Issuing and Transfer of Content

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

4.4.1. Content Retrieval Sequence

In order to Download or Stream a Content item from a Service, a Reading System must perform the following;

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 Content item.

getContentResources takes a Content Identifier as a parameter which is generally sourced from a contentList.

The call to getContentResources also includes an accessType which informs the Service if the content access will be either a STREAM, DOWNLOAD or AUTOMATIC_DOWNLOAD activity.

A Service should allow calls to getContentResources for the same Content item over more than one Session.

4.4.2. Monitor Download/Streaming Activity

The DAISY Online Delivery Protocol offers the operation setProgressState to assist a Service Provider in monitoring activity around Content access. This is done by setting the Progress State which allows the Service to track the state of a given Download or Streaming activity.

Valid states are: START, PAUSE, RESUME and FINISH

By interpreting these states a Service can track such metrics as the number of concurrent download / streaming activities which may be useful in managing Service quality.

Prior to accessing any of the relevant Content URIs, the Reading System uses the setProgressState(contentID, "START") operation to inform the Service that access is about to begin.

If the Reading System wishes to pause the activity, then setProgressState(contentID, "PAUSE") is executed, calling setProgressState(contentID, "RESUME") once the operation restarts.

When the activity is complete, the Reading System calls setProgressState(contentID, "FINISH").

This enables the Service to know what activity is currently occurring by Reading System and by Content item.

4.4.3. Downloading and Streaming of Content

Once the Reading System has retrieved the list of resources for a Content item, and the Progress State has been set to START, 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”.

When a Reading System attempts to stream DAISY content, it should ensure files are downloaded in a logical order to prevent excessive calls and load on Services for downloading non required files. For example the Reading System will access the NCC or NCX files, and by interrogating their contents determine the files that are needed to begin streaming. This ensures the downloading of the entire item is not required to begin streaming.

A Reading System may wish to perform Automatic Download. It may do so by providing either DOWNLOAD_ONLY, STREAM_AND_DOWNLOAD, STREAM_AND_RESTRICTED_DOWNLOAD or RESTRICTED_DOWNLOAD_ONLY as the value for the accessConfig in the readingSystemAttributes. Then any contentItem returned from the Service having its accessPermission set to either DOWNLOAD_ONLY_AUTOMATIC_ALLOWED, STREAM_AND_DOWNLOAD_AUTOMATIC_ALLOWED, STREAM_AND_RESTRICTED_DOWNLOAD_AUTOMATIC_ALLOWED or RESTRICTED_DOWNLOAD_ONLY_AUTOMATIC_ALLOWED is available for Automatic Download.

4.4.4. Publishing Updates and Instalments

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 a 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 a lastModifiedDate attribute that the Reading System may use to determine which specific resources have been updated. All these lastModifiedDate attributes must include time zone information.

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

4.4.5. Content Synchronization sequence

This section is informative

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.

1. 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.
2. The Reading System calls getContentList("bookshelf", 0, -1).
3. The Reading System returns each Content item that has passed its returnBy date by calling returnContent(itemid).
4. For each Content item in the list, the Reading System calls getContentResources(itemid), as described in Section 4.4.1, “Content Retrieval Sequence”.

At this point, the Reading System will have the contentItem and resources for every Content item available to the User. It can begin downloading (see 4.4.2 Monitor Download/Streaming Activity and 4.4.3 Downloading and Streaming of Content) 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.

Note:

When synchronizing the Content, Reading Systems should not depend on Content lists or Content status remaining the same between Sessions, since the Service or other Reading Systems belonging to the User may have changed state.

4.4.5.1 Best practice for Services returning content lists

Services are allowed to return a contentList with a different range than the range that is being requested by the Reading System in getContentlist requests. This is based on to the following two scenarios:

1. The Reading System does not specify any firstItem / lastItem range in the getContentlist request. In this case the Service should try to return the complete list if possible, but may return it in partial lists if needed for performance reasons.
2. The Reading System specifies a firstItem / lastItem range in the getContentlist request. In this case the Service should try to return exactly this range. The Service may return a smaller range (for example if there are not enough items to fill the list or for performance reasons). However, the Service may not return a larger range than what is being requested by the Reading System.

4.4.6. 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.6.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.6.2. Identifying PDTB2 Content

If a Content item is protected using PDTB2, a Service must include a meta element in its contentItem 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.6.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 to the User 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 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.

Services that do support service announcements are recommended to provide service announcements in advance, regarding planned system work that affects the availability of the Service.

4.5.1. New Announcements

A Reading System checks for new messages 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 and re-checks every X minutes according to the announcmentPullFrequency.

The Service can set the priority for each announcement from a level of HIGH, MEDIUM or LOW and specify the type of announcement as one of SYSTEM or INFORMATION to assist Reading Systems in ordering the announcements for rendering to the User. See the Announcements Priorities section for information regarding interpreting the priority attribute.

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.

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.5.3. Announcement Priorities

Each announcement has an associated priority. The following recommendations are made to assist the Reading System in interpreting the given priority.

• HIGHImmediately abort all current activities, render the announcement to the User.
• MEDIUMWait until the current activity (e.g. streaming a file) is finished and render the announcement to the User.
• LOWNext time the Reading System is idle, render the announcement to the User.

4.6. Bookmarks

• The DAISY Online Delivery protocol uses the Portable Bookmarks and Highlights grammar from [Z39-86.2005] to record Users’ bookmarks with the updateBookmarks operation. This operation can also be used by Reading Systems to record the last reading position for a Content item. Reading Systems can retrieve stored bookmarks with the getBookmarks operation. Services can also predefine bookmarks for the User to access.

Note:

• [Z39-86.2005-BOOKMARKS] constitutes the normative reference regarding the use and semantics of this type. However, audio notes are not supported in the updateBookmarks and getBookmarks operations in this version of the protocol.
• To indicate that a Service supports the retrieval of bookmarks, the Service must include an operation element with the value GET_BOOKMARKS in its serviceAttributes.
• To indicate that a Service supports the setting of bookmarks, the Service must include an operation element with the value SET_BOOKMARKS in its serviceAttributes.
• If a Service supports both the setting and retrieval of bookmarks, a Reading System may use the lastMark element of the bookmarkSet to store the User’s last reading position. The Reading System should check for a last reading position before resuming playback.
• A Service may support the retrieval of bookmarks or both the setting and retrieval of bookmarks. A Reading System should support both operations for maximum interoperability.
• The lastmark position can be obtained through the getContentList response or by invoking the getBookmarks operation. It is a recommendation that Reading Systems don’t invoke the getBookmarks operation when building a Bookshelf and instead rely on the information received from the getContentList operation.

4.7. Dynamic Menus

This section is informative

The DAISY Online Delivery Protocol offers the ability for Services to provide dynamic menus to compliant Reading Systems. Users can use these menus to perform a wide variety of activities that may be offered by the Service, such as browsing the Service’s catalog, answering surveys, or purchasing items from an online store.

These sections describe the basic principles of dynamic menu systems. Refer to [Dynamic Menus Primer] for informative usage examples.

4.7.1. Support

This section is normative

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.

4.7.2. Root Question

This section is normative

Every dynamic menu system must have a root question. The root question is the base starting menu, or main menu. It has an id of default.

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. Content Item Question

This section is normative

A contentItem (normally returned as part of a contentList) may have a multipleChoiceQuestion child element associated with it.

The multipleChoiceQuestion choices represent actions that can be performed on the given contentItem.

The service must encode the id of the contentItem into the id of the multipleChoiceQuestion in a way that allows it to be retrieved from the subsequent userResponse.

If the Service supports the ability to return to the list where the contentItem originated, (for example a search list) after completing an action, it must also encode the id of the contentList into the id of the multipleChoiceQuestion so it is able to return this as a contentListRef once the action has completed.

If a contentItem from the bookshelf contentList does not contain a multipleChoiceQuestion then the Reading System may assume that only playback and the returnContent operation are available.

If a contentItem from a non-bookshelf contentList (for example a contentListRef returned by a dynamic menu call such as search), does not contain a multipleChoiceQuestion then the Reading System may assume that only the addContentToBookshelf operation is available.

A Reading System informs a Service that it supports the use of contentItem questions by setting the child element supportsAdvancedDynamicMenus of its readingSystemAttributes to true.

If the Reading System does not support the use of contentItem questions, then the only operation that may be performed on a non-bookshelf contentList is addContentToBookshelf.

4.7.4. Navigation

This section is normative

A question is the basic unit of navigation in the dynamic menu system, as each set of menu options can be conceptually viewed as querying a User about the next step to take.

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.7, “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.6, “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.5. Question Types

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.6. 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. The contentListRef can be a search result or a return point based on a previous response given to a multipleChoiceQuestion or an inputQuestion.

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

4.8. Managing Terms of Service

This section is informative

The DAISY Online Delivery Protocol offers the ability for a Service to require agreement to Terms of Service prior to providing non-guest access to a User’s Bookshelf. The Reading System will receive a termsOfServiceNotAccepted Fault (for example calling getContentList) if Terms of Service agreement is required and agreement has not been previously accepted by the User.

Note that the Service may issue updated Terms of Service and may therefore Fault with termsOfServiceNotAccepted to re-gain agreement to the updated terms even though the User may have agreed to a previous set of Terms.

A Service that does not require acceptance of Terms of Service should return the operationNotSupported Fault for getTermsOfService or acceptTermsOfService operation.

A Reading System may also call getTermsOfService at other times if it wishes to present the Terms of Service to the User.

4.8.1. Retrieving Terms of Service content

The operation getTermsOfService is used to retrieve the Terms of Service text (and/or audio). The Reading System renders the Terms to the User and requests the User to accept them prior to accessing any Service functions including accessing the User’s Bookshelf or downloading/streaming Content.

Terms of Service are not required to provide guest access if guest access is supported.

4.8.2. Accepting Agreement to Terms of Service

If the User accepts the Terms of Service the Reading System must call the acceptTermsOfService operation to notify the Service that the Terms have been accepted. The Service records the fact the Terms of Service have been accepted by the User to ensure this Fault is not generated in future Sessions.

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.

readingSystemAttributes

Type: readingSystemAttributes

Contains the Reading System attributes.
Response
Type: serviceAttributes

Contains the attributes of the Service.

logOn must either return serviceAttributes or a Fault.

If the request parameters are not valid for logon, the unauthorized Fault should be returned.
Faults
internalServerError, invalidOperation, unauthorized, invalidParameter

5.1.2. The logOff Operation

Logs a Reading System off a Service.

Request parameters
logOff takes no parameters.
Response
Type: xs:boolean [XML Schema 2]

Specifies whether the logOff was successful.

logOff must either return true or a Fault; it must not return false.
Faults
internalServerError, operationFailed, noActiveSession

5.1.3. The getContentResources Operation

Retrieves the resources list for the specified Content item.

The Service must set and maintain the firstAccessedDate and lastAccessedDate for this contentItem based on each call to getContentResources which is made available in subsequent calls to getContentList.

The getContentResources operation must be called prior to either a Streaming or Download event beginning. For example, if a Streaming Event has begun and a new session is created for any reason, then getContentResources needs to be called again.

If a Reading System starts a new process, then getContentResources must be called again with a new valid accessType such as DOWNLOAD or STREAM.

Request parameters
contentID

Type: xs:string [XML Schema 2]

Contains the Content Identifier of the Content item for which the resources list is being requested.

accessType

Type: xs:string [XML Schema 2]

Contains one of the following values

• STREAM
• DOWNLOAD
• AUTOMATIC_DOWNLOAD

This parameter informs the Service of the type of Access to be performed to allow for the return of resources in order to optimise the retrieval process.
Response
Type: resources

Contains the resources list for the specified Content item.
Faults
internalServerError, invalidOperation, invalidParameter, noActiveSession, termsOfServiceNotAccepted

5.1.4. 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 the bookshelf reserved value defined in the id parameter below. This would return all content items valid for the given Reading System (Refer to 4. Protocol Fundamentals for information on the context in which these reserved values are used.) An example where Content items are not returned to the Reading System is where the Reading System has declared in its readingSystemAttributes that it does not support restricted downloads, yet requested a bookshelf that contains such items.

The list can also be dynamic (for example 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 value is reserved and must not be used as an identifier except as defined below.

• bookshelf

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

The list excludes Content items that 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, termsOfServiceNotAccepted

5.1.5. The returnContent Operation

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

The specified Content item is removed from a User’s Bookshelf after a successful call to this operation.

A Reading System must delete the Content item before calling returnContent. A Reading System must not call returnContent for a Content item that is not on the User’s Bookshelf.

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, noActiveSession, termsOfServiceNotAccepted

5.2. Optional Operations

This section documents additional protocol operations that a Service may support. Note that even if a Service chooses not to support a given operation, it still must expose an operation with the same signature that faults with operationNotSupported.

5.2.1. The getServiceAnnouncements Operation

Retrieves any announcements from the Service that a User has not yet read. The announcementPullFrequency is used to determine the frequency at which announcements are checked. See the Service Announcements section for more information.

Request parameters
getServiceAnnouncements takes no parameters.
Response
Type: announcements

Contains the announcements from the Service.
Faults
internalServerError, invalidOperation, operationNotSupported, noActiveSession, termsOfServiceNotAccepted

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. markAnnouncementsAsRead must either return true or a Fault; it must not return false. A Service must return true if the announcement(s) is already marked as read when the call is made.
Faults
internalServerError, invalidOperation, invalidParameter, operationFailed, operationNotSupported, noActiveSession, termsOfServiceNotAccepted

5.2.3. The updateBookmarks Operation

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

Request parameters
contentID

Type: xs:string [XML Schema 2]

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

action

Type: xs:string [XML Schema 2]

The action to be performed.

The following values are permitted as valid actions.

• REPLACE_ALL
  The Service entirely replaces the User’s bookmarks for this Content item with this new bookmarkObject.
• ADD
  The Service adds the elements in this bookmarkObject to the User’s bookmarks for this Content item. Any duplicate bookmarks are updated.
• REMOVE
  The Service removes the elements in this bookmarkObject from the User’s bookmarks for this Content item.

bookmarkObject

Type: bookmarkObject

Contains the bookmarks to store.
Response
Type: xs:boolean [XML Schema 2]

Specifies whether the Service successfully performed the action.
Faults
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession, termsOfServiceNotAccepted

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

action

Type: xs:string [XML Schema 2]

The action to be performed.

The following values are permitted as valid actions.

• LASTMARK
  Retrieves the lastmark only.
• HILITE
  Retrieves all hilites only.
• BOOKMARK
  Retrieves all bookmarks only.
• ALL
  Retrieves all bookmarks including those of type lastmark, hilite and bookmark.

Response
Type: bookmarkObject

Contains the selected bookmarks for the Content item.
Faults
internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession, termsOfServiceNotAccepted

5.2.5. The addContentToBookshelf Operation

Requests a Service to add a specified Content item to the User’s Bookshelf.

Request parameters
contentID

Type: xs:string [XML Schema 2]

The Content Identifier of the Content item being requested.
Response
Type: xs:boolean [XML Schema 2]

Specifies whether the Content item was added successfully.

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

A Service must return true if the Content item is already on the User’s Bookshelf when the call is made.

If the content item cannot be added to the User’s Bookshelf then the OperationFailed Fault should be used to allow a label to be passed back containing details of the reason – for example, the daily loan limit was exceeded.
Faults
internalServerError, invalidOperation, invalidParameter, noActiveSession, operationFailed, termsOfServiceNotAccepted

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

5.2.7. The getUserCredentials Operation

Retrieves the User credentials for a given Reading System based on the manufacturer and serial number supplied in the readingSystemAttributes.

Request parameters
readingSystemAttributes

Type: readingSystemAttributes

Contains the Reading System attributes.
Response
credentials

Type: credentials

Contains the User credentials.
Faults
internalServerError, invalidOperation, invalidParameter, operationNotSupported

5.2.7.1. getUserCredentials parameter / response examples

Example: 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>
    <supportsAdvancedDynamicMenus>true</supportsAdvancedDynamicMenus>
    <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>

Example: credentials

<credentials xmlns="http://www.daisy.org/ns/daisy-online/" 
  encryptionScheme="RSAES-OAEP">
  <username>user</username>
  <password>pass</password>
</credentials>

5.2.8. 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, termsOfServiceNotAccepted

5.2.9. The getTermsOfService Operation

Requests the Terms of Service from a Service. See Managing Terms of Service for a description of how this operation is used.

Request parameters
getTermsOfService takes no parameters.
Response
Type: label

Contains the terms of service for the Service.
Faults
internalServerError, invalidOperation, noActiveSession, operationNotSupported

5.2.10. The acceptTermsOfService Operation

Marks the terms of service as accepted. See Managing Terms of Service for a description of how this operation is used.

Request parameters
acceptTermsOfService takes no parameters.
Response
Type: xs:boolean [XML Schema 2]

Specifies whether the Service successfully marked the terms of service as accepted.
Faults
internalServerError, invalidOperation, noActiveSession, operationNotSupported

5.2.11. The setProgressState Operation

Sets the Content access state for a given Content item. For example if a Reading System is about to start to download or stream, its state would be set to START and when completed would be set to FINISH.

If a noActiveSession Fault is returned, the Reading System must re-activate the Session with the Service to pass on the information.

Request parameters
contentID

Type: xs:string [XML Schema 2]

Contains the Content Identifier of the Content item for which the state is being set.

state

Type: xs:string [XML Schema 2]

The following values are permitted as valid states.

• START
  A download or streaming is beginning which would result in resources returned by getContentResources being accessed.
• PAUSE
  A download or streaming is being paused. This is valid from a START state.
• RESUME
  A download or streaming is being resumed. This is valid from a PAUSE state.
• FINISH
  A download or streaming is finished. This is valid from either a START, PAUSE or RESUME state.

Response
Type: xs:boolean [XML Schema 2]

Specifies whether the Service successfully set the state.
Faults
internalServerError, invalidOperation, noActiveSession, termsOfServiceNotAccepted

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:

1. internalServerError
2. noActiveSession
3. operationNotSupported
4. invalidOperation
5. invalidParameter
6. termsOfServiceNotAccepted
7. operationFailed
8. unauthorized

The detail element may also optionally contain a label element. If it exists, this label represents a human readable (if audio is included in the label, and is playable) error message with any information that the Service wishes to communicate to the User, in order to explain the error. A Reading System receiving this label should present it to the User, if it has the capability of doing so.

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 remaining available 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.

5.3.6. The termsOfServiceNotAccepted Fault

Condition: the Terms of Service have not been accepted by the User.

This Fault is issued when a Reading System calls the getContentList operation before the Terms of Service have been accepted.

5.3.7. The operationFailed Fault

Condition: the operation was not successful.

This Fault is issued when a Reading System calls an operation and the outcome of the operation was not successful.

5.3.8. The unauthorized Fault

Condition: the User is not authorized to access this Service.

This Fault is issued when a Reading System calls a logOn operation and the User credentials fail to validate.

6. Type Reference

This section is normative

The following sections describe the elements defined in the [XML Schema 1] schema do-types-20.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-20.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: announcements

<announcements xmlns="http://www.daisy.org/ns/daisy-online/">
  <announcement id="downtime" priority="HIGH" type="SYSTEM">
    <label xml:lang="en">
      <text>The Service will not be available for 30 minutes from 1:30pm today, 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="MEDIUM" 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 bookmarkObject Type

Used By

updateBookmarks (parameter)
getBookmarks (response)

Content Model

( bookmarkSet )

Attributes

lastModifiedDate
The last modified time of the bookmark object. If this attribute is present, it must include time zone information.

Use: optional

Data type: xs:dateTime

6.3. The bookmarkSet Type

Used By

Content Model

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

6.4. 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 the reserved value bookshelf 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.4.1. contentList Examples

Example: A complete contentList with audio labels

This example shows a complete contentList (the firstItem and lastItem attributes are not present in the root element). The second book is [PDTB2] protected (see Section 4.4.6, “Rights management”) and has a cover. Both books are available for streaming but not downloading.

<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" category="BOOK" 
    lastModifiedDate="2015-02-25T09:20:10Z">
    <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>
    <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>
      <dc:description>Harry ignores warnings not to return to Hogwarts, only to find the school plagued by a series of mysterious attacks and a strange voice haunting him.</dc:description>
      <narrator>Mary Svensson</narrator>
      <size>8119213</size>
    </metadata>
    <accessPermission>STREAM_ONLY</accessPermission >
  </contentItem>
  <contentItem id="com-example-002" category="BOOK" 
    lastModifiedDate="2015-02-26T13:20:10+06:00">
    <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>
    <sample id="hp_cos-sample"/>
    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
      <dc:title>Harry Potter and the Goblet of Fire</dc:title>
      <dc:identifier>com-example-hp_cos</dc:identifier>
      <dc:format>Daisy 2.02</dc:format>
      <dc:language>en-GB</dc:language>
      <dc:description>Harry ignores warnings not to return to Hogwarts, only to find the school plagued by a series of mysterious attacks and a strange voice haunting him.</dc:description>
      <narrator>Mary Svensson</narrator>
      <size>8119213</size>
      <meta name="pdtb2:specVersion" content="2005-1" />    
      <meta name="cover" content="http://example.com/image.png" />
    </metadata>
    <accessPermission>STREAM_ONLY</accessPermission >
    <multipleChoiceQuestion id="contentId_cl123">
      <label>
        <text>What would you like to do now?</text>
      </label>
      <choices>
        <choice id="loanItem">
          <label>
            <text>Loan Book</text>
          </label>
        </choice>
        <choice id="addToWishList">
          <label>
            <text>Add to Wish List</text>
          </label>
        </choice>
      </choices>
    </multipleChoiceQuestion>
  </contentItem>
</contentList>

Example: A partial contentList

This example shows a partial contentList (firstItem and lastItem attributes specify which of the items are included in this segment). The second book is [PDTB2] protected (see Section 4.4.6, “Rights management”) and has a cover. Both books are available for streaming but not downloading, although it is available for restricted download.

<contentList xmlns="http://www.daisy.org/ns/daisy-online/" 
  id="cl125" firstItem="0" lastItem="1" totalItems="25"
  lastModifiedDate="2015-02-25T09:20:10Z">
  <label xml:lang="en">
    <text>Please select from these publications.</text>
  </label>
  <contentItem id="com-example-001" category="BOOK">
    <label xml:lang="en">
      <text>Harry Potter and the Chamber of Secrets</text>
    </label>
    <sample id="hp_cos-sample"/>
    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
      <dc:title>Harry ignores warnings not to return to Hogwarts, only to find the school plagued by a series of mysterious attacks and a strange voice haunting him.</dc:title>
      <dc:identifier>com-example-hp_cos</dc:identifier>
      <dc:format>Daisy 2.02</dc:format>
      <dc:language>en-GB</dc:language>
      <dc:description>This book </dc:description>
      <narrator>Mary Svensson</narrator>
      <size>8119213</size>
    </metadata>
    <accessPermission>STREAM_ONLY</accessPermission >
  </contentItem>
  <contentItem id="com-example-002" category="BOOK" 
    lastModifiedDate="2015-02-26T13:20:10+06:00">
    <label xml:lang="en">
      <text>Harry Potter and the Goblet of Fire</text>
    </label>
    <sample id="hp_cos-sample"/>
    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
      <dc:title>Harry ignores warnings not to return to Hogwarts, only to find the school plagued by a series of mysterious attacks and a strange voice haunting him.</dc:title>
      <dc:identifier>com-example-hp_cos</dc:identifier>
      <dc:format>Daisy 2.02</dc:format>
      <dc:language>en-GB</dc:language>
      <dc:description>This book </dc:description>
      <narrator>Mary Svensson</narrator>
      <size>8119213</size>
      <meta name="pdtb2:specVersion" content="2005-1" />    
      <meta name="cover" content="http://example.com/image.png" />
    </metadata>
    <accessPermission>STREAM_ONLY</accessPermission >
  </contentItem>
</contentList>

6.5. The credentials Type

The User credentials used to support automatic Reading System configuration.

Used By

getUserCredentials (response)

Content Model

( username, password )

Attributes

encryptionScheme
The identifier of the encryption scheme used to encrypt the username and password.

This attribute must be set to RSAES-OAEP.

Use: required

Data type: xs:NMTOKEN

6.5.1. credentials Examples

Example: credentials

<credentials xmlns="http://www.daisy.org/ns/daisy-online/" 
  encryptionScheme="RSAES-OAEP">
  <username>user</username>
  <password>pass</password>
</credentials>

6.6. The KeyExchange Type

Used By

getKeyExchangeObject (response)

Content Model

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

6.7. The keyRing Type

A list of key names.

Used By

Content Model

( item* )

6.8. The questions Type

A sequence of questions.

The questions element must contain either:

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

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

If the questions element contains a contentListRef child element, it is an endpoint to the sequence of questions that comprise a dynamic menu if neither of the contentItems on the contentList being referenced has a multipleChoiceQuestion element.

A label together with contentListRef, multipleChoiceQuestions or inputQuestions may for example describe the outcome of a previous dynamic menu action.

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? ) | label )

6.9. The read Type

A list of announcement identifiers.

Used By

markAnnouncementsAsRead (parameter)

Content Model

( item* )

6.10. The readingSystemAttributes Type

Specifies Reading System properties.

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

Used By

logon (parameter)

Content Model

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

This element is extensible.

6.10.1. readingSystemAttributes Examples

Example: readingSystemAttributes for a basic Reading System

This example shows readingSystemAttributes for a basic 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>
    <accessConfig>STREAM_ONLY</accessConfig>
    <supportsMultipleSelections>false</supportsMultipleSelections>
    <supportsAdvancedDynamicMenus>false</supportsAdvancedDynamicMenus>
    <preferredUILanguage>en</preferredUILanguage>
    <bandwidth>8000000</bandwidth>
    <supportedContentFormats>
      <contentFormat>ANSI/NISO Z39.86-2005</contentFormat>
      <contentFormat>application/zip</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: 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>
    <accessConfig>STREAM_ONLY</accessConfig >
    <supportsMultipleSelections>true</supportsMultipleSelections>
    <supportsAdvancedDynamicMenus>true</supportsAdvancedDynamicMenus>
    <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>
    <requiresAudioLabels>false</requiresAudioLabels>
  </config>
</readingSystemAttributes>

6.11. The readingSystemList Type

The list of DAISY Consortium compliant Reading Systems available to a given Service.

Used By

Used as source data by a Service to support automatic configuration.

Content Model

( readingSystem* )

6.11.1. readingSystemList Examples

Example: readingSystemList

<readingSystemList xmlns="http://www.daisy.org/ns/daisy-online/"> 
   <readingSystem>
      <manufacturer>Shinano Kenshi Co.,Ltd.</manufacturer>
      <model>PTX1Pro</model>
      <publicKey>http://daisy.plextalk.com/key</publicKey>
   </readingSystem>
</readingSystemList>

6.12. The resources Type

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

Used By

getContentResources (response)

Content Model

( resource+, package* )

Attributes

lastModifiedDate
The last modified time of the Content item.

This is the most recent of all lastModifiedDates for the collection of resources and packages that make up this Content item. This attribute must include time zone information.

Use: required

Data type: xs:dateTime

6.12.1. resources Examples

Example: 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/" 
  lastModifiedDate="2015-02-26T13:20:10+06:00" >
  <resource mimeType="text/xml" size="123456" 
    uri="https://example.com/content/get.php?a123891"
    localURI="package.opf"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="application/x-dtbncx+xml" size="123456" 
    uri="https://example.com/content/get.php?a123892"
    localURI="nav.ncx"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="application/smil" size="567890" 
    uri="https://example.com/content/get.php?a123893"
    localURI="chapter_1.smil"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="audio/mpeg" size="123456789" 
    uri="https://example.com/content/get.php?a123894"
    localURI="chapter_1.mp3" 
    lastModifiedDate="2015-02-26T13:20:10+06:00" />
  <resource mimeType="image/jpeg" size="23456" 
    uri="https://example.com/content/get.php?a123895" 
    localURI="./images/sun001.jpg"
    lastModifiedDate="2015-02-25T09:20:10Z" /> 
</resources>

Example: A resources instance using script URIs that uses packages

This example shows a resources instance where a few resources can also be downloaded as part of a package.

<resources xmlns="http://www.daisy.org/ns/daisy-online/" 
  lastModifiedDate="2015-02-26T13:20:10+06:00" >
  <resource mimeType="text/xml" size="123456"
    uri="https://example.com/content/get.php?a123891"
    localURI="package.opf" 
    lastModifiedDate="2015-02-26T13:20:10+06:00" />
  <resource mimeType="application/x-dtbncx+xml" size="123456"
    uri="https://example.com/content/get.php?a123892"
    localURI="nav.ncx"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="application/smil" size="567890"
    uri="https://example.com/content/get.php?a123893"
    localURI="chapter_1.smil"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="audio/mpeg" size="123456789"
    uri="https://example.com/content/get.php?a123894"
    localURI="chapter_1.mp3"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <package mimeType="application/zip" size="987" 
    uri="https://example.com/content/get.php?123"
    lastModifiedDate="2015-02-26T13:20:10+06:00">
    <resourceRef localURI="package.opf"/>
    <resourceRef localURI="nav.ncx"/>
    <resourceRef localURI="chapter_1.smil"/>
  </package>
</resources>

Example: A resources instance using script URIs containing a single package

This example shows a resources instance where the Service presents all resources packaged to a single zip resource.

<resources xmlns="http://www.daisy.org/ns/daisy-online/" 
  lastModifiedDate="2015-02-26T13:20:10+06:00" >
  <resource mimeType="text/xml" size="123456"
    uri="https://example.com/content/get.php?a123891"
    localURI="package.opf"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="application/x-dtbncx+xml" size="123456"
    uri="https://example.com/content/get.php?a123892"
    localURI="nav.ncx"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <resource mimeType="application/smil" size="567890"
    uri="https://example.com/content/get.php?a123893"
    localURI="chapter_1.smil" 
    lastModifiedDate="2015-02-26T13:20:10+06:00" />
  <resource mimeType="audio/mpeg" size="123456789"
    uri="https://example.com/content/get.php?a123894"
    localURI="chapter_1.mp3"
    lastModifiedDate="2015-02-25T09:20:10Z" />
  <package mimeType="application/zip" size="987" 
    uri="https://example.com/content/get.php?123"
    lastModifiedDate="2015-02-26T13:20:10+06:00">
    <resourceRef localURI="package.opf"/>
    <resourceRef localURI="nav.ncx"/>
    <resourceRef localURI="chapter_1.smil"/>
    <resourceRef localURI="chapter_1.mp3"/>
  </package>
</resources>

6.13. The serviceAttributes Type

Properties of the Service.

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

Used By

logOn (response)

Content Model

( serviceProvider?, service?, supportsServerSideBack, supportsSearch, supportedUplinkAudioCodecs, supportsAudioLabels, supportedOptionalOperations, accessConfig, announcementsPullFrequency, progressStateOperationAllowed )

Example: serviceAttributes for a minimal library Service

This example shows the serviceAttributes for a Service that only supports streaming.

<serviceAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <serviceProvider id="uk.com.example" />
  <service id="uk.com.example.libraryServiceBasic" />
  <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>
  <accessConfig>STREAM_ONLY</accessConfig>
  <announcementsPullFrequency>15</announcementsPullFrequency>
  <progressStateOperationAllowed>false</progressStateOperationAllowed>
</serviceAttributes>

Example: serviceAttributes for a fuller Service

This example shows the serviceAttributes for a Service that provides some or all of its Content protected using [PDTB2]. This Service also supports both download and streaming (including restricted downloads).

<serviceAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <serviceProvider id="gy-zenith" />
  <service id="gy-zenith-libraryServiceDeluxe" />
  <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>
  <accessConfig>STREAM_AND_RESTRICTED_DOWNLOAD</accessConfig>
  <announcementsPullFrequency>120</announcementsPullFrequency>
  <progressStateOperationAllowed>true</progressStateOperationAllowed>
</serviceAttributes>

6.14. The serviceList Type

The list of Services available to a given Reading System sourced from the DAISY Consortium.

Used By

Used as source data by a Reading System to support automatic configuration.

Content Model

( service* )

6.14.1. serviceList Examples

Example: serviceList

<serviceList xmlns="http://www.daisy.org/ns/daisy-online/"> 
   <!-- Vision Australia -->
   <service id="au.org.visionaustralia.I-AccessOnlineBasic"> 
      <label xml:lang="en">
         <text>Vision Australia</text>
         <audio uri="http://example.com/name.mp3"
          rangeBegin="0" rangeEnd="65856" size="65856"/>
      </label>
      <url>https://something.visionaustralia.org/service.svc</url> 
      <website>http://www.visionaustralia.org/</website>
      <phone>611300654656</phone>
      <countries>
         <country>au</country>
      </countries>
      <languages> 
         <language>en</language> 
      </languages> 
      <latitude>-37.8471942</latitude>
      <longitude>145.0082843</longitude> 
   </service> 
   <!-- CNIB -->
   <service id="ca-cnib">
      <label xml:lang="en">
         <text>CNIB</text>
      </label>
      <url>https://smething.cniblibrary.com/DOService/DaisyOService</url> 
      <website>http://www.cniblibrary.com/</website>
      <phone>611300654656</phone>
      <countries>
         <country>ca</country> 
      <countries>
      <languages> 
         <language>en</language> 
         <language>fr</language>
      </languages> 
      <latitude>43.717457</latitude> 
      <longitude>-79.3779645,17</longitude> 
   </service> 
</serviceList>

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

7. Element Reference

7.1. accessConfig

This element allows the Reading System and Service to exchange details of access capability. When used in the config element in the readingSystemAttributes it declares the methods supported by the Reading System. When used in serviceAttributes it declares the methods supported by the Service.

Properties

Allowed values:

• STREAM_ONLY

The Reading System or Service only supports the streaming of Content.

• DOWNLOAD_ONLY

The Reading System or Service only supports the downloading of unrestricted Content.

• STREAM_AND_DOWNLOAD

The Reading System or Service supports both the streaming of Content and downloading of unrestricted Content.

• STREAM_AND_RESTRICTED_DOWNLOAD

The Reading System or Service supports the streaming of Content and downloading of both unrestricted and restricted Content.

• RESTRICTED_DOWNLOAD_ONLY

The Reading System or Service supports both the downloading of unrestricted and restricted Content.
Parent(s): serviceAttributes, config

7.2. accessPermission

This element specifies the allowed operations for a given contentItem.

Properties

Allowed values:

• STREAM_ONLY

This content can ONLY be streamed.

• DOWNLOAD_ONLY

This content can ONLY be downloaded.

• STREAM_AND_DOWNLOAD

This content can be streamed or downloaded.

• STREAM_AND_RESTRICTED_DOWNLOAD

This content can be streamed or downloaded as Restricted Content.

• RESTRICTED_DOWNLOAD_ONLY

This content can ONLY be downloaded as Restricted Content.

• DOWNLOAD_ONLY_AUTOMATIC_ALLOWED

This content can ONLY be downloaded. Automatic Download is allowed.

• STREAM_AND_DOWNLOAD_AUTOMATIC_ALLOWED

This content can be streamed or downloaded. Automatic Download is allowed.

• STREAM_AND_RESTRICTED_DOWNLOAD_AUTOMATIC_ALLOWED

This content can be streamed or downloaded as Restricted Content. Automatic Download is allowed.

• RESTRICTED_DOWNLOAD_ONLY_AUTOMATIC_ALLOWED

This content can ONLY be downloaded as Restricted Content. Automatic Download is allowed.
Parent(s): contentItem

7.3. additionalTransferProtocols

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

Properties

Content model: ( protocol+ )

Parent(s): config

7.4. 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:

• INFORMATION
  Service news, general ‘non actionable’ information.
• SYSTEM
  Actionable information for the User, for example account, service outages.

Default Value: INFORMATION
priority
The priority of this announcement. See the Announcements Priorities section for information regarding how to interpret the priority.

Use: required

Enumeration:

• HIGH
• MEDIUM
• LOW

Default Value: LOW

7.5. announcementsPullFrequency

The pulling frequency (in minutes) of announcements, i.e. the number of minutes between calls from the Reading System to check for announcements.

A value of 0 indicates that the Reading System should only check for announcements at logon time.

Properties

Data type: xs:int

Parent(s): serviceAttributes

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

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

7.8. categoryLabel

The human readable, localized, label for the category of a Content item.

Properties

Content model: ( label )

Parent(s): contentItem

7.9. choice

Properties

Content model: ( label )

Parent(s): choices

Attributes

id
Use: required

Data type: xs:NMTOKEN

7.10. choices

Properties

Content model: ( choice+ )

Parent(s): multipleChoiceQuestion

7.11. codec

The codec’s [MIME] type.

Properties

Data type: xs:string

Parent(s): supportedUplinkAudioCodecs

7.12. config

Properties

Content model: ( accessConfig, supportsMultipleSelections, supportsAdvancedDynamicMenus, preferredUILanguage, bandwidth?, supportedContentFormats, supportedContentProtectionFormats, keyRing?, supportedMimeTypes, supportedInputTypes, requiresAudioLabels, additionalTransferProtocols?)

Parent(s): readingSystemAttributes

7.13. contentFormat

The content of this element follows the convention of the [Dublin Core] Format element.

Properties

Data type: xs:string

Parent(s): supportedContentFormats

7.14. contentItem

A single Content item.

Properties

Content model: ( label, sample?, metadata, categoryLabel?, subCategoryLabel?, accessPermission, lastmark?, multipleChoiceQuestion?)

Parent(s): contentList

Attributes

id
The Content Identifier of this Content item.

Use: required

Data type: xs:string
firstAccessedDate
A timestamp representing when a contentItem was first accessed. If this attribute is present, it must include time zone information.

If a Content item has been accessed, this attribute must be supplied. For example it can only be omitted if the content item has not been accessed and therefore has a null value.

Use: optional

Data type: xs:dateTime
lastAccessedDate
A timestamp representing when a contentItem was last accessed. If this attribute is present, it must include time zone information. If a Content item has been accessed, this attribute must be supplied. For example it can only be omitted if the content item has not been accessed and therefore has a null value.

Use: optional

Data type: xs:dateTime
lastModifiedDate
The last modified time of the Content item.

This is the most recent of all lastModifiedDates for the collection of resources and packages that make up this Content item. This attribute must include time zone information.

Use: required

Data type: xs:dateTime
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
subCategory
The publication sub category of the Content item.

Reading Systems may use the value provided here to categorize or sort Content items. Any value is allowed. This value is to be machine-readable by the Reading Systems, thus should not be localized.

Use: optional

Data type: xs:string
returnBy
Specifies the time when the Service Provider requires this Content item to be returned.

This attribute must include time zone information. This attribute may change value while the Content item is on a User’s Bookshelf, for example another process (such as Service Provider staff member) may change this date to extend the loan of this item.

Use: optional

Data type: xs:dateTime
hasBookmarks
Specifies whether the Content item has bookmarks or hilites.

Use: required

Data type: xs:boolean

7.15. 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, if neither of the contentItems on the contentList being referenced has a questions element.

Properties

Data type: xs:NMTOKEN

Parent(s): questions

7.16. country

The country where a given Service Provider resides.

Properties

Data type: xs:string

Parent(s): countries

7.17. countries

A set of countries supported by a given Service Provider.

Properties

Content model: ( country* )

Parent(s): service

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

7.19. email

A valid email address that can be used by the Reading System or User to contact the Service Provider.

Properties

Data type: xs:string

Parent(s): service

7.20. input

Properties

Content model: empty element

Parent(s): inputTypes, supportedInputTypes

Attributes

type
Use: required

Enumeration:

• TEXT_NUMERIC
  The Reading System supports numeric input. The Service allows numeric-only responses to the question.

• TEXT_ALPHANUMERIC
  The Reading System supports text and numeric input. The Service allows text and numeric responses to the question.

• AUDIO
  The Reading System supports audio input. The Service allows audio responses to the question.

7.21. 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
defaultValue
A valid default value that enables the input field to be rendered by the Reading System with an existing value.

Use: optional

Data type: xs:string

7.22. inputTypes

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

Properties

Content model: ( input+ )

Parent(s): inputQuestion

7.23. item

Properties

Data type: xs:string

Parent(s): keyRing, read

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

Used By

getTermsOfService (response)

Properties

Content model: ( text, audio? )

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

Attributes

xml:lang
The language of the label.

Use: required
dir
The direction of the text.

Use: optional

Enumeration:

• LTR
  Left-to-right.

• RTL
  Right-to-left.

7.25. language

A 2 digit language code representing a language supported by a given Service Provider as defined by ISO 639-1.

Properties

Data type: xs:string

Parent(s): languages

7.26. languages

A set of languages supported by a given Service Provider.

Properties

Content model: ( language* )

Parent(s): service

7.27. latitude

A valid latitude that goes to describing the location of the Service Provider.

Properties

Data type: xs:string

Parent(s): service

7.28. longitude

A valid longitude that goes to describing the location of the Service Provider.

Properties

Data type: xs:string

Parent(s): service

7.29. manufacturer

The manufacturer of the Reading System.

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

7.30. meta

An arbitrary metadata element. Allows custom metadata fields from schemas other than Dublin Core.

Properties

Content model: empty element

Parent(s): metadata

Attributes

name
Use: required

Data type: xs:string
content
Use: required

Data type: xs:string

7.31. 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]

A meta element with cover in the name attribute contains the URL for the cover image of the Content item in the content attribute (see contentList Examples).

dc:description can be used for the Content item’s Synopsis.

Properties

Content model: ( dc:title, dc:identifier, dc:publisher?, dc:format, (dtb:multimediaType | ncc:multimediaType)?, 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): contentItem

7.32. mimeType

Properties

Content model: empty element

Parent(s): supportedMimeTypes

Attributes

type
A [MIME] type.

Use: required

Data type: xs:string
xml:lang
Use: optional

7.33. model

The model name or designation of the Reading System.

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

7.34. multipleChoiceQuestion

Properties

Content model: ( label, choices )

Parent(s): contentItem, 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

7.35. narrator

In the case of audio Content, the name of the person reading the Content .

Properties

Data type: xs:string

Parent(s): metadata

7.36. operation

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

Properties

Allowed values:

• SET_BOOKMARKS

This Service supports the updateBookmarks 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

7.37. package

Properties

Content model: ( resourceRef )

Parent(s): resources

Attributes

uri
The URI of a package in which the resource can be found. The value of this attribute refers to a URI, which the Reading System may choose to download instead of the uri attribute of the individual resources. The Service thus has the possibility to group one or more resources into one package, such as all text resources of an audio book.

Use: required

Data type: xs:anyURI
mimeType
The [MIME] type of the package.

The value of this attribute indicates to the Reading System how to unpack the package.

Use: required

Data type: xs:string
size
The size of the package in bytes.

Use: required

Data type: xs:long
lastModifiedDate
The last modified time of the package. This attribute must include time zone information.

Use: required

Data type: xs:dateTime

7.38. password

A valid password, encrypted with the [RSAES-OAEP] scheme and encoded using base64, for the given Service that can be used with its corresponding username for authentication against a compliant Service Provider.

Properties

Data type: xs:string

Parent(s): credentials

7.39. phone

A valid phone number that can be used by a User to contact the Service Provider.

Properties

Data type: xs:string

Parent(s): service

7.40. preferredUILanguage

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

Properties

Data type: xs:language

Parent(s): config

7.41. progressStateOperationAllowed

Specifies whether Reading Systems shall call the setProgressState operation.

Properties

Data type: xs:boolean

Parent(s): serviceAttributes

7.42. protectionFormat

Properties

Allowed values:

• PDTB2

This Reading System supports DAISY Protected Digital Talking Book 2.
Parent(s): supportedContentProtectionFormats

7.43. protocol

The identifier of a transfer protocol. Identifiers are as given in the protocol’s specification.

Properties

Data type: xs:string

Parent(s): additionalTransferProtocols

7.44. publicKey

The url to a valid public key for the given Reading System that can be used to encrypt data from the Service Provider.

Properties

Data type: xs:string

Parent(s): readingSystem

7.45. readingSystem

Contains the definition of a Reading System compliant with the DAISY Online Delivery protocol.

Properties

Content model: ( manufacturer, model?, publicKey)

Parent(s): readingSystemList

7.46. requiresAudioLabels

Specifies whether the Reading System requires audio labels for messages provided by the Service (for example whether the audio child element of label is required).

Refer to the supportsAudioLabels element in serviceAttributes for the Service’s declaration of support for audio in labels.

In the case where the Reading System requires audio labels and the Service does not support audio labels, the Reading System must decide whether to continue initializing the session. If a session is established in this scenario, then the Service is not required to include the audio element in each label it provides.

Properties

Data type: xs:boolean

Parent(s): config

7.47. resource

Properties

Content model: empty element

Parent(s): resources

Attributes

uri
The URI of the resource.

Use: required

Data type: xs:anyURI
mimeType
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. This attribute must include time zone information.

Use: required

Data type: xs:dateTime
serverSideHash
A server side hash of the resource.

The Service may freely choose which algorithm to use for calculating the serverSideHash. It is required for the serverSideHash to remain constant while the resource is unchanged and the same algorithm must be used for calculating the serverSideHash for all resources.

By examining the localURI, the lastModifiedDate and the serverSideHash attributes of resources combined, Reading Systems can identify duplicate resources for a Content item, provided by multiple calls to getContentResources, with various accessType parameters provided.

Use: optional

Data type: xs:string

7.48. resourceRef

A reference to a resource.

Properties

Content model: empty element

Parent(s): package

Attributes

localURI
The local relative path of the resource.

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

It represents a reference to the resource contained within the package and should have the same value as in the referenced resource.

Use: required

Data type: xs:anyURI

7.49. sample

A sample of the Content item that the User may retrieve without the Content item being added to their Bookshelf.

Properties

Content model: empty element

Parent(s): contentItem

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.

Use: required

Data type: xs:string

7.50. serialNumber

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

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

7.51. service

Contains the definition of a Service compliant with the DAISY Online Delivery protocol.

Properties

Content model: (label, url, website?, phone?, email?, countries, languages, latitude, longitude)

Parent(s): serviceList, serviceAttributes

Attributes

id
The identifier of the Service.

This specification does not require a specific scheme to be used for this identifier. The identifier should not change while the Service remains active, and it should be universally unique.

A recommended expression form is a hyphen-separated string consisting of a country code from [ISO 3166], followed by an agency code unique within its country. For example, us-afb.

Use: required

Data type: xs:NMTOKEN

7.52. serviceProvider

The identity of the Service Provider.

Properties

Content model: ( label? )

Parent(s): serviceAttributes

Attributes

id
The identifier of the Service Provider.

This specification does not require a specific scheme to be used for this identifier. The identifier should not change while the Service provider remains active, and it should be universally unique.

A recommended expression form is a hyphen-separated string consisting of a country code from [ISO 3166], followed by an agency code unique within its country. For example, us-afb.

Use: required

Data type: xs:NMTOKEN

7.53. size

The total size of the resources making up the Content item, in bytes.

Properties

Data type: xs:long

Parent(s): metadata

7.54. subCategoryLabel

The human readable, localized, label for the subCategory of a Content item.

Properties

Content model: ( label )

Parent(s): contentItem

7.55. supportedContentFormats

Specifies which Content formats the Reading System supports. A Service may use this information to choose which formats to offer to the Reading System.

This document does not specify the behaviour of the Service if this list is empty.

If a Reading System supports resource packages, the supportedContentFormats element needs to contain a contentFormat with the value application/zip among the other supportedContentFormats. The Service may then present the package element for resources. The Service may also choose to present one single zip resource, or a zip resource that contains only part of the resource set. An example of this includes sending the smaller files (non-audio) of a DAISY Audio book in a zip package, while the larger audio files are sent as stand-alone resources. This may enable simpler streaming support, supplying the control files in the zip package but still allowing the audio files to be accessed only as needed.

Properties

Content model: ( contentFormat* )

Parent(s): config

7.56. supportedContentProtectionFormats

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

Properties

Content model: ( protectionFormat* )

Parent(s): config

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

7.58. supportedMimeTypes

Specifies which [MIME] types the Reading System supports.

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

A Service may use this information to choose which resource types to offer to the Reading System as labels and Content. Content types for which support is implied by the Content formats in supportedContentFormats need not be included here.

This specification does not specify the behavior of the Service if both this and the supportedContentFormats lists are empty.

Properties

Content model: ( mimeType* )

Parent(s): config

7.59. supportedOptionalOperations

Specifies which (if any) of the optional operations are supported by the Service.

Properties

Content model: ( operation* )

Parent(s): serviceAttributes

7.60. supportedUplinkAudioCodecs

A list of the audio codecs (if any) supported in userResponses in addition to [RIFF WAVE].

Properties

Content model: ( codec* )

Parent(s): serviceAttributes

7.61. supportsAdvancedDynamicMenus

Specifies whether the Reading System supports dynamic menus attached to contentItems.

If this element is set to false, the Service must not present dynamic menus attached to contentItems to the Reading System.

Properties

Data type: xs:boolean

Parent(s): config

7.62. supportsAudioLabels

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, then the Service must include the audio element in each label it provides.

Properties

Data type: xs:boolean

Parent(s): serviceAttributes

7.63. supportsMultipleSelections

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

If this element is set to false, the Service must not present a multipleChoiceQuestion with its allowMultipleSelections attribute set to true to the Reading System.

Properties

Data type: xs:boolean

Parent(s): config

7.64. supportsSearch

Specifies whether getQuestions with the reserved parameter search is supported by the Service.

Properties

Data type: xs:boolean

Parent(s): serviceAttributes

7.65. supportsServerSideBack

Specifies whether getQuestions with the reserved parameter back is supported by the Service.

Properties

Data type: xs:boolean

Parent(s): serviceAttributes

7.66. text

The text component of the label.

Properties

Data type: xs:string

Parent(s): label

7.67. url

The URL of the Service Provider’s DAISY Online service.

Properties

Data type: xs:string

Parent(s): service

7.68. username

A valid username, encrypted with the [RSAES-OAEP] scheme and encoded using base64, for the given Service that can be used for subsequent Reading System authentication against a compliant Service Provider.

Properties

Data type: xs:string

Parent(s): credentials

7.69. userResponse

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

• default
  The 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.

• search
  The 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.

• back
  The 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

7.70. version

The version of the Reading System.

Properties

Data type: xs:string

Parent(s): readingSystemAttributes

7.71. website

A valid website address that points to the Service Provider’s web site.

Properties

Data type: xs:string

Parent(s): service

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.

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

[RSAES-OAEP] Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1. J. Jonsson and B. Kaliski, February 2003.

Informative References

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

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

Appendix A. WSDL Abstract Definition

This appendix is normative

The [WSDL 1.1] entities defined in the accompanying do-wsdl-20.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/2-0/do-wsdl-20.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: 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/2-0/do-wsdl-20.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. Location of the DODP Service Discovery File

This appendix is informative

The DODP Service Discovery file can be found here:

http://www.daisy.org/DODP/dodp-service-list.xml

Appendix C. Location of the DODP Reading System File

This appendix is informative

The DODP Reading System file can be found here:

http://www.daisy.org/DODP/dodp-reading-system-list.xml

Appendix D. 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 2.0 specification:

• Dave Gunn, DAISY Consortium Consultant (Chair)
• Daniel Ainasoja, Kolibre
• Keith Creasy, American Printing House for the Blind
• Hiro Fujimori, Shinano Kenshi
• Andrew Furlong, Vision Australia
• Jelle Martijn Kok, Solutions Radio
• Dominic Labbé, Humanware
• Claudio Montalban, Vision Australia
• Fredrik Schill, Textalk
• Edmar Schut, Dedicon
• Per Sennels, Norwegian Library of Talking Books and Braille
• Takuro Shiroki, Shinano Kenshi
• Sean Brougham, Vision Australia

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

• Johan Abbors, Kolibre
• Ole Holst Anderson, Nota
• David Andrews, Minnesota State Services for the Blind
• Roger Beatty, CNIB
• Geoff Gilmour-Taylor, CNIB
• Mark Klarer, American Printing House for the Blind
• Bert Paepen, Pyxima
• Bernd van Velsen, Pyxima
• Nick Williamson, RNIB

Version 1.0 of this specification was developed by the DAISY Consortium’s DAISY Online Working Group. The following individuals were members in good standing of the DAISY Online Working Group at the time of the publication of the 1.0 specification:

• Markus Gylling, DAISY Consortium (co-chair)
• Kenny Johar, Vision Australia (co-chair)
• Johan Abbors, Pratsam
• Hiro Fujimori, Plextor
• Geoff Gilmour-Taylor, CNIB
• 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 to the 1.0 specification:

• 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

Appendix E. Guidance

This appendix is informative

A separate guidance document has been created for use when implementing DAISY Online Services and Reading Systems which can be found on the following page:

http://www.daisy.org/projects/daisy-online-delivery/2-0/Guidance.html