From MemberWiki

This wiki page is one of several wiki pages for the Mobile TF work on Mobile Device APIs. Here are the pages:

• Mobile Device APIs initiative home page
• Mobile Device APIs Objectives
• Mobile Device APIs Use Cases
• Mobile Device APIs Requirements
• Mobile Device APIs Security
• Mobile Device APIs Due Diligence Industry Survey
• Mobile Device APIs initiative todo list

Contents 1 Introduction 2 Notational Conventions 3 General requirements 3.1 Application deployment 3.2 Introspection 3.3 Standardized loader 4 Device service API requirements 4.1 Call 4.2 PIM 4.2.1 Messaging 4.2.2 Email 4.2.3 Address book 4.2.4 Agenda/Calendar 4.2.5 Notes 4.2.6 Tasks 4.3 Indicators 4.3.1 Power 4.3.2 Network 4.3.3 Location 4.3.4 Time 4.4 Data feeds 4.5 Files & media 4.5.1 Media resources 4.5.2 File I/O 4.6 Camera 4.7 Effectors 4.8 Miscellaneous 4.9 Network 4.9.1 Bluetooth 4.9.2 Wi-Fi 5 Security requirements 6 Requirements beyond immediate scope 6.1 Already addressed by browser 6.2 Soon to be addressed by browser 6.3 Currently not supported by browser 6.4 Too niche oriented

Introduction

Device API requirements fall into two broad categories:

• General requirements that apply to the framework in which individual APIs are made available and affect the manner in which the specific device features are accessed.
• Device service APIs

Requirements in each of these areas are discussed below.

Notational Conventions

Each distinct requirement should include text that indicates the relative priority for that particular feature, plus any other supplemental information about that item's urgency or other factors affecting that item. Each item should be annoatated at a minimum using the terms MUST, SHOULD and MAY, where we assume that OpenAjax Alliance will be developing a future specification (i.e., open standard) and/or open source, and in this context the words have the following meaning:

1. MUST means that the item is an absolute requirement for the first version.
2. SHOULD means that there may exist valid reasons in particular circumstances to ignore the item, but the full implications must be understood and carefully weighed before choosing a different course.
3. MAY means that item will be considered, but further examination is needed to determine if the item should be treated as a requirement.

General requirements

Application deployment

The specific APIs discussed in the next section are used in deployed applications. The application deployment requirements originate in the isolation and user interface use cases identified in Mobile Device APIs Use Cases. In each deployment model, applications use a rendering and layout framework, programming toolkit, and network protocol. Here are the four categories of deployment models for Ajax applications and their relative priority:

1. Full-frame Web sites MUST
2. Web runtime-based widgets SHOULD
3. Embedded Web controls inside native applications MAY
4. Site specific browser applications (SSBA) MAY

Introspection

These APIs are available for an application to discover the capabilities of the OpenAjax device services. As part of the API, applications can:

1. check on the availability of a particular API
   1. obtain the version(s) supported
2. check on the access rights for using the API

Each module should be globally identifiable and this identifier should be used during introspection. Presumptively, JavaScript dot notation for naming globals is the standard for uniquely identifying modules. The W3C has also asked OOA for help in identifying ways of identifying device capabilities.

Standardized loader

Javascript APIs and scriptable plug-ins add to the footprint of a browser running a JavaScript application. Therefore, applications require a means of controlling when the OpenAjax APIs and their implementations are loaded. The loading can be performed in one of the following two ways. Loading is also an important event that needs to be controlled through appropriate security policies.

1. Load-and-bind, e.g., a load API takes a module identifier and adds the required API to the globals, and a bind step uses/associates the global with an application-specific variable
2. Call, e.g., a native object that can be initialized using regular JavaScript techniques such as new and new ActiveXObject

Note to API developers: The mechanism depends on the deployment choice - as a native object or as a plug-in.

Device service API requirements

The following represents an attempt to capture all of the different sorts of Mobile Device APIs that are candidates to support in the first version or future versions:

Call

1. Setup call
2. Accept call
3. Release call
4. Divert call
5. Send DTMF
6. video
   1. send
   2. receive
   3. pause
7. Call logs - placed/received/missed/all
   1. list
   2. remove
   3. get details
8. Events
   1. call waiting
   2. missed call
   3. mail received
      1. voice
      2. video

PIM

Messaging

1. send
   1. text
   2. media
2. list
   1. inbox/outbox/sent
   2. other folders - trash, personalized
   3. details
      1. text
      2. media
3. remove
4. markAsRead
5. status
6. incoming message

Email

1. create new
2. send
   1. with media
3. list
   1. inbox/outbox/sent
   2. other folders - trash, personalized
   3. get details
4. get
   1. headers
   2. body
   3. attachments/parts
5. delete
6. move
7. markAsRead
8. status
9. incoming message
10. sync with server

Address book

1. subscribe
2. unsubscribe
3. create
4. search
5. get details
   1. contact info
   2. photo
6. remove
7. change
8. favorite

Agenda/Calendar

1. subscribe
2. unsubscribe
3. search
   1. get details
4. remove
5. change
6. add
7. reminder
8. timer
9. dismiss
10. snooze
    1. set
    2. clear
    3. remaining
    4. alarm

Notes

1. list
2. create list
3. get details
4. create
5. update
6. delete

Tasks

1. list
2. create list
3. get details
4. create
5. update
6. delete
7. reminder event

Indicators

Indicators are used for keeping track of the current status of a number of peripherals attached to the device. These requirements are not meant to effect any changes to the sources of these indicators.

Power

1. power source
2. charge level
3. critical battery
4. charging
5. charging interrupted
6. charge completed
7. power source changed

Network

1. signal strength
2. network type - Cellular/Wi-Fi
   1. Cellular
   2. Wi-Fi
   3. Bluetooth
3. out of coverage
4. signal available
5. roaming
6. in home

Location

1. get current location
2. location changed
3. signal lost
4. orientation
   1. started
   2. interrupted
   3. completed

Time

1. now
   1. date
   2. time
   3. change
   4. time zone
2. time zone change

Data feeds

Some background on this new section: Oracle proposes a model in which applications use Ajax to subscribe to Atom feeds for data. These feeds are synchronized (updates sent to and fetched from the server) by an implementation of this API and the API provides applications a means of controlling the synchronization process. Business applications require data to be available when the device is out of coverage. This data is also required with relatively low latency. Previously this requirement has been met with the use of a relational database designed for embedded platforms. However, such applications can't be easily reconciled with the Ajax model. The Atom publishing protocol IETF's RFC5023 defines the semantics for these operations.

Oracle is willing to contribute a detailed specification to OpenAjax describing the Ajax API for controlling synchronization. When an application wishes to access the locally cached data, it uses the same techniques used for accessing or changing any data on the Web - using HTTP HEAD, OPTIONS, GET, PUT, POST, and DELETE operations. Data can be added to and removed from such feeds even when there is no connectivity to the server. The server may control this cache in the same way that servers control HTTP caches inside the browser.

1. subscribe
   1. authorization headers
   2. links followed
   3. subscription interval
2. subscription
   1. unsubscribe
   2. list
      1. memory used
      2. status
   3. pause
   4. resume
3. error
4. clear error
5. subscription completed

Files & media

Media resources

1. render
   1. image
   2. audio
   3. video
2. get metadata
   1. image
   2. audio
   3. video
3. play list
   1. play
   2. get details
   3. add to
   4. create
   5. remove
4. remove
5. capture
   1. image
   2. audio
   3. video
   4. 2d bar code
6. annotate
   1. image
   2. audio
   3. video

File I/O

1. create
2. read
3. write
4. append
5. remove
6. disk space (total, available)

Camera

1. zoom
2. resolution
3. brightness
4. timer

Effectors

1. vibrate
2. backlight
3. mode
   1. set
   2. get

Miscellaneous

1. Accelerometer (i.e., portrait/landscape tilt event and ability to query)
2. Out of memory event, memory query (total memory, available memory)
3. console manager

Network

These requirements provide means for an application to control the connectivity of a device with various kinds of networks - cellular, Wi-Fi, and Bluetooth

Bluetooth

1. start
2. stop
3. list devices
   1. device info
   2. connected state
   3. connect
   4. disconnect
   5. send
   6. receive

Wi-Fi

1. start
2. stop
3. list networks
   1. network info
   2. connect
   3. disconnect

Security requirements

Stored at: Mobile Device APIs Security

Requirements beyond immediate scope

Existing mobile application platforms and standards offer a number of device services in addition to those identified in the requirements above.

Already addressed by browser

• Content handler (JSR 211) - We assume that for version 1 the HTML markup (e.g., <img> to identify an image) or browser engine sniffing of the content will do the job of mapping content to an appropriate handler. Whatever, we assume that the browser is providing all of the rendering.
• Internationalization (JSR 238) - We assume that content developers will internationalize their HTML content using the same approaches as they do for the desktop Web.
• Speech synthesis
• Bridging to Java or COM
• Debugging and diagnostics
• Web Services (JSR 172) - We assume that Web Services will be invoked using standard Ajax techniques, such as POST, XMLHttpRequest, or dynamic SCRIPT tag

Soon to be addressed by browser

• audio and video (MSR 135) - We assume that these features will be available through markup, such as via HTML <object> or HTML5 <audio> or <video>
• Vector graphics (JSR 226/287) - We assume that all rendering is done by the browser engines, such as including SVG and/or Canvas support.

Currently not supported by browser

• Programming
  • Google Gears features - such as workerpools
  • Application launching
  • Softkey management
• Networking
  • Sockets
  • WiFi
  • Infrared
  • SIP (JSR 180) - We are trying to avoid putting any non-HTTP networking features into version 1.
• Security
  • Security and Trust Services (JSR 177) - The features from JSR 177 should server as input into our the security framework efforts, but we don't need to add any specific APIs that correspond to JSR 177.
  • Smart card
  • Certificates

Too niche oriented

• Multimedia supplement (JSR 234) - We list camera in the requirements, but the other features in this JSR we feel are too advanced and niche-oriented for our version 1 effort
• 3D graphics (JSR 284) - We assume that all rendering is done by the browser engines, and 3D isn't a top priority for most of the use cases.