Deliverable D3.2 FP7-ICT-2009-5 257103 June 2011 D3.2: webinos phase I device, network, and server-side API specifications FP7-ICT-2009-5 257103 D3.2: webinos phase I device, network, and server-side API specifications page: 2 of 396 Project Number : FP7-ICT-2009-5 257103 Project Title : Secure WebOS Application Delivery Environment (webinos) Deliverable Type : Public Deliverable Number : D 3.2 Contractual Delivery Date : June, 30th, 2011 Actual Date of Delivery : June, 30th, 2011 Title of Deliverable : webinos phase I device, network, and server-side API specifications Contributing Work Package : WP 3 Nature of Deliverable : Report Editor : SonyEricsson Authors : Fraunhofer FOKUS, Deutsche Telekom, ERCIM, Telecom Italia, TNO, BMW F+T, SonyEricsson., ISMB, Document History Version Date Author (Partner) Remarks 0.9 01/07/2011 SonyEricsson Initial version created from Wiki 1.0 α 04/07/2011 Fraunhofer FOKUS Updated, Word-formatted version This work is partially funded by webinos, an EU-funded project under the EU FP7 ICT Programme, No 257103. FP7-ICT-2009-5 257103 page: 3 of 396 D3.2: webinos phase I device, network, and server-side API specifications Abstract This deliverable covers the APIs to be implemented by a webinos device. According to the use cases and requirements defined in WP2 and the common components introduced in task 3.1, task 3.2 has defined a set of application programming interface specifications (APIs) to make the desired functionalities available to webinos applications. Due to earlier or ongoing standardization and implementation activities, e.g. within W3C and WAC, some needed APIs are already specified and available in modern browsers. Other APIs have been specified but implementations have not yet been established in existing browsers.Some APIs needed to fulfill webinos functionality do not yet exist so these APIs have to be specified within the webinos project. A key feature of webinos is the ability to discover services on remote devices and access these services using APIs. For example, an application can use the core webinos Service Discovery API to search for a geolocation service on another device and then access this service through the standard W3C Geolocation API. The webinos APIs can be divided into a number of categories: • Webinos base and generic objects/interfaces: For example the webinos core interface • APIs for service discovery and remote API access: APIs allowing applications to discover other devices and services/applications on other devices and on network servers and access these remote services. • HW Resources APIs: APIs allowing applications to access information and functionality relating to device HW resources such as GPS, camera, microphone, sensors, etc. • Application Data APIs: APIs allowing applications read and write access to application capabilites such as contact items, calender information, messages, media files, etc. • Communication APIs: APIs allowing applications to communicate with other applications in the same or another device. • Application execution APIs: APIs allowing webinos applications to launch other webinos and native applications. • User profile and context APIs: APIs allowing applications access to user profile data and user context. • Security and Privacy APIs: APIs related to the security model for webinos Note: This Word/PDF linear document represents only a snapshot of the specification for the purpose of review as a single document. The actual specification is located on the webinos redmine/Wiki. That version is the one relevant for the work within the project. Due to the close interworking between the specification and the implementation work packages in webinos, experience gained about gaps that need to be filled in the specification will be fed back directly into the online specification. The Word/PDF document has been exported from the online version and represents the status of the specification on June, 30th, 2011. Keyword list: webinos, specification, API, JavaScript, attestation, authentication, context, events, applauncher, messaging, nfc, payment, sensors, discovery, tv, suerprofile, vehicle, webinoscore, widget, calendar, contacts, device (status, interaction, orientation), file (reader, writer, directory), gallery, geolocation, media capture FP7-ICT-2009-5 257103 D3.2: webinos phase I device, network, and server-side API specifications page: 4 of 396 Content 1. INTRODUCTION ............................................................................................................... 8 2. ACKNOWLEDGEMENT .................................................................................................. 9 3. METHODOLOGY .............................................................................................................. 9 4. API LANDSCAPE ............................................................................................................. 10 World Wide Web Consortium (W3C) ............................................................................. 10 Web Hypertext Application Technology Working Group (WHATWG) ..................... 12 Wholesale Application Community (WAC) .................................................................... 12 PhoneGap ........................................................................................................................... 12 Nokia/Symbian Web Runtime environment ................................................................... 12 5. API TYPES ........................................................................................................................ 13 JavaScript APIs ................................................................................................................. 13 Using HTML-elements ...................................................................................................... 13 Using DOM events ............................................................................................................. 14 Using REST ........................................................................................................................ 14 6. API INVESTIGATIONS .................................................................................................. 14 HW Resource APIs ............................................................................................................ 15 This work is partially funded by webinos, an EU-funded project under the EU FP7 ICT Programme, No 257103. FP7-ICT-2009-5 257103 D3.2: webinos phase I device, network, and server-side API specifications page: 5 of 396 APIs for which no existing standards/implementations exist ........................................ 29 Application Data APIs....................................................................................................... 35 Communication APIs ........................................................................................................ 43 Application execution APIs............................................................................................... 48 Discovery APIs ................................................................................................................... 58 Security and Privacy APIs ................................................................................................ 65 User profile and context APIs ........................................................................................... 67 7. TOOLS FOR API SPECIFICATIONS ........................................................................... 71 8. JS API DESIGN PATTERNS AND GUIDELINES ....................................................... 72 9. LIST OF WEBINOS PHASE 1 API SPECIFICATIONS ............................................. 73 10. APIS SPECIFIED BY WEBINOS ................................................................................... 76 API Summary .................................................................................................................... 76 APIs: The attestation module ........................................................................................... 78 APIs: The authentication module .................................................................................... 87 APIs: The context module ................................................................................................. 94 APIs: The events module ................................................................................................ 105 APIs: The AppLauncher module ................................................................................... 128 APIs: The messaging module .......................................................................................... 136 This work is partially funded by webinos, an EU-funded project under the EU FP7 ICT Programme, No 257103. FP7-ICT-2009-5 257103 D3.2: webinos phase I device, network, and server-side API specifications page: 6 of 396 APIs: The nfc module ...................................................................................................... 166 APIs: The payment module ............................................................................................ 187 APIs: The sensors module ............................................................................................... 202 APIs: The discovery module ........................................................................................... 217 APIs: The tv module .......................................................................................................