Opera Platform DOM Interface Specification 1.1
Opera Software Specification 28 April 2005
- Editor:
- Arve Bersvendsen, arveb@opera.com
- Contributors:
- Ian Hickson, ian@hixie.ch
Copyright © 2003-2005 Opera Software.
Copyright © 2003-2005 Opera Software.
The Opera Platform specification describes a set of DOM APIs, including new interfaces and new events, to let telecom operators write Web-based portals that interact with their customers' devices. These APIs provide access to device status flags, messaging, OS applications, and related features.
This document was produced by Opera Software. Comments on, and discussions of this draft can be sent to the document editor.
This is a working draft and may therefore be updated, replaced or rendered obsolete by other documents at any time. It is inappropriate to use Working Drafts as reference material or to cite them as other than "work in progress".
To find the latest version of this document, please follow the "Latest version" link above.
This document describes a set of DOM interfaces for use in the [Opera Platform] for accessing OS-native features such as battery indicators, SMS messages, and the like.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Diagrams, examples, and notes are non-normative. All other content in this specification is intended to be normative.
interface OperaPlatform {
/* General Status Indicators */
const unsigned short BATTERY = 1;
const unsigned short MAINS = 2;
const unsigned short CHARGING = 3;
readonly attribute unsigned short power;
readonly attribute float batteryCharge;
readonly attribute float signalStrength;
readonly attribute boolean keypadLocked;
readonly attribute boolean alarmSet;
readonly attribute DOMString homeNetwork;
readonly attribute DOMString activeNetwork;
readonly attribute DOMString wallpaper;
/* Interface Status */
const unsigned short NONE = 0;
const unsigned short CLOSED = 1;
const unsigned short CONNECTING = 3;
const unsigned short IDLE = 5;
const unsigned short ACTIVE = 7;
unsigned short getInterfaceStatus(in DOMString interface);
readonly attribute DOMStringList interfaces;
/* Profiles */
readonly attribute DOMStringList profiles;
attribute DOMString activeProfile;
/* Messaging */
readonly attribute ContactList contacts;
readonly attribute MessageStore messages;
readonly attribute MissedCallList missedCalls;
DraftMessage createMessage();
Contact createContactByAddress(in DOMString method, in DOMString address);
Contact createContactByName(in DOMString name);
/* Broadcast/Push message support */
void setChannelFilterList(in int...); // zero or more integer arguments
readonly attribute ChannelList broadcastChannels;
readonly attribute DOMStringList broadcastMessages;
/* Calendars, Alarms, To Do lists */
readonly attribute Calendar calendar;
readonly attribute ToDoList todoList;
/* System and Applications */
readonly attribute System system;
readonly attribute ApplicationList applications;
Application launchCalendar();
Application launchCallLog();
Application launchCamera();
Application launchContactList();
Application launchMessages();
Application launchTelephone();
Application launchURI(in DOMString uri);
Application launchAppById(in DOMString id);
Application launchAppByName(in DOMString name);
/* System-Specific APIs */
DOMString getDeviceSpecificString(in DOMString key);
};
The object device, which implements the
OperaPlatform
interface, is made available in the host environment.
Events in this specification are fired on the device object, which therefore also
implements the EventTarget interface. [DOM3EVENT]
No Opera Platform-specific exceptions are raised by Opera Platform interfaces in this version (failures are largely silent). DOM exceptions are used when the API is used incorrectly. A future version of the Opera Platform may raise specific exceptions in device error conditions.
Some aspects of the OperaPlatform interface are
susceptible to race conditions. For example, while a script is
interating through a user's mailbox, new mail could arrive, or
other applications on the device could remove old messages. This
specification makes no attempt to work around these issues.
Authors should be aware of them and write code accordingly.
These indicators return general status information about certain aspects of the device.
power attribute, of
type unsigned short, readonlyBATTERYMAINSCHARGINGbatteryCharge
attribute, of type float, readonlysignalStrength
attribute, of type float, readonlykeypadLocked
attribute, of type boolean, readonlyalarmSet attribute,
of type boolean, readonlyhomeNetwork
attribute, of type DOMString, readonlyactiveNetwork
attribute, of type DOMString, readonlywallpaper
attribute, of type DOMString, readonlyThe following function, which would be called on a regular
basis, sets the class of an element to a particular value from
level0 to level5 depending on the
charge of the device's battery:
function update() {
document.getElementById("battery").className = 'level' + (5 * device.batteryCharge).toFixed();
}
This could be used with the following CSS, for instance, to show a battery meter that shrunk in steps over time:
#battery { border: solid navy 0.1em; background: blue; height: 0.8em; }
#battery.level0 { width: 0.2em; background: red; border-color: maroon; }
#battery.level1 { width: 1em; }
#battery.level2 { width: 2em; }
#battery.level3 { width: 3em; }
#battery.level4 { width: 4em; }
#battery.level5 { width: 5em; }
Similarly, the following script updates a message based on the
state of the power source. This function could be used as an
event handler for the powerChanged message.
function updatePower(event) {
var node = document.getElementById('powerMessage').firstChild;
if (device.power == device.CHARGING) {
node.data = "Battery is charging...";
} else if (device.power == device.MAINS) {
node.data = "Battery is full.";
} else {
node.data = "Battery is draining...";
}
}
Status change events are fired when important state flags change state. They are not fired when the signal or battery power levels change, since that happens continuously. Scripts are encouraged to simply update their battery and signal indicators on a timer, possibly updating more frequently if the user is actively using the device.
The powerChanged
event has the namespace
http://www.opera.com/opera-platform, does not
bubble, is not cancellable, and has no default action. It has no
context information, and thus uses the normal Event
interface.
It is fired whenever the value of the power attribute changes. It is dispatched on
the device object.
The keypadLockedChanged
event has the namespace
http://www.opera.com/opera-platform, does not
bubble, is not cancellable, and has no default action. It has no
context information, and thus uses the normal Event
interface.
It is fired whenever the value of the keypadLocked attribute changes. It is
dispatched on the device
object.
The alarmSetChanged event has
the namespace http://www.opera.com/opera-platform,
does not bubble, is not cancellable, and has no default action.
It has no context information, and thus uses the normal
Event interface.
It is fired whenever the value of the alarmSet attribute changes. It is
dispatched on the device
object.
The networkChanged
event has the namespace
http://www.opera.com/opera-platform, does not
bubble, is not cancellable, and has no default action. It has no
context information, and thus uses the normal Event
interface.
It is fired whenever the homeNetwork and activeNetwork attributes change. It
is dispatched on the device
object.
The wallpaperChanged event has
the namespace http://www.opera.com/opera-platform,
does not bubble, is not cancellable, and has no default action.
It has no context information, and thus uses the normal
Event interface.
It is fired whenever the wallpaper attribute changes. It is
dispatched on the device
object.
The Opera Platform provides operators with access to the various networking and communications interfaces available on the host device.
getInterfaceStatus()To fetch the current status of a interface, the getInterfaceStatus() method is
used. It takes one argument, of type DOMString, the
name of the interface to examine. Valid values are described in
the section on Interface
Types below.
The value it returns is an unsigned short in the form of a bit mask:
MSB LSB
┌──┬──┬──┬──┬──┬──┬──┬──┐
│ │ │ │ │ │04│02│01│
└──┴──┴──┴──┴──┴──┴──┴──┘
│ │ ╰── interface type available
│ ╰───── interface type is active
╰──────── interface type is connected
Note that if bit 1 is 0, then other bits must always be 0
(i.e. interface statuses can never be even numbers) because it
makes no sense for an interface to be connected or active if it
isn't available. Thus, the possible return values from
getInterfaceStatus()are:
NONECLOSEDCONNECTINGIDLEACTIVEinterfacesThe interfaces
attribute, of type DOMStringList, readonly,
enumerates the list of interfaces the device supports. In the
case that the device supports on-the-fly changes to its hardware
configuration, the returned list is live. Changes to the
physical availability of interfaces affects the contents of the
list. The order of items in the list is arbitrary.
The list of interfaces in the interfaces list is the exact list of
interfaces that, when passed to the getInterfaceStatus() method,
are guarenteed to return non-zero values.
The following interface types are predefined:
GSMGPRSUMTSWCDMABlueToothIrDA802.11b802.11gEthernetThey refer to the respective interfaces (for example the
interface type GPRS refers to the GPRS connection,
and IrDA refers to the IrDA infrared port).
If the device has more than one instance of an interface type,
e.g. a device with two infrared ports, then the first instance
has the name given in the list above, and subsequent instances
have the name with a hyphen and a decimal number appended, the
number representing the number of the instance, starting with 2
for the second instance. For example, two infrared ports would be
called IrDA and IrDA-2.
Interface types are case sensitive. Types not in the list
above should be prefixed with x-; for example,
x-BongoDrums for a device with a Bongo Drums
interface.
interface InterfaceEvent : Event {
readonly attribute DOMString interface;
readonly attribute unsigned short status;
void initInterfaceEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMString interfaceArg,
in unsigned short statusArg);
// For DOM Level 3 support
void initInterfaceEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMString interfaceArg,
in unsigned short statusArg);
}
There is only one type of interface event, interfaceChanged, with
namespace http://www.opera.com/opera-platform, which
does not bubble, is not cancellable, and has no default action.
It uses the InterfaceEvent interface to store
context information.
It is fired when the status of an interface changes.
The interface
attribute of the event will be one of the interfaces, and the value of the
status attribute will be the
value that would be returned by a call to getInterfaceStatus() for that
interface at the moment the event is dispatched.
The interfaceChanged event is
dispatched on the device
object.
The Opera Platform provides operators with access to the various ring tone profiles available on the host device.
A profile controls how the device will sound when an incoming message or call is received.
Future versions of this specification will expose profiles as objects (that stringify to their name). These objects will have methods that can be used to trigger the incoming message ring tones, configure the ring tones, etc.
profilesThe profiles attribute,
of type DOMStringList, readonly, enumerates the list
of profiles the device has. In the case that the device supports
on-the-fly changes to its list of profiles, the returned list is
live. The order of items in the list is arbitrary but
should be consistent across sessions.
activeProfileThe activeProfile
attribute, of type DOMString, contains the value of
the active profile. It can be set, thus changing the currently
selected profile. (Doing so fires a profileChanged
event.)
interface ProfileEvent : Event {
readonly attribute DOMString profile;
void initProfileEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMString profileArg);
// For DOM Level 3 support
void initProfileEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in DOMString profileArg);
}
There is only one type of profile event, activeProfileChanged,
with namespace http://www.opera.com/opera-platform,
which does not bubble, is not cancellable, and has no default
action. It uses the ProfileEvent interface to store
context information.
It is fired whenever the active profile changes.
The profile attribute of the event will be one of
the profiles, and will
equal the value of activeProfile at the moment the
event is dispatched.
The activeProfileChanged event is
dispatched on the device
object.
Future versions of this specification may have other profile events, for example events triggered when a profile's settings change.
The device object is the
starting point for all messaging features of the Opera
Platform.
The contacts attribute
gives access to the user's OS contact list through a
ContactList interface.
The user's contacts may thus be manipulated.
The messages attribute
gives access to the user's OS message store through a
MessageStore interface.
The user's messages may thus be manipulated as well.
Creating and then sending new messages is done by obtaining a
DraftMessage via the
createMessage()
method. This method takes no arguments and returns an empty draft
message.
Creating contacts, either to add to the user's contact list or
to use as temporary placeholders when the user has entered an
address directly without selecting a contact from the OS contact
list can be done using the two methods createContactByAddress() and
createContactByName().
The createContactByAddress()
method takes two arguments, an address, and a messaging
method. It returns a contact that has been suitably
prefilled so that the given address for the given method is as
per the arguments, and the name of the contact is
the same as the given address.
The createContactByName()
method only takes one argument, a name. It returns a contact with
no addresses and the given name.
There are several different methods via which messages may be sent and received.
| Method | Description | Required fields | Optional fields |
|---|---|---|---|
sms |
An SMS. Can only contain one attachment, containing text, with a maximum length. (Theoretically, SMS messages can also contain other content, such as low resolution pictures or ring tones, but the Opera Platform does not currently support this.) | to | |
mms |
An MMS. Unrestricted content. | to | |
email |
An [RFC822] Internet e-mail message. Unrestricted content. | subject, to, from | cc, bcc |
bluetooth |
A BlueTooth message. One attachment of any type. | subject, to | |
irda |
An infrared message. One attachment of any type. | subject | |
telephone |
Not actually valid for messages, used only as the contact method for voice calls. | n/a | n/a |
Messaging methods are case sensitive. Types not in the list
above should be prefixed with x-; for example,
x-jabber for a message sent via the Jabber instant
messaging system.
interface Contact {
attribute DOMString name;
readonly attribute DOMStringList methods;
readonly attribute ContactList contactList;
DOMString getAddress(in DOMString method);
void setAddress(in DOMString method, in DOMString address);
Application launchApplication();
void call();
}
The Opera Platform provides a simple interface to the system
address book. The interface is significantly more limited than
the functions the OS is likely to expose for controlling the
address book. To give the user more complete control, either the
launchContactList() method should be called on the
device object (to show the
application normally) or the launchApplication()
method should be called on a Contact object (to start the application
with a particular contact selected).
Each contact has a name, and can have one address set for each contact method. If the contact has more than one address associated with a particular method, this interface only accesses the first one.
This interface is also used to represent contacts that are not on the user's contact list, such as unknown addresses in incoming messages.
Contacts can also be created dynamically using the
createContactByName() and
createContactByAddress()
methods.
nameThe name attribute, of type
DOMString, readonly, is the name of the contact, as
a locale-specific concatenation of the firstname and
lastname attributes.
firstnameThe firstname attribute, of type
DOMString, is the first name of the contact.
lastnameThe lastname attribute, of type
DOMString, is the last name of the contact.
methodsThe methods attribute, of
type DOMStringList, is a list of the contact methods
that are accessible via getAddress(). The list is live. It will
be updated to always accurately reflect the list of available
methods.
A contact on the device may have several addresses of the same type, and with different profiles. Therefore the method accepts two postfixes.
home or workWhen the location postfix is present, the numeric post-fix MUST be present. Valid messaging methods could be sms-1-work or sms-2-home.
contactListThe contactList
attribute, of type ContactList, contains a reference to
the contact list from which the contact was found. It is null for
orphan contacts (such as those created with createContactByName() or those
representing unknown callers for missed calls).
getAddress()The getAddress()
method is used to obtain the address of the contact for a
particular method. It takes one argument, method, of
type DOMString. It returns the address as a
DOMString.
The valid method types are described in the
section on Messaging
Methods.
If an unrecognised method, or a method for which the contact
has no address, is passed, then the return value is
null. The list of methods which will not return
null is given by the methods list.
setAddress()The setAddress()
method is used to set the address of the contact for a particular
method. It takes two arguments, method, of type
DOMString, which contains the method to change, and
address, of type DOMString, which
specified the new address. It has no return value.
The valid method types are described in the
section on Messaging
Methods. If, by using this method, a new address is
added to the contact, the methods list is updated too.
If the method or address are invalid, or some other error occurs, the call silently fails.
call()If the contact has an address for the telephone
method, then this invokes the dialling application and causes it
to call this contact. Otherwise it does nothing.
interface ContactList {
readonly attribute unsigned long length;
Contact item(in unsigned long index);
Contact namedItem(in DOMString name);
void add(in Contact contact);
void remove(in Contact contact);
}
This interface represents a list of Contacts. The namedItem()
method allows access by name, and the item() method
allows access by integer. If the argument passed to
namedItem() does not match any of the contacts'
name attributes, or if the index passed to
item() is less than zero or greater than or equal to
the value of the length attribute (which returns the
number of items in the list), then the return value should be
null.
In the ECMAScript binding, objects implementing this interface
can also be dereferenced using square bracket notation (e.g.
contactList[1] or contactList["ben"]).
Dereferencing with an integer index is equivalent to invoking the
item() method with that index, and dereferencing
with a string index is equivalent to invoking the
namedItem() method with that index.
The order of contacts in contact lists is arbitrary, but should be well-defined. It is recommended that it be alphabetical for contact lists that represent OS lists, and that it be the insertion order for lists generated by scripts that use this interface.
In addition, the interface implements two methods to add and
remove contacts from the contact list. The add()
method adds its argument to the list (unless it is
null or already on the list, in which case it does
nothing), and the remove() method removes its
argument from the list (unless it is null or not on
the list in the first place, in which case it does nothing).
In bindings that support operator overloading, the
+= operator is implemented via a call to
add() and the -= operator via a call to
remove().
There are two kinds of message interfaces, both of which
derive from the AbstractMessage interface.
interface AbstractMessage {
attribute DOMString subject;
readonly attribute ContactList to;
readonly attribute ContactList from;
readonly attribute ContactList cc;
readonly attribute ContactList bcc;
readonly attribute AttachmentList attachments;
attribute DOMString content;
}
Both kinds of message have a common interface, representing the headers and content of the message.
Not all message types use all the fields.
The subject attribute is
a DOMString that represents the message's
subject.
The to, from, cc, and bcc fields represent the concepts with
the same names. They are all of type ContactList, readonly. The way to add
or remove contacts is to call the add() and
remove() methods on the lists.
The attachments
attribute, of type AttachmentList, readonly, is a list
of the current contents of the message. This interface is defined
below.
The content attribute is
a shorthand for accessing the first text/plain
attachment's text attribute. On setting, if there is
no such attachment, one is created (with the given content) and
appended. On getting, if there is no such attachment,
null is returned.
interface AttachmentList {
Attachment item(in unsigned long index);
readonly attribute unsigned long length;
Attachment insert(in unsigned long index);
Attachment append();
void remove(in unsigned long index);
}
The attachments model in the Opera Platform consists of an ordered list of objects that can hold any resource.
The AttachmentList
interface thus implements a straight-forward ordered list
interface. The length attribute gives the number of
attachments in the list, the item() method gives
access to individual attachments (returning null if
the argument is out of range). The insert() method
inserts an attachment at the specified index, pushing all
attachments that had an index equal to or greater than that index
up one, and returns the new attachment. If the argument is
greater than length, this simply calls
append(), ignoring the exact value of the arguemnt.
The append() method is equivalent to calling
insert() with the length argument as
the index. Finally, the remove() method removes the
specified attachment from the list, discarding it and moving any
attachments with indexes greater than the specified index down by
one.
interface Attachment {
attribute DOMString type;
attribute Image image;
attribute Document document;
attribute DOMString text;
attribute DOMString uri;
}
Attachments are all represented by the same interface, regardless of what type of data they contain.
Initially, an attachment will be empty. All its fields will be
null.
The type attribute contains the type of the
attachment, the other attributes represent the current state of
the attachment. Attributes that do not apply to the current
content of the attachment have the value null.
The values of the attributes thus depend on the
type attribute, as follows:
type |
image/svg+xml |
image/* |
text/html, text/xml,
application/xml, */*+xml |
text/* |
other |
|---|---|---|---|---|---|
image |
The image | The image | null |
null |
null |
document |
The document node | null |
The document node | null |
null |
text |
A textual representation of the document | null |
A textual representation of the document | The text | null |
uri |
The URI to the attachment, if known,
otherwise a data: URI representing the
resource |
||||
For XML and HTML documents, the textual representation is a
serialisation of the Document node (including
markup, etc).
On setting, the attributes work as follows, except if the new
value exactly matches the old value (tested via pointer
comparison for images and documents, and via string comparison
for the type, text and uri
attributes), in which case no change occurs:
Current type |
image/* |
text/html, text/xml,
application/xml, */*+xml |
text/* |
other |
|---|---|---|---|---|
New type |
Ignored. | If new type is text/plain,
document is set to null but
text preserves its value. Otherwise, change is
ignored. |
type is set to the new value,
other attributes do not change. |
|
image |
image is set to the new value,
URI is reset, type is set appropriately. |
|||
document |
document is set to the new
value, URI is reset, type is set
appropriately. |
|||
text |
text is set to the new value,
URI is reset, type is set appropriately. |
|||
uri |
The specified URI is downloaded,
type is set to the resource's Content-Type (or
equivalent for non-HTTP URIs), and if the type is an image,
a document, or a text file, the appropriate attribute is
initialised to the relevant value too. |
|||
Using the createMessage() method, a new message
can be created, e.g. for subsequently sending it to a
contact.
interface DraftMessage : AbstractMessage { CompleteMessage send(in DOMString method [delete]); }
The only method on this interface sends the message using the
specified method, and returns null on failure, or
the resulting complete message on success. (The original draft
message is left unchanged and can be used for sending further
messages.) The message may be copied to the Outbox or Sent
message boxes. A future version of this specification may define
this in more detail.
The valid method types are described in the
section on Messaging
Methods.
An optional postfix string delete may be appended
to any given messaging method, to immediately delete the message
after sending. This postfix must consist of exactly one space,
and the word "delete".
interface CompleteMessage : AbstractMessage { attribute boolean read; readonly attribute DOMString method; readonly attribute DOMTimeStamp timestamp; readonly attribute MessageBox messageBox Application launchApplication(); }
The read attribute specifies
whether the message should be marked as viewed by the user or
not. The method attribute specifies the type of
message represented by the object (e.g. sms). The
possible method types are described in the section
on Messaging Methods.
The timestamp attribute
shall return the time at which the message was received (for
incoming messages) or sent (for outgoing messages). If the
message has an explicit time associated with it (e.g. e-mails
have a Date: field) then that
must be returned instead.
The messageBox
attribute, if not null, represents the message box
in which the message is stored.
interface MessageStore {
readonly attribute MessageBox inbox;
readonly attribute MessageBox outbox;
readonly attribute unsigned long length;
MessageBox item(in unsigned long index);
MessageBox namedItem(in DOMString name);
};
interface MessageBox {
readonly attribute DOMString name;
readonly attribute unsigned long read;
readonly attribute unsigned long unread;
readonly attribute unsigned long length;
AbstractMessage item(in unsigned long index);
};
An object implementing the MessageStore interface is obtained via
the messages attribute on
the device object. It provides
the usual enumerated and named access to all the message boxes
provided by the operating system, for example the Inbox, Drafts,
Outbox, Sent, and IMAP folders seen on typical phones.
The namedItem() method allows access by name, and
the item() method allows access by integer. If the
argument passed to namedItem() does not match any of
the available message boxes' names, or if the index passed to
item() is less than zero or greater than or equal to
the value of the length attribute (which returns the
number of items in the list), then the return value should be
null.
In the ECMAScript binding, objects implementing this interface
can also be dereferenced using square bracket notation (e.g.
messages[1] or messages["IMAP"]).
Dereferencing with an integer index is equivalent to invoking the
item() method with that index, and dereferencing
with a string index is equivalent to invoking the
namedItem() method with that index.
The order of message boxes in the message store is arbitrary, but should be well-defined. It is recommended that it be either alphabetical or in the same order as provided by the OS.
In addition, two attributes inbox and outbox provide direct access to the
Inbox (initial message box for new SMS messages) and Outbox
(initial location of outgoing messages) respectively,
independently of the names of these message boxes.
The MessageBox
interface is another list interface, with the usual semantics for
the item() and length members and the
same dereferencing behaviour in ECMAScript.
The read and unread attributes give convenient
access to the count of read and unread messages in the message
box.
interface MessageEvent : Event {
readonly attribute CompleteMessage message;
void initMessageEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in CompleteMessage messageArg);
// For DOM Level 3 support
void initMessageEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in CompleteMessage messageArg);
}
There are several message events. They are all dispatched on
the device object.
The newMessage event,
with namespace http://www.opera.com/opera-platform,
which does not bubble, is not cancellable, has no default action,
and uses the MessageEvent interface to store
context information, is fired whenever an incoming message
arrives.
The message attribute of the event contains a
reference to the new message.
The messagesChanged event, with
namespace http://www.opera.com/opera-platform, which
does not bubble, is not cancellable, has no default action, and
has no context information, is fired whenever the total number of
messages, or the number of read or unread messages, changes, or
when a message box is added or removed. The event is fired on the
device object. There is no way
to tell which message box changed, applications are expected to
check all the message boxes in the message store.
The Opera Platform does not provide direct access to the telephony APIs, as most devices are designed to handle such features in a failsafe manner which would preclude the Opera Platform system from reliably taking control of them. However, an event is provided to handle missed calls.
Contacts can be called by using the call() method.
Incoming calls are not handled by the Opera Platform. When an incoming call arrives, the Opera Platform process yields to the OS native phone application.
interface MissedCallList {
readonly attribute unsigned long length;
MissedCall item(in unsigned long index);
};
interface MissedCall {
readonly attribute Contact contact;
readonly attribute DOMTimeStamp timestamp;
readonly attribute DOMString address;
void returnCall();
};
Missed calls are stored in the missedCalls attribute, in
arrival order (most recent first).
The contact attribute of
the MissedCall interface
used to represent missed calls contains a reference to the
contact who initiated the call. If the call came from an unknown
source, it will be an orphan contact (one that can't be found in
the contacts ContactList) with only one address
with the method name telephone, with a name equal to
the value of that address, and with the contactList attribute set to
null.
The timestame attribute is set to the
time of the missed call. The address
attribute is the number from which the call originated.
The returnCall()
method causes the call to be returned on the number that
initiated the call. If the contact only has one telephone number,
this is equivalent to calling the call() method on the contact attribute.
interface TelephonyEvent : Event {
readonly attribute MissedCall missedCall;
void initTelephonyEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Contact contactArg);
// For DOM Level 3 support
void initTelephonyEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Contact contactArg);
}
The missedCall event,
with namespace http://www.opera.com/opera-platform,
which does not bubble, is not cancellable, has no default action,
and uses the TelephonyEvent interface to store
context information, is fired whenever an incoming call was
missed.
The missedCall attribute points to an
instance of the MissedCall interface, which shall also
be the 0th entry in the missedCalls list at the time of the
event being fired.
typedef Channel DOMStringList;
interface ChannelList {
Channel item(in unsigned long index);
};
Cell Broadcast Center (CBC) and Unstructured Supplementary
Services Data (USSD) are systems that can be used for broadcast
and push messages. The broadcastMessages
attribute contains the list of recent messages from all
subscribed channels, ordered in arrival order with the most
recent messages first.
The setChannelFilterList()
method is used to define the currently subscribed channels. It
takes zero or more integer arguments, which are then set as the
subscribed channels.
The broadcastChannels list can
then be used to obtain the messages from a specific channel,
using the channel ID as the index. Channels contain the messages
recently received on that channel, in arrival order, most recent
first.
When a new message arrives, the receivedBroadcastMessage
event is fired on the device
object.
The receivedBroadcastMessage
event has the namespace
http://www.opera.com/opera-platform, does not
bubble, is not cancellable, and has no default action. It has no
context information, and thus uses the normal Event
interface.
In this version of the Opera Platform only the list of events is exposed. A future version of this specification may provide more detailed access to the system calendar.
interface Calendar {
readonly attribute CalendarEvent nextEvent;
readonly attribute unsigned long length;
Calendar item(in unsigned long index);
}
The nextEvent attribute
of the Calendar interface
(accessible via the calendar attribute of the
device object) returns the
next pending event in the calendar. If there are no pending
events it returns null.
The calendar object
itself is a list of all the calendar events, in date
order.
In the ECMAScript binding, objects implementing this interface
can also be dereferenced using square bracket notation (e.g.
calendar[1]). Dereferencing with an integer index is
equivalent to invoking the item() method with that
index.
interface CalendarEvent {
readonly attribute DOMString title;
readonly attribute DOMTimeStamp date;
Application launchApplication();
}
The CalendarEvent
interface has two attributes; title is a string representing the
event's title, and date is the
starting date and time of the event.
To give the user access to the calendar, either the
launchCalendar() method should be called on the
device object (to show the
application normally) or the launchApplication()
method should be called on a CalendarEvent object (to start the
application with a particular event selected).
The ToDoList and
ToDoItem interfaces and
provide access to the system To Do list.
interface ToDoList {
readonly attribute unsigned long length;
ToDoItem item(in unsigned long index);
ToDoItem add();
void remove(in ToDoItem item);
};
interface ToDoItem {
attribute DOMString name;
attribute DOMString priority;
attribute boolean done;
attribute DOMTimeStamp dateAdded;
attribute DOMTimeStamp deadline;
};
The add() method adds a new item at the end of
the list and returns it. The new item is initialised with a blank
name and priority, done
set to false, dateAdded set to the current time, and
deadline set to zero (1970-01-01 00:00:00.0
UTC).
When the deadline attribute is set to zero
(1970-01-01 00:00:00.0 UTC) it means there is no deadline.
The priority attribute is a string whose allowed
values are system-dependent. If it is set to a value the system
does not allow, it shall be silently ignored.
Removing an item with remove() renumbers all
subsequent items. Passing null to
remove() raises an appropriate exception.
For geeks, the system
attribute provides an object that lets script see the status of
the disk and of memory.
interface System {
readonly attribute DriveList drives;
readonly attribute unsigned long long totalDiskSpace;
readonly attribute unsigned long long freeDiskSpace;
readonly attribute unsigned long long totalMemory;
readonly attribute unsigned long long freeMemory;
};
interface DriveList {
readonly attribute int length;
Drive item(in int index);
};
interface Drive {
readonly attribute DOMString name; // mount point, drive letter, or similar
readonly attribute DOMString uri; // e.g. "file:///mnt/flash/" or "file:///C|/"
readonly attribute unsigned long long totalDiskSpace;
readonly attribute unsigned long long freeDiskSpace;
};
On systems that cannot return the relevant information, a
NOT_SUPPORTED_ERR exception shall be raised when
they are accessed.
The uri attribute returns a URI that, if invoked
somehow, will display the drive contents.
The applications
attribute returns a list of applications that are available on
the system.
interface ApplicationList {
readonly attribute int length;
ApplicationDescription item(in int index);
}
interface ApplicationDescription {
readonly attribute DOMString name;
readonly attribute DOMString description;
readonly attribute HTMLImageElement icon;
readonly attribute DOMString id;
readonly attribute DOMString path;
void launchApplication();
}
Each application has a name (e.g. "Opera"), a
description (e.g. "Web Browser"), and an icon,
obtained from the OS.
Each application also may also have an id and a
path, depending on the OS. These may be used with
the launchAppById() and
launchAppByName()
methods respectively.
The various launchXXXX methods act as their names
imply. On the device object
they launch the applications normally, on the more specific
interfaces they launch the applications with the arguments
appropriate to starting them already displaying the appropriate
data.
The launchURI() method
launches a URI in the platform's default browser. What is
considered to be the default browser is platform dependant and
may be user configurable. The URI may also be opened in the same
browser instance as the one hosting the document that called the
method in the first place, in which case the URI shallll be
opened in a seperate window. The application or window that is
opened to display the URI shall be given focus.
The launchAppById()
method launches the application specified by the argument. The
argument must be an ID. The exact format of application IDs
depends on the platform. Symbian, for instance, uses GUIDs to
identify applications.
The launchAppByName() method
launches the application specified by the argument. The argument
must be the path to an application. The exact format of
application paths depends on the platform.
interface Application {
readonly attribute DOMString name;
void focus();
void blur();
}
The Application
interface merely provides a way to send the focus to and from
other applications that were launched through the various
application launching methods.
The getDeviceSpecificString()
method shall return device-specific values for the provided
device-specific key.
The resetAPN method shall, in case connection to a specified access point, either because the access point is invalid, or for some other reason fails, reset Opera Platform's default access point, to allow a user to select a new access point/connection. This method takes no arguments, and returns void.
This specification is designed to leverage existing standards, only providing interfaces for functionality not covered by existing specifications.
The CSS2 System Colors (defined in [CSS21]) are to be implemented so that they reflect the appropriate OS colors.
The Opera Platform includes the DOM Level 3
Keyboard Events by reference. (See [DOM3EVENT].) In particular, a pair of
keydown and keyup events should be
produced when the phone's keys are pressed. The following keys
are typically available on devices:
Other devices may have other keys. Implementors should
contact the editor before deciding what keys that are not
mentioned above map to. Authors should not rely on key
identifiers other than those listed above. In general, it is
highly recommended that the
Text Events be used instead. The key events described above
should only really be used for catching keys such as the left and
right menu selection keys (LaunchApplication1 and
LaunchApplication2).
The keyup and keydown events are
dispatched on the focussed element, or, if there is none, the
document node. (Since the events bubble, all keys that are not
handled by the focussed element will arrive at the document
node.)
The host application may provide caching features above and
beyond those specified in the HTTP specification. For example, a
never-flush directive. For more details, see the
platform's feature specification. (For example, section 7.14 of
the Browser Core 2.0 for S60, S80, S90: Opera Engine
Functional Specification.)
This was originally based on the interfaces described in [WAPWTAI].