Global Requirements

These requirements apply to all APIs produced by the DAP WG.

• APIs MUST be made available in a consistent fashion, hanging off a single access point;
• methods that may take a long time to complete MUST support asynchronous, cancellable operation.

Should the APIs be made available on navigator, navigator.device, or straight off a window.device?

Application Configuration

Due to overlapping with Widgets: The widget Interface [[WIDGETS-APIS]] and with Web Storage [[WEBSTORAGE]], this deliverable has been dropped.

Application Launcher

The following requirements have been expressed.

• A User Agent MAY provide means for non-web applications to register themselves as handlers for media types and URI schemes. (Note that this may be outside the scope of this API.)
• It SHOULD be possible to launch an application for which no media type or protocol handler exists.
• It SHOULD be possible to pass arguments to a launched application.
• It SHOULD be possible to launch an application asynchronously.
• It SHOULD be possible to launch an application synchronously.
• For applications that run synchronously, it SHOULD be possible to catch the output streams (STDOUT/ERR etc.).

The following requirements, while they could be considered to be functionally part of this API, are already addressed as part of the HTML5 [[HTML5]] Custom scheme and content handlers:

• This interface MUST enable (web) applications to register themselves as handlers for a specific protocol.
• A User Agent MAY provide default handlers for a specific protocol.
• This interface MUST enable (web) applications to register themselves as handlers for a specific media type.
• A User Agent MAY provide default handlers for a specific media type.

Calendar

This interface:

• MUST enable listing multiple available calendars;
• MUST expose some basic properties of calendars such as default time zone, name, etc.;
• MUST enable creating, deleting, and updating calendars;
• MUST enable creating, deleting, updating, and finding calendar events;
• MUST expose calendar event properties with a 1:1 mapping to iCalendar [[!RFC5545]] properties and values.

Camera

This interface:

• MUST enable capture of static images;
• MUST enable capture of videos;
• MUST enable listing the available cameras;
• MUST enable listing the available formats and codecs, per camera;
• MUST enable retrieval of the captured content;
• MUST provide some metadata about the captured content (e.g. width, height, format, duration);
• MUST enable choosing preferred aspects of the captured content (e.g. width, height, format, frame rate);
• MUST enable displaying a viewfinder;
• MUST support asynchronous, cancellable capture;
• SHOULD enable displaying a viewfinder as part of the document (e.g. as a video element [[HTML5]]);
• SHOULD enable control of the camera's capabilities (e.g. zoom, luminosity, night mode, focus mode).

Given support for capturing video, we need to take sound capture into account. Once that's supported, is there any reason not to support capturing sound on its own? If we go there, isn't this a Capture API, with the ability to list mikes?

We could very easily get bogged down in specifying camera capabilities and format feature variants — how do we decide which ones are reasonably in?

Communications Log

This interface:

• MUST be able to provide a list of incoming and outgoing communication events;
• MUST be able to search for events by type (email, phone, SMS...) as well as by content;
• MUST be able to expose relevant metadata about events (start and end time, to and from, etc.).

Contacts

This interface:

• MUST enable listing all available address books on the device;
• MUST enable listing all contacts in the address book(s);
• MUST enable reading the details for a contact;
• SHOULD enable creating a new contact;
• SHOULD enable updating a contact;
• SHOULD enable deleting a contact;
• SHOULD enable filtering the list of contacts to search for a subset.

Are there convincing use cases for supporting multiple address books in v1 (as opposed to just a default one, and maybe exposing more later)?

Do we need support for groups in v1?

File System

This interface:

• MUST integrate with the W3C File API [[!FILE-UPLOAD]];
• MUST enable listing items in a directory;
• MUST enable creating a file or directory;
• MUST enable deleting a file or directory;
• MUST enable writing to a file;
• MUST enable appending to a file;
• MUST enable getting some metadata about a file (e.g. size, creation and update time, media type);
• MAY enable setting some metadata on a file;
• SHOULD enable copying files and directories;
• SHOULD enable moving files and directories;
• MUST handle text encoding conversion when reading and writing to file (at least UTF-8 and UTF-16 LE/BE);
• SHOULD support binary access to file content;
• MUST enable navigating a directory tree;
• MUST reflect file system paths using a normalised separator (/) and in a consistent encoding;
• MAY provide conversion between paths and file: URLs;
• MAY support reading and writing in Base64 (or using data: URLs);
• SHOULD support reading lines from a text document;
• SHOULD support events for detecting the mounting/unmounting of a file system (e.g. to detect a memory card being plugged in);
• MUST support listing the available file systems;
• SHOULD provide access to a temporary storage location (a form of /tmp directory);
• MUST provide some file system metadata (e.g. size, available space, quota).

Gallery

This interface:

• MUST enable listing all available gallery sources, their names and types;
• MUST enable finding content inside a gallery;
• MUST enable adding, updating, and removing content from a gallery;
• MUST expose metadata about the gallery's content items (copyright, author, media-dependent information, etc.).

Exposing metadata is tricky, often giving a choice between creating an endless ontology or building an open-ended system that guarantees no interoperability.

A lot of this functionality can be provided if the Gallery API is basically a way of accessing well-known parts of the file system, and if the File System API has a way of exposing sufficient metadata. This could make for a very simple API.

Messaging

This interface:

• MUST support messages in one or several formats and transports supported by the platform (email, SMS, MMS...);
• MUST allow creating and sending messages;
• MUST support multiple accounts for each transport/format type;
• MUST support setting various envelope fields corresponding to the message type (email, SMS...);
• MUST support attaching files when the format allows it.

System Information & Events

This interface:

• MUST enable listing available power sources (batteries, wall...);
• MUST expose whether the device is running on battery or not;
• MUST expose charge level per battery and globally;
• MUST enable listing available network interfaces, their types (Wifi, 3G, LAN...), and signal strengths;
• MUST list which of the available network interface are active, and provide events to be informed of their status;
• MUST provide CPU information;
• MAY provide CPU load information;
• MUST enable listing storage areas, their types, writability, and available space;
• MUST provide RAM information;
• MAY provide RAM load information;
• MUST enable listing displays, as well as their colour depth, resolution, etc.;
• MUST enable listing input devices (mouse, keyboard, touch, keypad, voice, stylus...);
• MUST enable listing audio output devices and their properties;
• MUST enable listing audio input devices and their properties;
• MUST enable listing video capture devices and their properties;
• MUST enable listing picture capture devices and their properties;
• MUST enable listing thermal sensors, alongside their names and measurements;
• MUST enable listing ambient light sensors, alongside their names and measurements;
• MUST enable listing proximity detectors, alongside their names and measurements;
• MUST expose gyroscope and accelerometer capability and measurements;
• MUST enable listing vibration capability;
• MUST expose the availability of compass and geolocation capability.

This mixes system information and sensors — should they be separate? Should we have some system information and a universal sensor API? How do we get interoperability out of that?

Tasks

This interface:

• MUST enable listing multiple available task lists (projects);
• MUST expose some basic properties of projects such as default name, priority, etc.;
• MUST enable creating, deleting, and updating projects;
• MUST enable creating, deleting, updating, and finding tasks;
• MUST expose task properties with a 1:1 mapping to iCalendar [[!RFC5545]] properties and values (VTODO).

See the issues that are part of the Calendar API.

User Interface

This interface:

• MUST support beeping;
• MUST support vibrating;
• MUST support manipulating the backlight(s);
• MUST enable the creation, deletion, and update of native application menus, with arbitrary depth levels, and callbacks.