- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 19 Jan 2011 17:11:35 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/messaging
In directory hutz:/tmp/cvs-serv24199
Added Files:
WD2.html
Log Message:
first pass
--- NEW FILE: WD2.html ---
<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
<html lang="en" dir="ltr">
<head>
<title>The Messaging API</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<!-- <script type="text/javascript" src='http://dev.w3.org/2009/dap/ReSpec.js/js/sh_main.min.js' class='remove'> </script> -->
<style type="text/css">
/*****************************************************************
* ReSpec CSS
* Robin Berjon (robin at berjon dot com)
* v0.05 - 2009-07-31
*****************************************************************/
/* --- INLINES --- */
em.rfc2119 {
text-transform: lowercase;
font-variant: small-caps;
font-style: normal;
color: #900;
}
h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
border: none;
}
dfn {
font-weight: bold;
}
a.internalDFN {
color: inherit;
border-bottom: medium solid #99c;
text-decoration: none;
}
a.externalDFN {
color: inherit;
border-bottom: medium dotted #ccc;
text-decoration: none;
}
a.bibref {
text-decoration: none;
}
code {
color: #ff4500;
}
/* --- WEB IDL --- */
pre.idl {
border-top: 1px solid #90b8de;
border-bottom: 1px solid #90b8de;
padding: 1em;
line-height: 120%;
}
pre.idl::before {
content: "WebIDL";
display: block;
width: 150px;
background: #90b8de;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
.idlType {
color: #ff4500;
font-weight: bold;
text-decoration: none;
}
/*.idlModule*/
/*.idlModuleID*/
/*.idlInterface*/
.idlInterfaceID {
font-weight: bold;
color: #005a9c;
}
.idlSuperclass {
font-style: italic;
color: #005a9c;
}
/*.idlAttribute*/
.idlAttrType, .idlFieldType {
color: #005a9c;
}
.idlAttrName, .idlFieldName {
color: #ff4500;
}
.idlAttrName a, .idlFieldName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlMethod*/
.idlMethType {
color: #005a9c;
}
.idlMethName {
color: #ff4500;
}
.idlMethName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlParam*/
.idlParamType {
color: #005a9c;
}
.idlParamName {
font-style: italic;
}
.extAttr {
color: #666;
}
/*.idlConst*/
.idlConstType {
color: #005a9c;
}
.idlConstName {
color: #ff4500;
}
.idlConstName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlException*/
.idlExceptionID {
font-weight: bold;
color: #c00;
}
.idlTypedefID, .idlTypedefType {
color: #005a9c;
}
.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
color: #c00;
font-weight: normal;
}
.excName a {
font-family: monospace;
}
.idlRaises a.idlType, .excName a.idlType {
border-bottom: 1px dotted #c00;
}
.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
width: 45px;
text-align: center;
}
.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
.idlImplements a {
font-weight: bold;
}
dl.attributes, dl.methods, dl.constants, dl.fields {
margin-left: 2em;
}
.attributes dt, .methods dt, .constants dt, .fields dt {
font-weight: normal;
}
.attributes dt code, .methods dt code, .constants dt code, .fields dt code {
font-weight: bold;
color: #000;
font-family: monospace;
}
.attributes dt code, .fields dt code {
background: #ffffd2;
}
.attributes dt .idlAttrType code, .fields dt .idlFieldType code {
color: #005a9c;
background: transparent;
font-family: inherit;
font-weight: normal;
font-style: italic;
}
.methods dt code {
background: #d9e6f8;
}
.constants dt code {
background: #ddffd2;
}
.attributes dd, .methods dd, .constants dd, .fields dd {
margin-bottom: 1em;
}
table.parameters, table.exceptions {
border-spacing: 0;
border-collapse: collapse;
margin: 0.5em 0;
width: 100%;
}
table.parameters { border-bottom: 1px solid #90b8de; }
table.exceptions { border-bottom: 1px solid #deb890; }
.parameters th, .exceptions th {
color: #fff;
padding: 3px 5px;
text-align: left;
font-family: initial;
font-weight: normal;
text-shadow: #666 1px 1px 0;
}
.parameters th { background: #90b8de; }
.exceptions th { background: #deb890; }
.parameters td, .exceptions td {
padding: 3px 10px;
border-top: 1px solid #ddd;
vertical-align: top;
}
.parameters tr:first-child td, .exceptions tr:first-child td {
border-top: none;
}
.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
width: 100px;
}
.parameters td.prmType {
width: 120px;
}
table.exceptions table {
border-spacing: 0;
border-collapse: collapse;
width: 100%;
}
/* --- TOC --- */
.toc a {
text-decoration: none;
}
a .secno {
color: #000;
}
/* --- TABLE --- */
table.simple {
border-spacing: 0;
border-collapse: collapse;
border-bottom: 3px solid #005a9c;
}
.simple th {
background: #005a9c;
color: #fff;
padding: 3px 5px;
text-align: left;
}
.simple th[scope="row"] {
background: inherit;
color: inherit;
border-top: 1px solid #ddd;
}
.simple td {
padding: 3px 10px;
border-top: 1px solid #ddd;
}
.simple tr:nth-child(even) {
background: #f0f6ff;
}
/* --- DL --- */
.section dd > p:first-child {
margin-top: 0;
}
.section dd > p:last-child {
margin-bottom: 0;
}
.section dd {
margin-bottom: 1em;
}
.section dl.attrs dd, .section dl.eldef dd {
margin-bottom: 0;
}
/* --- EXAMPLES --- */
pre.example {
border-top: 1px solid #ff4500;
border-bottom: 1px solid #ff4500;
padding: 1em;
margin-top: 1em;
}
pre.example::before {
content: "Example";
display: block;
width: 150px;
background: #ff4500;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
/* --- EDITORIAL NOTES --- */
.issue {
padding: 1em;
margin: 1em 0em 0em;
border: 1px solid #f00;
background: #ffc;
}
.issue::before {
content: "Issue";
display: block;
width: 150px;
margin: -1.5em 0 0.5em 0;
font-weight: bold;
border: 1px solid #f00;
background: #fff;
padding: 3px 1em;
}
.note {
margin: 1em 0em 0em;
padding: 1em;
border: 2px solid #cff6d9;
background: #e2fff0;
}
.note::before {
content: "Note";
display: block;
width: 150px;
margin: -1.5em 0 0.5em 0;
font-weight: bold;
border: 1px solid #cff6d9;
background: #fff;
padding: 3px 1em;
}
/* --- Best Practices --- */
div.practice {
border: solid #bebebe 1px;
margin: 2em 1em 1em 2em;
}
span.practicelab {
margin: 1.5em 0.5em 1em 1em;
font-weight: bold;
font-style: italic;
}
span.practicelab { background: #dfffff; }
span.practicelab {
position: relative;
padding: 0 0.5em;
top: -1.5em;
}
p.practicedesc {
margin: 1.5em 0.5em 1em 1em;
}
@media screen {
p.practicedesc {
position: relative;
top: -2em;
padding: 0;
margin: 1.5em 0.5em -1em 1em;
}
/* --- SYNTAX HIGHLIGHTING --- */
pre.sh_sourceCode {
background-color: white;
color: black;
font-style: normal;
font-weight: normal;
}
pre.sh_sourceCode .sh_keyword { color: #005a9c; font-weight: bold; } /* language keywords */
pre.sh_sourceCode .sh_type { color: #666; } /* basic types */
pre.sh_sourceCode .sh_usertype { color: teal; } /* user defined types */
pre.sh_sourceCode .sh_string { color: red; font-family: monospace; } /* strings and chars */
pre.sh_sourceCode .sh_regexp { color: orange; font-family: monospace; } /* regular expressions */
pre.sh_sourceCode .sh_specialchar { color: #ffc0cb; font-family: monospace; } /* e.g., \n, \t, \\ */
pre.sh_sourceCode .sh_comment { color: #A52A2A; font-style: italic; } /* comments */
pre.sh_sourceCode .sh_number { color: purple; } /* literal numbers */
pre.sh_sourceCode .sh_preproc { color: #00008B; font-weight: bold; } /* e.g., #include, import */
pre.sh_sourceCode .sh_symbol { color: blue; } /* e.g., *, + */
pre.sh_sourceCode .sh_function { color: black; font-weight: bold; } /* function calls and declarations */
pre.sh_sourceCode .sh_cbracket { color: red; } /* block brackets (e.g., {, }) */
pre.sh_sourceCode .sh_todo { font-weight: bold; background-color: #00FFFF; } /* TODO and FIXME */
/* Predefined variables and functions (for instance glsl) */
pre.sh_sourceCode .sh_predef_var { color: #00008B; }
pre.sh_sourceCode .sh_predef_func { color: #00008B; font-weight: bold; }
/* for OOP */
pre.sh_sourceCode .sh_classname { color: teal; }
/* line numbers (not yet implemented) */
pre.sh_sourceCode .sh_linenum { display: none; }
/* Internet related */
pre.sh_sourceCode .sh_url { color: blue; text-decoration: underline; font-family: monospace; }
/* for ChangeLog and Log files */
pre.sh_sourceCode .sh_date { color: blue; font-weight: bold; }
pre.sh_sourceCode .sh_time, pre.sh_sourceCode .sh_file { color: #00008B; font-weight: bold; }
pre.sh_sourceCode .sh_ip, pre.sh_sourceCode .sh_name { color: #006400; }
/* for Prolog, Perl... */
pre.sh_sourceCode .sh_variable { color: #006400; }
/* for LaTeX */
pre.sh_sourceCode .sh_italics { color: #006400; font-style: italic; }
pre.sh_sourceCode .sh_bold { color: #006400; font-weight: bold; }
pre.sh_sourceCode .sh_underline { color: #006400; text-decoration: underline; }
pre.sh_sourceCode .sh_fixed { color: green; font-family: monospace; }
pre.sh_sourceCode .sh_argument { color: #006400; }
pre.sh_sourceCode .sh_optionalargument { color: purple; }
pre.sh_sourceCode .sh_math { color: orange; }
pre.sh_sourceCode .sh_bibtex { color: blue; }
/* for diffs */
pre.sh_sourceCode .sh_oldfile { color: orange; }
pre.sh_sourceCode .sh_newfile { color: #006400; }
pre.sh_sourceCode .sh_difflines { color: blue; }
/* for css */
pre.sh_sourceCode .sh_selector { color: purple; }
pre.sh_sourceCode .sh_property { color: blue; }
pre.sh_sourceCode .sh_value { color: #006400; font-style: italic; }
/* other */
pre.sh_sourceCode .sh_section { color: black; font-weight: bold; }
pre.sh_sourceCode .sh_paren { color: red; }
pre.sh_sourceCode .sh_attribute { color: #006400; }
</style><link charset="utf-8" type="text/css" rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD"></head><body style="display: inherit;"><div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p><h1 class="title" id="title">The Messaging API</h1><h2 id="w3c-working-draft-20-january-2011">W3C Working Draft 20 January 2011</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-messaging-api-20110120/">http://www.w3.org/TR/2011/WD-messaging-api-20110120/</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/messaging-api/">http://www.w3.org/TR/messaging-api/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2009/dap/messaging/">http://dev.w3.org/2009/dap/messaging/</a></dd><dt>Previous version:</dt><dd><a href="http://www.w3.org/TR/2010/WD-messaging-api-20100810/">http://www.w3.org/TR/2010/WD-messaging-api-20100810/</a></dd><dt>Editors:</dt><dd><span>Suresh Chittur</span>, Research in Motion (RIM)</dd>
<dd><span>Daniel Coloma</span>, Telefonica</dd>
<dd><span>Max Froumentin</span>, Opera</dd>
<dd><span>Maria Angeles Oteo</span>, Telefonica</dd>
<dd><span>Niklas Widell</span>, Ericsson AB</dd>
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
<div class="introductory section" id="abstract"><h2>Abstract</h2>
<p>
This specification defines an API that provides access to messaging functionality in the device, including SMS, MMS and e-mail.
</p>
</div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>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 <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p><p>This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs and Policy Working Group</a> as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to <a href="mailto:public-device-apis@w3.org">public-device-apis@w3.org</a> (<a href="mailto:public-device-apis-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-device-apis/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement bythe 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.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/43696/status" rel="disclosure">public list of any patent disclosures</a> 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 <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p></div><div class="section" id="toc"><h2 class="introdutory">Table of Contents</h2><ul class="toc"><li class="tocline"><a class="tocxref" href="#conformance"><span class="secno">1. </span>Conformance</a></li><li class="tocline"><a class="tocxref" href="#intro"><span class="secno">2. </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#security-considerations"><span class="secno">3. </span>Security Considerations</a></li><li class="tocline"><a class="tocxref" href="#supported-messaging-types"><span class="secno">4. </span>Supported messaging types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#sms-specific-concerns"><span class="secno">4.1 </span>SMS specific concerns</a></li></ul></li><li class="tocline"><a class="tocxref" href="#api-description"><span class="secno">5. </span>API Description</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#devicemessaging"><span class="secno">5.1 </span> <span class="idlType formerLink idlType"><code>DeviceMessaging</code></span> </a><ul class="toc"><li class="tocline"><a cass="tocxref" href="#attributes"><span class="secno">5.1.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#messagingmanager"><span class="secno">5.2 </span><span class="idlType formerLink idlType"><code>MessagingManager</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#methods"><span class="secno">5.2.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#smsmessage"><span class="secno">5.3 </span><span class="idlType formerLink idlType"><code>SMSMessage</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-1"><span class="secno">5.3.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-1"><span class="secno">5.3.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#mmsmessage"><span class="secno">5.4 </span><span class="idlType formerLink idlType"><code>MMSMessage</code></span></a><ul class="toc"><li class="tocline"><a class="tocref" href="#attributes-2"><span class="secno">5.4.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-2"><span class="secno">5.4.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#emailmessage"><span class="secno">5.5 </span><span class="idlType formerLink idlType"><code>EmailMessage</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-3"><span class="secno">5.5.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-3"><span class="secno">5.5.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#smsproperties"><span class="secno">5.6 </span><span class="idlType formerLink idlType"><code>SMSProperties</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-4"><span class="secno">5.6.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#mmsproperties"><span class="secno">5.7 </span><span class="idlype formerLink idlType"><code>MMSProperties</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-5"><span class="secno">5.7.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#emailproperties"><span class="secno">5.8 </span><span class="idlType formerLink idlType"><code>EmailProperties</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-6"><span class="secno">5.8.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#emailaddress"><span class="secno">5.9 </span><span class="idlType formerLink idlType"><code>EmailAddress</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-7"><span class="secno">5.9.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#messagingsuccesscb"><span class="secno">5.10 </span><span class="idlType formerLink idlType"><code>MessagingSuccessCB</code></span></a><ul class="toc"><li clas="tocline"><a class="tocxref" href="#methods-4"><span class="secno">5.10.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#messagingerrorcb"><span class="secno">5.11 </span><span class="idlType formerLink idlType"><code>MessagingErrorCB</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#methods-5"><span class="secno">5.11.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#messagingerror"><span class="secno">5.12 </span><span class="idlType formerLink idlType"><code>MessagingError</code></span></a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-8"><span class="secno">5.12.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#constants"><span class="secno">5.12.2 </span>Constants</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#features-for-future-consideration"><span class="secno">A. </span>Features for Future Consideration</a></li><li class="tocline">a class="tocxref" href="#acknowledgements"><span class="secno">B. </span>Acknowledgements</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">C. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">C.1 </span>Normative references</a></li><li class="tocline"><a class="tocxref" href="#informative-references"><span class="secno">C.2 </span>Informative references</a></li></ul></li></ul></div>
<div class="section" id="conformance"><!--OddPage--><h2><span class="secno">1. </span>Conformance</h2><p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p>
<p>The key words <em title="must" class="rfc2119">must</em>, <em title="must not" class="rfc2119">must not</em>, <em title="required" class="rfc2119">required</em>, <em title="should" class="rfc2119">should</em>, <em title="should not" class="rfc2119">should not</em>, <em title="recommended" class="rfc2119">recommended</em>, <em title="may" class="rfc2119">may</em>, and <em title="optional" class="rfc2119">optional</em> in this specification are to be interpreted as described in [<cite><a href="#bib-RFC2119" rel="biblioentry" class="bibref">RFC2119</a></cite>].</p>
</div>
<p>
This specification defines conformance criteria that apply to a single product:
<dfn id="dfn-user-agents">
user agents
</dfn>
that implement the interfaces that it contains.
</p>
<p class="note">
Since not all devices will have all messaging functionality (e.g. a phone may have only SMS and MMS while a PC may have only e-mail) there is a need to indicate that conformant implementations need only expose available functionality.
</p>
<p>Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [<cite><a href="#bib-WEBIDL" rel="biblioentry" class="bibref">WEBIDL</a></cite>], as this specification uses that specification's terminology.</p>
<div class="informative section" id="intro">
<!--OddPage--><h2><span class="secno">2. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
<p>
The Messaging API defines a high-level interface to messaging functionality,
including SMS, MMS and e-mail. It includes APIs to create and send messages.
</p>
<p>These APIs complement what <code>sms:</code>, <code>mms:</code>, and <code>mailto:</code> URI schemes provide with:</p>
<ul>
<li>the possibility to attach files to messages,</li>
<li>a callback on success / error when a message is sent.</li>
</ul>
<p>The following code extracts illustrate how to create and send messages. </p>
<div> <p>
Sending an SMS, if device supports it.
</p> </div>
<pre class="example sh_javascript_dom sh_sourceCode"><span class="sh_keyword">function</span> <span class="sh_function">successCB</span><span class="sh_symbol">()</span> <span class="sh_cbracket">{</span>
<span class="sh_predef_func">alert</span><span class="sh_symbol">(</span><span class="sh_string">"The Message has been sent successfully"</span><span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span>
<span class="sh_keyword">function</span> <span class="sh_function">errorCB</span><span class="sh_symbol">(</span>error<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_predef_func">alert</span><span class="sh_symbol">(</span><span class="sh_string">"The Message could not be sent "</span> <span class="sh_symbol">+</span> error<span class="sh_symbol">.</span>code<span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span>
<span class="sh_keyword">if</span> <span class="sh_symbol">(</span><span class="sh_predef_var">navigator</span><span class="sh_symbol">.</span>device<span class="sh_symbol">.</span>messaging<span class="sh_symbol">.</span>createSMS<span class="sh_symbol">)</span>
<span class="sh_predef_var">navigator</span><span class="sh_symbol">.</span>device<span class="sh_symbol">.</span>messaging<span class="sh_symbol">.</span><span class="sh_function">createSMS</span><span class="sh_symbol">(</span><span class="sh_cbracket">{</span>to<span class="sh_symbol">:</span> <span class="sh_symbol">[</span><span class="sh_cbracket">{</span><span class="sh_string">'+460000000001'</span><span class="sh_cbracket">}</span><span class="sh_symbol">],</span> body<span class="sh_symbol">:</span>
<span class="sh_string">"Welcome to Atlantis"</span><span class="sh_cbracket">}</span><span class="sh_symbol">).</span><span class="sh_function">send</span><span class="sh_symbol">(</span>successCB<span class="sh_symbol">,</span> errorCB<span class="sh_symbol">);</span></pre>
</div>
<div class="section" id="security-considerations">
<!--OddPage--><h2><span class="secno">3. </span>Security Considerations</h2>
<p>
The API defined in this specification can be used to create and send messages through different technologies.
Sending messages usually has an associated cost (especially SMSs and MMSs), hence a conforming implementation of this specification
should provide a mechanism that ensures that no message is sent without the user's consent.
</p>
<p>
The methods for sending messages that require user's express permission to be accessed are: <code>SMSMessage.send()</code>, <code>MMSMessage.send()</code> and <code>EmailMessage.send()</code>.
</p>
<p>Since the implications of sending a given message may depend on the message attributes (e.g. destination address) and content, the approach used to ensure user’s consent should include the relevant information, typically the type of message and its destination address.</p>
<p>A typical (but not required) way of ensuring user’s consent would be to use the same mechanism as the one used when the user click on a link using one the relevant URI schemes, for instance, bringing up the platform messaging application with pre-filled fields.</p>
<p>In general, user’s consent is expected to be confirmed for each invocation of the <code>send</code> methods.</p>
</div>
<div class="section" id="supported-messaging-types">
<!--OddPage--><h2><span class="secno">4. </span>Supported messaging types</h2>
<p>
The specification supports three kinds of messages: SMS, MMS and e-mail. For each of them specific interfaces and data types have been defined and they will be detailed in the following section. The table below summarizes the attributes that are supported for each given message type.
</p>
<table class="simple">
<thead>
<tr>
<th>Attribute</th>
<th>SMS</th>
<th>MMS</th>
<th>e-mail</th>
</tr>
</thead>
<tbody>
<tr>
<th><code>sentTime</code></th>
<td title="supported">✓</td>
<td title="supported">✓</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>to</code></th>
<td title="supported">✓</td>
<td title="supported">✓</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>cc</code></th>
<td title="not available">N/A</td>
<td title="not available">N/A</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>bcc</code></th>
<td title="not available">N/A</td>
<td title="not available">N/A</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>subject</code></th>
<td title="not available">N/A</td>
<td title="supported">✓</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>body</code></th>
<td title="supported">✓</td>
<td title="supported">✓</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>attachments</code></th>
<td title="not available">N/A</td>
<td title="supported">✓</td>
<td title="supported">✓</td>
</tr>
<tr>
<th><code>priority</code></th>
<td title="not available">N/A</td>
<td title="not available">N/A</td>
<td title="supported">✓</td>
</tr>
</tbody></table>
<div class="section" id="sms-specific-concerns">
<h3><span class="secno">4.1 </span>SMS specific concerns</h3>
<p>
Note that there are size limitations for SMSs sent on a network (the actual maximum size depends on language encoding the content). When an SMS exceeds the maximum size the device may divide the SMS into several parts. This means that one SMS object may lead to sending several ones to the network (if the platform supports multi-part SMSs).
</p>
</div>
</div>
<div class="section" id="api-description">
<!--OddPage--><h2><span class="secno">5. </span>API Description</h2>
<div class="section" id="devicemessaging">
<h3><span class="secno">5.1 </span> <a class="idlType" href="#idl-def-DeviceMessaging"><code>DeviceMessaging</code></a> </h3>
<p>
The <a href="#devicemessaging">DeviceMessaging</a> object is exposed on the <code>navigator.device</code> object, as defined in [<cite><a href="#bib-CORE-DEVICE" rel="biblioentry" class="bibref">CORE-DEVICE</a></cite>].
</p>
<pre class="idl"><span class="idlImplements"><a>Device</a> implements <a class="idlType" href="#idl-def-DeviceMessaging"><code>DeviceMessaging</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>Device</a></code> type are defined to also implement the <a class="idlType" href="#idl-def-DeviceMessaging"><code>DeviceMessaging</code></a> interface.</p></div>
<pre class="idl"><span class="idlInterface" id="idl-def-DeviceMessaging">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">DeviceMessaging</span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MessagingManager"><code>MessagingManager</code></a></span> <span class="idlAttrName"><a href="#widl-DeviceMessaging-messaging">messaging</a></span>;</span>
};</span>
</pre><div class="section" id="attributes"><h4><span class="secno">5.1.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-DeviceMessaging-messaging"><code>messaging</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MessagingManager"><code>MessagingManager</code></a></span>, readonly</dt><dd>
The object from which the messaging functionality can be accessed.
<div><em>No exceptions.</em></div></dd></dl></div>
</div>
<div class="section" id="messagingmanager">
<h3><span class="secno">5.2 </span><a class="idlType" href="#idl-def-MessagingManager"><code>MessagingManager</code></a></h3>
<p>
This interface provides the general functionality that relates to messaging as well as the entry point for message creation and sending.
</p>
<p class="issue">The Working Group plans in reworking this interface to rely more directly on URI schemes rather than having a per messaging protocol method.</p>
<pre class="idl"><span class="idlInterface" id="idl-def-MessagingManager">interface <span class="idlInterfaceID">MessagingManager</span> {
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-SMSMessage"><code>SMSMessage</code></a></span> <span class="idlMethName"><a href="#widl-MessagingManager-createSMS">createSMS</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-SMSProperties"><code>SMSProperties</code></a></span> <span class="idlParamName">smsProperties</span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-MMSMessage"><code>MMSMessage</code></a></span> <span class="idlMethName"><a href="#widl-MessagingManager-createMMS">createMMS</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-MMSProperties"><code>MMSProperties</code></a></span> <span class="idlParamName">mmsProperties</span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-EmailMessage"><code>EmailMessage</code></a></span> <span class="idlMethName"><a href="#widl-MessagingManager-createEmail">createEmail</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-EmailProperties"><code>EmailProperties</code></a></span> <span class="idlParamName">emailProperties</span></span>);</span>
};</span>
</pre><div class="section" id="methods"><h4><span class="secno">5.2.1 </span>Methods</h4><dl class="methods"><dt id="widl-MessagingManager-createEmail"><code>createEmail</code></dt><dd>
Creates a new <code>EmailMessage</code> object.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">emailProperties</td><td class="prmType"><code><a class="idlType" href="#idl-def-EmailProperties"><code>EmailProperties</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
The e-mail properties may include the "to", "cc", "bcc", "subject", "body", "priority" and "attachments" attributes.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a class="idlType" href="#idl-def-EmailMessage"><code>EmailMessage</code></a></code></div></dd><dt id="widl-MessagingManager-createMMS"><code>createMMS</code></dt><dd>
Creates a new <code>MMSMessage</code> object.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">mmsProperties</td><td class="prmType"><code><a class="idlType" href="#idl-def-MMSProperties"><code>MMSProperties</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
The MMS properties may include the "to", "subject", "body" and "attachments" attributes.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a class="idlType" href="#idl-def-MMSMessage"><code>MMSMessage</code></a></code></div></dd><dt id="widl-MessagingManager-createSMS"><code>createSMS</code></dt><dd>
Creates a new <code>SMSMessage</code> object.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">smsProperties</td><td class="prmType"><code><a class="idlType" href="#idl-def-SMSProperties"><code>SMSProperties</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
The SMS properties may include the "to" and "body" attributes.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a class="idlType" href="#idl-def-SMSMessage"><code>SMSMessage</code></a></code></div></dd></dl></div>
</div>
<div class="section" id="smsmessage">
<h3><span class="secno">5.3 </span><a class="idlType" href="#idl-def-SMSMessage"><code>SMSMessage</code></a></h3>
<p>
This interface describes generic functionality of SMS message.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-SMSMessage">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">SMSMessage</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-SMSProperties"><code>SMSProperties</code></a></span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Date</a></span> <span class="idlAttrName"><a href="#widl-SMSMessage-sentTime">sentTime</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>PendingOp</a></span> <span class="idlMethName"><a href="#widl-SMSMessage-send">send</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></span> <span class="idlParamName">successCB</span></span>, <span class="idlParam">in optional <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></span> <span class="idlParamName">errorCB</span></span>);</span>
};</span>
</pre><div class="section" id="attributes-1"><h4><span class="secno">5.3.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-SMSMessage-sentTime"><code>sentTime</code> of type <span class="idlAttrType"><a>Date</a></span>, readonly</dt><dd>
A readonly time stamp that detemines the time the SMS was sent. By default it is undefined and will be initialized when the message is successfully sent.
<div><em>No exceptions.</em></div></dd></dl></div><div class="section" id="methods-1"><h4><span class="secno">5.3.2 </span>Methods</h4><dl class="methods"><dt id="widl-SMSMessage-send"><code>send</code></dt><dd>
Asynchronous method to request sending an SMS. The <code>pendingOp</code> return object allows canceling the sending of the message.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">successCB</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
Function to call when the asynchronous operation completes.
</td></tr><tr><td class="prmName">errorCB</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
Function to call when the asynchronous operation fails.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>PendingOp</a></code></div></dd></dl></div>
</div>
<div class="section" id="mmsmessage">
<h3><span class="secno">5.4 </span><a class="idlType" href="#idl-def-MMSMessage"><code>MMSMessage</code></a></h3>
<p>
This interface describes generic functionality of MMS message.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-MMSMessage">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">MMSMessage</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-MMSProperties"><code>MMSProperties</code></a></span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Date</a></span> <span class="idlAttrName"><a href="#widl-MMSMessage-sentTime">sentTime</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>PendingOp</a></span> <span class="idlMethName"><a href="#widl-MMSMessage-send">send</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></span> <span class="idlParamName">successCB</span></span>, <span class="idlParam">in optional <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></span> <span class="idlParamName">errorCB</span></span>);</span>
};</span>
</pre><div class="section" id="attributes-2"><h4><span class="secno">5.4.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-MMSMessage-sentTime"><code>sentTime</code> of type <span class="idlAttrType"><a>Date</a></span>, readonly</dt><dd>
A readonly time stamp that detemines the time the MMS was sent. By default it is undefined and will be initialized when the message is successfully sent.
<div><em>No exceptions.</em></div></dd></dl></div><div class="section" id="methods-2"><h4><span class="secno">5.4.2 </span>Methods</h4><dl class="methods"><dt id="widl-MMSMessage-send"><code>send</code></dt><dd>
Asynchronous method to request sending an MMS. The <code>pendingOp</code> return object allows canceling the sending of the message.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">successCB</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
Function to call when the asynchronous operation completes.
</td></tr><tr><td class="prmName">errorCB</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
Function to call when the asynchronous operation fails.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>PendingOp</a></code></div></dd></dl></div>
</div>
<div class="section" id="emailmessage">
<h3><span class="secno">5.5 </span><a class="idlType" href="#idl-def-EmailMessage"><code>EmailMessage</code></a></h3>
<p>
This interface describes generic functionality of e-mail message.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-EmailMessage">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">EmailMessage</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-EmailProperties"><code>EmailProperties</code></a></span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Date</a></span> <span class="idlAttrName"><a href="#widl-EmailMessage-sentTime">sentTime</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>PendingOp</a></span> <span class="idlMethName"><a href="#widl-EmailMessage-send">send</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></span> <span class="idlParamName">successCB</span></span>, <span class="idlParam">in optional <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></span> <span class="idlParamName">errorCB</span></span>);</span>
};</span>
</pre><div class="section" id="attributes-3"><h4><span class="secno">5.5.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-EmailMessage-sentTime"><code>sentTime</code> of type <span class="idlAttrType"><a>Date</a></span>, readonly</dt><dd>
A readonly time stamp that determines the time the e-mail was sent. By default it is undefined and will be initialized when the message is successfully sent.
<div><em>No exceptions.</em></div></dd></dl></div><div class="section" id="methods-3"><h4><span class="secno">5.5.2 </span>Methods</h4><dl class="methods"><dt id="widl-EmailMessage-send"><code>send</code></dt><dd>
Asynchronous method to request sending an e-mail.
The <code>pendingOp</code> return object allows cancelling the sending of the message.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">successCB</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
Function to call when the asynchronous operation completes.
</td></tr><tr><td class="prmName">errorCB</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
Function to call when the asynchronous operation fails.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>PendingOp</a></code></div></dd></dl></div>
</div>
<div class="section" id="smsproperties">
<h3><span class="secno">5.6 </span><a class="idlType" href="#idl-def-SMSProperties"><code>SMSProperties</code></a></h3>
<p>
This interface captures the data fields in an SMS message. See <a href="#supported-messaging-types">Supported Messaging Types</a> for the list of attributes that must be supported for SMS type.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-SMSProperties">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">SMSProperties</span> {
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a>[]</span> <span class="idlAttrName"><a href="#widl-SMSProperties-to">to</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-SMSProperties-body">body</a></span>;</span>
};</span>
</pre><div class="section" id="attributes-4"><h4><span class="secno">5.6.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-SMSProperties-body"><code>body</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The message text body
<div><em>No exceptions.</em></div></dd><dt id="widl-SMSProperties-to"><code>to</code> of type array of <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The set of addresses of the recipients. For SMS these are phone numbers.
<div><em>No exceptions.</em></div></dd></dl></div>
</div>
<div class="section" id="mmsproperties">
<h3><span class="secno">5.7 </span><a class="idlType" href="#idl-def-MMSProperties"><code>MMSProperties</code></a></h3>
<p>
This interface captures the data fields in an MMS message. See <a href="#supported-messaging-types">Supported Messaging Types</a> for the list of attributes that must be supported for MMS type.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-MMSProperties">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">MMSProperties</span> {
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a>[]</span> <span class="idlAttrName"><a href="#widl-MMSProperties-to">to</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-MMSProperties-subject">subject</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-MMSProperties-body">body</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Blob</a>[]</span> <span class="idlAttrName"><a href="#widl-MMSProperties-attachments">attachments</a></span>;</span>
};</span>
</pre><div class="section" id="attributes-5"><h4><span class="secno">5.7.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-MMSProperties-attachments"><code>attachments</code> of type array of <span class="idlAttrType"><a>Blob</a></span></dt><dd>
The list of files [<cite><a href="#bib-FILE-API" rel="biblioentry" class="bibref">FILE-API</a></cite>] that will be sent together with the MMS as attachments.
<div><em>No exceptions.</em></div></dd><dt id="widl-MMSProperties-body"><code>body</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The MMS text body
<div><em>No exceptions.</em></div></dd><dt id="widl-MMSProperties-subject"><code>subject</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The MMS subject
<div><em>No exceptions.</em></div></dd><dt id="widl-MMSProperties-to"><code>to</code> of type array of <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The set of addresses of the recipients. For MMS these may be phone numbers or e-mail addresses.
<div><em>No exceptions.</em></div></dd></dl></div>
</div>
<div class="section" id="emailproperties">
<h3><span class="secno">5.8 </span><a class="idlType" href="#idl-def-EmailProperties"><code>EmailProperties</code></a></h3>
<p>
This interface captures the data fields in an e-mail message. See <a href="#supported-messaging-types">Supported Messaging Types</a> for the list of attributes that must be supported for e-mail type.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-EmailProperties">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">EmailProperties</span> {
<span class="idlAttribute"> attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a>[]</span> <span class="idlAttrName"><a href="#widl-EmailProperties-to">to</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a>[]</span> <span class="idlAttrName"><a href="#widl-EmailProperties-cc">cc</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a>[]</span> <span class="idlAttrName"><a href="#widl-EmailProperties-bcc">bcc</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-EmailProperties-subject">subject</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-EmailProperties-body">body</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-EmailProperties-priority">priority</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Blob</a>[]</span> <span class="idlAttrName"><a href="#widl-EmailProperties-attachments">attachments</a></span>;</span>
};</span>
</pre><div class="section" id="attributes-6"><h4><span class="secno">5.8.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-EmailProperties-attachments"><code>attachments</code> of type array of <span class="idlAttrType"><a>Blob</a></span></dt><dd>
The list of files [<cite><a href="#bib-FILE-API" rel="biblioentry" class="bibref">FILE-API</a></cite>] that will be sent together with the e-mail as attachments.
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailProperties-bcc"><code>bcc</code> of type array of <span class="idlAttrType"><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a></span></dt><dd>
The set of bcc (blind carbon copy) addresses and names of the recipients.
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailProperties-body"><code>body</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The message text body
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailProperties-cc"><code>cc</code> of type array of <span class="idlAttrType"><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a></span></dt><dd>
The set of cc (carbon copy) addresses and names of the recipients.
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailProperties-priority"><code>priority</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
Delivery priority, the possible values are 'low', 'normal' (default) or 'high'.
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailProperties-subject"><code>subject</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The message subject
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailProperties-to"><code>to</code> of type array of <span class="idlAttrType"><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a></span></dt><dd>
The set of e-mail addresses and names of the recipients.
<div><em>No exceptions.</em></div></dd></dl></div>
</div>
<div class="section" id="emailaddress">
<h3><span class="secno">5.9 </span><a class="idlType" href="#idl-def-EmailAddress"><code>EmailAddress</code></a></h3>
<p>
This interface captures the data fields in an e-mail address.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-EmailAddress">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">EmailAddress</span> {
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-EmailAddress-address">address</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-EmailAddress-name">name</a></span>;</span>
};</span>
</pre><div class="section" id="attributes-7"><h4><span class="secno">5.9.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-EmailAddress-address"><code>address</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The e-mail address. It <em title="must" class="rfc2119">must</em> be a <b>valid e-mail address</b> as defined in [<cite><a href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a></cite>].
<div><em>No exceptions.</em></div></dd><dt id="widl-EmailAddress-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span></dt><dd>
The name associated to the "address". It is an optional attribute and by default it is undefined.
<div><em>No exceptions.</em></div></dd></dl></div>
</div>
<div class="section" id="messagingsuccesscb">
<h3><span class="secno">5.10 </span><a class="idlType" href="#idl-def-MessagingSuccessCB"><code>MessagingSuccessCB</code></a></h3>
<p>
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-MessagingSuccessCB">[<span class="extAttr">Callback=FunctionOnly, NoInterfaceObject</span>]
interface <span class="idlInterfaceID">MessagingSuccessCB</span> {
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-MessagingSuccessCB-onSuccess">onSuccess</a></span> ();</span>
};</span>
</pre><div class="section" id="methods-4"><h4><span class="secno">5.10.1 </span>Methods</h4><dl class="methods"><dt id="widl-MessagingSuccessCB-onSuccess"><code>onSuccess</code></dt><dd>
Invoked method when a successful messaging asynchronous call is received in the device.
<div><em>No parameters.</em></div><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
</div>
<div class="section" id="messagingerrorcb">
<h3><span class="secno">5.11 </span><a class="idlType" href="#idl-def-MessagingErrorCB"><code>MessagingErrorCB</code></a></h3>
<p>
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-MessagingErrorCB">[<span class="extAttr">Callback=FunctionOnly, NoInterfaceObject</span>]
interface <span class="idlInterfaceID">MessagingErrorCB</span> {
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-MessagingErrorCB-onError">onError</a></span> (<span class="idlParam">in <span class="idlParamType"><a class="idlType" href="#idl-def-MessagingError"><code>MessagingError</code></a></span> <span class="idlParamName">error</span></span>);</span>
};</span>
</pre><div class="section" id="methods-5"><h4><span class="secno">5.11.1 </span>Methods</h4><dl class="methods"><dt id="widl-MessagingErrorCB-onError"><code>onError</code></dt><dd>
This interface defines the method invoked on failed messaging asynchronous calls defined in this API.
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">error</td><td class="prmType"><code><a class="idlType" href="#idl-def-MessagingError"><code>MessagingError</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
</div>
<div class="section" id="messagingerror">
<h3><span class="secno">5.12 </span><a class="idlType" href="#idl-def-MessagingError"><code>MessagingError</code></a></h3>
<p class="note">
Adds Messaging API specific error codes.
</p>
<p>
The <code>MessagingError</code> interface encapsulates all errors in the manipulation of <code>Messaging</code> objects in the messaging API.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-MessagingError">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">MessagingError</span> : <span class="idlSuperclass"><a>GenericError</a></span> {
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-UNKNOWN_ERROR">UNKNOWN_ERROR</a></span> = <span class="idlConstValue">0</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-INVALID_ARGUMENT_ERROR">INVALID_ARGUMENT_ERROR</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-TIMEOUT_ERROR">TIMEOUT_ERROR</a></span> = <span class="idlConstValue">3</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-PENDING_OPERATION_ERROR">PENDING_OPERATION_ERROR</a></span> = <span class="idlConstValue">4</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-IO_ERROR">IO_ERROR</a></span> = <span class="idlConstValue">5</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-NOT_SUPPORTED_ERROR">NOT_SUPPORTED_ERROR</a></span> = <span class="idlConstValue">6</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-PERMISSION_DENIED_ERROR">PERMISSION_DENIED_ERROR</a></span> = <span class="idlConstValue">20</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-MessagingError-MESSAGE_SIZE_EXCEEDED">MESSAGE_SIZE_EXCEEDED</a></span> = <span class="idlConstValue">30</span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-MessagingError-code">code</a></span>;</span>
};</span>
</pre><div class="section" id="attributes-8"><h4><span class="secno">5.12.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-MessagingError-code"><code>code</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>
An error code assigned by an implementation when an error has occurred in Messaging API processing.
<div><em>No exceptions.</em></div></dd></dl></div><div class="section" id="constants"><h4><span class="secno">5.12.2 </span>Constants</h4><dl class="constants"><dt id="widl-MessagingError-INVALID_ARGUMENT_ERROR"><code>INVALID_ARGUMENT_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
An invalid parameter was provided when the requested method was invoked.
</dd><dt id="widl-MessagingError-IO_ERROR"><code>IO_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
An error occurred in communication with the underlying implementation that meant the requested method could not complete.
</dd><dt id="widl-MessagingError-MESSAGE_SIZE_EXCEEDED"><code>MESSAGE_SIZE_EXCEEDED</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The message that has been tried to be sent exceeds the maximum supported size for that message type.
</dd><dt id="widl-MessagingError-NOT_SUPPORTED_ERROR"><code>NOT_SUPPORTED_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The requested method is not supported by the current implementation.
</dd><dt id="widl-MessagingError-PENDING_OPERATION_ERROR"><code>PENDING_OPERATION_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
If the <a>user agent</a> is currently waiting for a callback on an asynchronous messaging operation, as defined in this specification.
</dd><dt id="widl-MessagingError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
Access to the requested method was denied at the implementation or by the user.
</dd><dt id="widl-MessagingError-TIMEOUT_ERROR"><code>TIMEOUT_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The requested method timed out before it could be completed.
</dd><dt id="widl-MessagingError-UNKNOWN_ERROR"><code>UNKNOWN_ERROR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
An unknown error occurred.
</dd></dl></div>
</div>
</div>
<div id="features-for-future-consideration" class="appendix section">
<!--OddPage--><h2><span class="secno">A. </span>Features for Future Consideration</h2>
<p>The following messaging functionalities have been delayed to a future version of the API.</p>
<ul>
<li>Message subscription and reading.</li>
<li>Message and folder management.</li>
<li>E-mail account management.</li>
<li>Notion of default accounts.</li>
</ul>
</div>
<div id="acknowledgements" class="appendix section">
<!--OddPage--><h2><span class="secno">B. </span>Acknowledgements</h2>
<p>
...
</p>
</div>
<div class="appendix section" id="references"><!--OddPage--><h2><span class="secno">C. </span>References</h2><div class="section" id="normative-references"><h3><span class="secno">C.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-CORE-DEVICE">[CORE-DEVICE]</dt><dd>Robin Berjon. <a href="http://dev.w3.org/2009/dap/device/"><cite>Core Device Interfaces.</cite></a> 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: <a href="http://dev.w3.org/2009/dap/device/">http://dev.w3.org/2009/dap/device/</a>
</dd><dt id="bib-FILE-API">[FILE-API]</dt><dd>Arun Ranganathan. <a href="http://www.w3.org/TR/2009/WD-FileAPI-20091117/"><cite>File API.</cite></a> 17 November 2009. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2009/WD-FileAPI-20091117/">http://www.w3.org/TR/2009/WD-FileAPI-20091117/</a>
</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/2010/WD-html5-20100304/"><cite>HTML 5.</cite></a> 4 March 2010. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2010/WD-html5-20100304/">http://www.w3.org/TR/2010/WD-html5-20100304/</a>
</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
</dd><dt id="bib-WEBIDL">[WEBIDL]</dt><dd>Cameron McCormack. <a href="http://www.w3.org/TR/2008/WD-WebIDL-20081219"><cite>Web IDL.</cite></a> 19 December 2008. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2008/WD-WebIDL-20081219">http://www.w3.org/TR/2008/WD-WebIDL-20081219</a>
</dd></dl></div><div class="section" id="informative-references"><h3><span class="secno">C.2 </span>Informative references</h3><p>No informative references.</p></div></div></body></html>
Received on Wednesday, 19 January 2011 17:11:39 UTC