2009/dap/contacts BlobWriter.html,NONE,1.1

Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv29296/contacts

Added Files:
	BlobWriter.html 
Log Message:
First editor's draft of Contact Blob Writer

--- NEW FILE: BlobWriter.html ---
<!DOCTYPE html>
<html>
  <head>
    <title>
      Contact Blob Writer
    </title>
    <meta
     http-equiv='Content-Type'
     content='text/html;charset=utf-8'>
<script
 type="text/javascript"
 src='../ReSpec.js/js/respec.js'
 class='remove'>
</script>
<script
 type="text/javascript"
 src='../ReSpec.js/js/sh_main.min.js'
 class='remove'>
</script>
<script
 type="text/javascript"
 class='remove'>
            var respecConfig = {
                specStatus: "ED",
                shortName: "contact-blob-writer",
            editors: [{name: "Richard Tibbett", company: "Opera Software ASA", companyURL: "http://opera.com/"}],
                //publishDate:  "2010-07-01",
                // previousPublishDate:  "2010-01-21",
                edDraftURI: "http://dev.w3.org/2009/dap/contacts/BlobWriter.html",
                // lcEnd: "2009-08-05",
            };
</script>
<script
 type="text/javascript"
 src='../common/config.js'
 class='remove'>
      
</script>
  </head>
  <body>
    <section
     id='abstract'>
      <p>
        The Contact Blob Writer provides an interface for developers to create contact objects from Javascript.
      </p>
      <p>  
        Contact objects can then be saved to the user's current device via the APIs and mechanisms defined in [[!FILE-API]] and shown 
        in this specification.
      </p>
      <p>
        This specification is built on top of an accompanying specification [[CONTACTS-API]] that enables read access to a user&#39;s
        unified address book.
      </p>
    </section>
    <section
     id='sotd'>
      <p>
        This document represents the early consensus of the group on the scope and features of the proposed Contact Blob Writer specification. 
        Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like 
        to get feedback.
      </p>
    </section>
    <section
     id='conformance'>
      <p>
        This specification defines conformance criteria that apply to a single product: the <dfn>user agent</dfn> that implements the
        interfaces that it contains.
      </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 [[!WEBIDL]], as this specification uses that specification and
        terminology.
      </p>
    </section>
    <section
     class="informative">
      <h2>
        Introduction
      </h2>
      
      <p>
         This specification provides a method for creating objects consisting of standard contact card information such as names, addresses and phone numbers so that
         these objects may be efficiently stored and saved on a user's device.
      </p>
      <p>
         The interfaces and API defined in this specification have been built on top of [[!FILE-API]]. <a>Contact Blobs</a> can be presented, downloaded 
         and stored on the user's device by creating a <a>Blob URI</a> [[!FILE-API]] from a created <a>Contact Blob</a> object. 
         This <a>Blob URI</a> may be presented to the user or invoked wherever URLs can be used within the web platform. 
      </p>
      <p>
         The API is designed so that implementors of this specification are not required to implement a handler for <a title="valid Contact Blob Type">valid Contact Blob Types</a>.
         The <a title="valid Contact Blob Type">valid Contact Blob Types</a> contained herein have been chosen for their ability to integrate with existing and legacy
         address book systems while still allowing <a title="user agent">user agents</a> to handle the given media types as required. 
      </p>
    </section>
    <section>
     <h2>Security and Privacy Considerations</h2>
     <p>
      This specification builds upon the security and privacy protections provided by the [[HTML5]] and [[!FILE-API]] specifications; 
      in particular, it is expected that any action to download the Contact information that has been created would require a 
      specific user interaction on an HTML element that is entirely controlled by the user agent.
     </p>
    </section>
    <section>
      <h2>
        Contact Blob API
      </h2>
      
      <section>
        <h2>
          Example
        </h2>
        <p>
          The following example illustrates how to create a Contact Blob, create a Blob URI and then a mechanism for saving the Contact object on the host device:
        </p>
<pre
 class='example sh_javascript_dom'>
&lt;a id="contactcard"&gt;Save our business card&lt;/a&gt;

&lt;script type="text/javascript"&gt; 
  // Define/Get some contact properties:
  var contact = {
    displayName: &#39;Robert&#39;,
    emails: [
      {
        value: &#39;bob@foo.com&#39;
      }
    ]
    // ...
  };

  // Create a new Contact Blob:
  var contactBlob = navigator.service.contacts.createContactBlob(contact);
  
  // Create a Blob URI object:
  // @see http://www.w3.org/TR/file-upload/#dfn-createObjectURL
  var contactURL = createObjectURL(contactBlob);
  
  // e.g. Assign contact URI to anchor element for user-initiated download: 
  document.getElementById(&#39;contactcard&#39;).href = contactURL;
&lt;/script&gt;
</pre>
      </section>
      
      <section>
         <h2><a>ContactURIMethods</a> interface</h2>

        <p>
          The <a>ContactURIMethods</a> interface allows users to create a <a>Contact Blob</a>.
        </p>
        
        <p>
          The <a
           href='#contacturimethods-interface'><code>ContactURIMethods</code></a> interface is exposed on the <a class="externalDFN" title="Contacts" href="http://dev.w3.org/2009/dap/contacts/Overview.html#contacts-interface">Contacts</a> object as defined in [[!CONTACTS-API]].
        </p>
        <div
         class='idl'
         title='Contacts implements ContactURIMethods'>
          &nbsp;
        </div>
        <dl class='idl' title='[NoInterfaceObject] interface ContactURIMethods'>
         <dt>
           Blob createContactBlob()
         </dt>
         <dd>
            Returns a <a>Contact Blob</a> containing the attributes provided.
            <dl class='parameters'>
              <dt>
                Contact attributes
              </dt>
              <dd>
                <a class="externalDFN" title="Contact" href="http://dev.w3.org/2009/dap/contacts/Overview.html#contact-interface">Contact</a> [[!CONTACTS-API]] properties to assign to the resulting <a>Contact Blob</a> object.
              </dd>
            </dl>
         </dd>
        </dl>
      </section>  
    </section>
    <section>
      <h2>Contact Blobs</h2>
      
      <p>
         A <dfn>Contact Blob</dfn> is a <a class="externalDFN" title="Blob" href="http://www.w3.org/TR/file-upload/#blob">Blob</a> object [[!FILE-API]] with a <a class="externalDFN" title="Blob_type" href="http://www.w3.org/TR/file-upload/#dfn-type"><var>type</var></a> attribute that 
         matches one of the given <a title="valid Contact Blob Type">valid Contact Blob Types</a>.
      </p>
      
      <p>
         A <dfn>valid Contact Blob Type</dfn> MUST be one of the following media types:
      </p>
      
      <ul>
         <li><code>text/x-vcard</code></li>
         <li><code>text/directory</code></li>
         <li><code>text/directory;profile=vCard</code></li>
      </ul>
      
      <p>
         ...
      </p>
      
      <p class="issue">
       Define <a class="externalDFN" title="Fragment Idenfifier" href="http://www.w3.org/TR/file-upload/#fragmentIdentifier">fragment identifiers</a> [[!FILE-API]] for this media type(?)
      </p>

      <p>
         ...
      </p>
      
    </section>
    
  </body>
</html>

Received on Monday, 8 November 2010 14:42:00 UTC