Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
Developing Web content for mobile devices is more challenging than developing for the desktop Web. Compared to desktop Web clients, Mobile Web devices come in a much wider range of shapes, sizes and capabilities. The Mobile Web developer relies upon accurate device descriptions in order to dynamically adapt content to suit the client. This document defines platform and language neutral programing interfaces that provide access to those device descriptions.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is a Public Working Draft of a possible future W3C Recommendation.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document is published as part of the W3C Mobile Web Initiative (MWI) by the Device Description Working Group (Member Only Link). It is a deliverable as defined in the Charter of that group.
Please send comments to public-ddwg@w3.org. This list is archived at http://lists.w3.org/Archives/Public/public-ddwg/.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 Introduction
1.1 Scope
1.2 Uses for the DDR-API
1.3 Reading the Specification
1.3.1 Conformance Information
1.3.1.1 Normative and Informative Parts
1.3.1.2 Normative Language for Conformance Requirements
2 Relationship with other specifications
2.1 CC/PP
2.2 DCCI
2.3 DPE
2.4 Delivery Context Ontology
3 Terminology
4 Conventions
4.1 Documentation Conventions
4.1.1 Bindings
4.2 Naming Conventions
4.3 Examples
5 Identification of the Delivery Context
5.1 Introduction
5.2 Context Key
5.3 Context Key Handler
6 DDR-API Abstract Data Model
6.1 Introduction
6.2 Common Datatypes
6.3 Additional Types
6.4 Property Collections
6.5 Metadata
7 IDL Definitions for the DDR-API
7.1 Core Interfaces
7.1.1 IDL Definition
7.2 Querying and Searching
7.3 The DDRException Exception
7.3.1 IDL Definition
7.3.2 DDR-API Exception Error Codes
7.4 Errors
7.5 Extended Interfaces
7.5.1 IDL Definition
8 DDR Extensions
8.1 Extending Device Descriptions and Properties
9 Conformance
9.1 Conformance Requirements for DDR-API Implementations
10 WSDL Language Binding
10.1 DDR-API Exception Interface
10.1.1 Properties of DDR-APIException:
11 Binding rules for mapping APIs to any programming language
A IDL Definitions for DDR-API
B Java API
C Informative Use Case: To Be defined
D Normative References
E Informative References
F Changes Since the Previous Version
F.1 Normative Changes
F.2 Informative Changes
G Acknowledgements (Non-Normative)
This section is informative.
Mobile Web development it is not as easy as conventional web development. Programmers must deal with a wide variety of device capabilities, an heterogeneous mix of software versions and different adherence to standards. For instance, there are different handsets (mobile phones, smart phones, PDAs) with different screen resolutions, input modes, memory, CPU constraints, etc.
Besides, although there is a convergence towards a unique markup language (XHTML), the reality nowadays is that different browsers support different versions of HTML-based and XML-based languages. Moreover, mobile web browsers that in theory support the same markup language often behave in different and unexpected manners. More generally speaking, the browser and the device are part of the delivery context, a set of attributes that characterizes the capabilities of the access mechanism, the preferences of the user and other aspects of the context into which a web page is to be delivered [DIGlossary].
The final page delivered to the user might depend on the delivery context. Top-quality mobile sites differentiate from less-quality sites because they take into account the delivery context when they are rendering a page. As a consequence, top-quality mobile sites provide the best user experience and usability, which is a critical point in the mobile space.
Device and browser descriptions are the two fundamental components of the delivery context. There are some properties of the device and browser that are inmutable and typically are stored in repositories of information maintained by content adaptation solutions, mobile telco operators or open source projects. One example of such a property is the color resolution of the display on a mobile device.
Programmers demand standard application programming interfaces (APIs) that simplify and provide a unified way of accessing the device and browser properties stored in Device Description Repositories (DDRs). This document defines those interfaces.
The W3C DDR API offers various levels of functionality to satisfy differing Use Cases [q.v.]. The classification of the various levels relates to conformance claims [q.v.]. The DDR Basic Interface provides read-only functionality to allow an adapting application to identify the Delivery Context (DC) and to query the DDR for attribute values for components of the DC.
In addition, it provides access to basic catalog information that allows it to find out about which attributes are supported and what devices and models are supported. Advanced functions allow the addition of information to the DDR and provide more elaborate access to the Cataloguing functions.
Many aspects of the operation of a real world DDR are not standardised by this recommendation, for example, user management, user identification and authentication, management of the data within the DDR. The recommendation makes no assumptions about the internals of the DDR, the physical storage mechanism, the distribution across actual servers and so on. In addition, the details of the operation of the API are not specified - e.g. how to instantiate and close the library, concurrency and threading and whether the calls are blocking or non-blocking.
The DDR-API can be used in any scenario that implies the necessity of accessing device descriptions. The DDR-API is not bound to any particular kind of device description or property.
However, it is noteworthy to point that one of the key uses for DDR-API are related to content adaptation for device independence. Materials to be used on a particular device may need to be tailored to take account of that device's particular capabilities. Layout, styling and the media associated with a web page may all need to be tailored based on the delivery context to achieve a good user experience.
The normative and informative parts of this specification are identified by use of labels within various sections. Generally, everything in the specification is considered to be normative, apart from the examples.
Individual conformance requirements or testable statements are identified in the DDR-API specification by the use of specific key words. In particular, the key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [IETF RFC 2119] .
This section is informative.
The DDR-API provides mechanisms for:
Discoverying an identifying a delivery context
Retrieving properties of a delivery context (previously discovered)
CC/PP is an RDF framework for defining vocabularies for capabilities of mobile devices
DCCI is the standard API that allow to retrieve delivery context properties from the client side. The capabilities made accesible through DCCI are very dynamic in nature.
DPE is a framework for retrieving device capabilities that can change during the lifetime of a user session
The Delivery Context Ontology is an ontology that captures all the knowledge behind the delivery context.
This section is informative.
An application that makes use of the DDR services to perform some functionality.
A description of an element of the delivery context.
A device property that can have different values (default, maximum, actual ...).
A key that identifies a delivery context in a DDR under the scope of a client session.
An abstract identifier that points to a context key in an specific DDR regarding a client session.
This section is informative.
This specification provides a normative definition of the interface based on OMG IDL [IDL].
In addition, it also provides a normative WSDL [WSDL] binding.
Examples given in this specification are informational. The programming language used in examples are Java and PHP.
This section is normative.
The DDR-API separates in different modules and functions the process of identification of the delivery context from the process of retrieving device properties. As a result the concepts of context key and context key handler are introduced.
This section is normative.
This section is informative.
The delivery context models the environment into which content is to be delivered. For Web Browsing, it includes, but is not limited to, network connections, gateways, proxies and a device running a browser (possibly with addtional helper applications). The device may have additional hardware attached, such as an external keyboard, display monitor, speech generation and assistive technologies such as a screen reader. Each identifiable item is called a "component of the Delivery Context", or component, for short.
Each component of an actual delivery context has a type. The DDR API does not prescribe which components any given DDR implementation may choose to recognise, nor does it prescribe the precise definition of any particular component type. For example, any DDR implementation may choose to model the DC in any way - a conforming DDR must, however, implement components that support the attributes identified by the [version of the] Core Vocabulary in some components. Typically, it is understood that most DDRs will share a similar view of the Component Types of Device Hardware and Browser.
This section is normative
This section specifies the DDR-API in terms of normative IDL definitions for its properties, interfaces and exceptions. It also defines the behavior of the DOM interfaces associated with DDR-API.
The DDR Interfaces are formally defined in terms of OMG IDL [IDL] interfaces.
DDR-API defines one specific additional exception, named DDR-APIException
, in addition to those that can defined by the DOM itself.
exception DDRException { unsigned short code; }; //Exception codes const unsigned short ACCESS_VIOLATION_ERROR = 1; const unsigned short NOT_SUPPORTED_ERROR = 2; const unsigned short PROPERTY_FILTER_ERROR = 3;
The following error codes can be returned with this exception.
ACCESS_VIOLATION_ERR
This exception is raised if an implementation of DDR-API, that supports access control, detects an illegal attempt to access the delivery context.
NOT_SUPPORTED_ERR
This exception is raised if a call is made to a method which is not supported by DDR-API. In particular, a number of standard DOM interface methods are not supported by DDR-API. Invocation of these methods must return this error code.
PROPERTY_FILTER_ERR
This exception is raised if a property filter performs an invalid or illegal operation when filtering a list of nodes returned during a search operation.
In general, DDR-API operations return values that may indicate error conditions. In "exceptional" circumstances, DDR-API operations may raise exceptions, for example, when an operation is impossible to perform.
This section is normative. It gathers together the conformance requirements for implementations of DDR-API defined in this specification.
A conforming DDR-API implementation must implement all the normative sections of this document.
A conforming DDR-API implementation
This section is normative. It describes a WSDL [WSDL] language binding for DDR-API.
DDR-APIException:
DDR-APIException.ACCESS_VIOLATION_ERR
The value of the constant ACCESS_VIOLATION_ERR
is 1
DDR-APIException.NOT_SUPPORTED_ERR
The value of the constant NOT_SUPPORTED_ERR
is 2
DDR-APIException.PROPERTY_FILTER_ERROR
The value of the constant PROPERTY_FILTER_ERROR
is 3
This section is normative
This appendix contains the complete OMG IDL [IDL] definitions for DDR-API
// File: DDR-API.idl #ifndef _DDR_IDL_ #define _DDR_IDL_ #pragma prefix "w3c.org" module ddr { const unsigned short UNSPECIFIED_ERROR = 1; const unsigned short NOT_SUPPORTED_ERROR = 2; const unsigned short ACCESS_VIOLATION = 3; const unsigned short SYNTAX_ERROR = 4; const unsigned short NO_SUCH_ELEMENT = 5; const unsigned short NO_SUCH_PROPERTY = 6; const unsigned short UNKNOWN_VALUE = 7; // A trade-off between concrete and generic exceptions should be taken exception DDRException { unsigned short code; }; typedef sequence<char> DDRString; typedef any DDRAny; typedef string Namespace; // Name of a property without a namespace typedef string PropertyName; typedef sequence<PropertyName> PropertyNames; // FQN of a property (includes a namespace) typedef string PropertyId; // XML-Schema datatype I guess typedef string PropertyType; // It represents a unit. typedef string PropertyUnit; // i.e. Needs a human to interpret typedef string PropertyDescription; typedef DDRAny ContextKeyHandler; // A query to a DDR typedef string DDRQuery; typedef string DeliveryContextComponent; // The identifier of a property in the ontology typedef string OntologyIdentifier; const Namespace DDR_VOCAB_NS = "http://www.w3.org/2007/mobile/DDRVocabulary"; const DeliveryContextComponent DELIVERY_CONTEXT = "http://www.w3.org/2007/DCO#DeliveryContext"; const DeliveryContextComponent DEVICE = "http://www.w3.org/2007/DCO#Device"; const DeliveryContextComponent WEB_BROWSER = "http://www.w3.org/2007/DCO#WebBrowser"; const PropertyUnit NO_UNIT = ""; enum PropertyResult { KNOWN_VALUE, UNKNOWN_VALUE, SEE_RELATED_PROPS, MULTIPLE_VALUES, NO_A_PRIORI_INFO }; // A property in a DDR // This represents a property i.e. all the characteristics of a property struct PropertyMetadata { // Short name of the property (normative according to the vocabulary) PropertyName name; // Id of the property (includes the namespace) PropertyId id; Namespace nmespace; // Identifier of the property in the ontology OntologyIdentifier ontologyId; // Type of property PropertyType type; // Related properties PropertyIds relatedProperties; // Default unit used in measuring the property PropertyUnit defaultUnit; // Informal description PropertyDescription description; }; struct PropertyValue { DDRAny value; PropertyUnit unit; }; struct FacetedPropertyValue { DDRAny currentValue; PropertyUnit unit; DDRAny defaultValue; DDRAny maxValue; DDRAny minValue; }; // A lis of values for a property interface PropertyValueList { readonly attribute unsigned long length; PropertyValue item(in unsigned long index) raises(DDRException); }; // This represents an element of the delivery context (Device, Browser, Display, Camera, etc) interface DCElementDescription { // What's a property name? URI according to the ontology? Shortcut? UAProf property?? DDRPropertyValue getPropertyValue(in PropertyName propertyName) raises(DDRException); // Does it raise an exception when the property is not available in that unit? How to deal with this DDRPropertyValue getPropertyValueInUnits(in PropertyName propertyName,in Unit unit) raises(DDRException); DDRPropertyValueList getPropertyValues(in PropertyName propertyName) raises(DDRException); DDRPropertyValueList getPropertyValuesInUnits(in PropertyName propertyName,in Unit unit) raises(DDRException); }; interface DCElementDescriptionList { readonly attribute unsigned long length; DCElementDescription item(in unsigned long index) raises (DDRException); }; // This interface represents all the delivery context. Usin this interface I can ask for different properties of the delivery context interface DeliveryContext : DCElementDescription { DCElementDescription getDeliveryContextElement(in DeliveryContextElement path) raises(DDRException); }; module core { // A condition over to query info on the DDR typedef string DeliveryContextCondition; valuetype ContextInfoPair { public string element; public string value; }; typedef sequence<ContextInfoPair> ContextInfo; interface ContextInformation { void put(in string element,in string value); string get(in string element); ContextInfo getAll(); }; interface Repository { DeliveryContext getDeliveryContext(in ContextInformation contextInfo) raises(DDRException); DCElementDescriptionList query(in DeliveryContextCondition condition) raises(DDRException); }; }; // To be defined Ckeck the Requirements module admin { interface RepositoryExt : Repository { void addProperty(in DDRProperty property); void addDCElementDescription(); void removeProperty(); void removeDCElementDescription(); }; }; }; #endif
This section is informative
Editorial note | |
The WG has not agreed yet if the Java Binding has to be normative or informative |
This section is informative. It provides an illustration of how the DDR-API could operate.
This section describes the changes introduced in this version of the specification.
This document was produced with the help of the Device Description Group participants: