Webinos Logo

Contacts API

Webinos API Specifications

30 Aug 2012

Authors


Abstract

This API provides access to a user unified address book.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Webinos
    2. Contacts
    3. PendingContactFindOp
    4. ContactProps
    5. ContactFilter
    6. Contact
    7. ContactName
    8. ContactField
    9. ContactAddress
    10. ContactOrganization
  3. Callbacks
    1. ContactFindSuccessCB
    2. ContactAddSuccessCB
    3. ContactUpdateSuccessCB
    4. ContactDeleteSuccessCB
    5. ContactErrorCB
  4. Features
  5. Full WebIDL

Summary of Methods

Interface Method
Webinos
Contacts Contact createContact(ContactProps? contactProps)
void addContact(ContactAddSuccessCB successCB, ContactErrorCB? errorCB, Contact contact)
void updateContact(ContactUpdateSuccessCB successCB, ContactErrorCB? errorCB, Contact contact)
void deleteContact(ContactDeleteSuccessCB successCB, ContactErrorCB? errorCB, DOMString id)
PendingContactFindOp findContacts(ContactFindSuccessCB successCB, ContactErrorCB? errorCB, ContactFilter? filter)
PendingContactFindOp void cancel()
Contact

Introduction

The Contacts API defines the high-level interfaces required to obtain access to a user's unified address book.

This API includes the following key interfaces:

A Contacts interface, which provides the method needed to access a user's unified address book. A Contact interface, which captures the individual contact information that can be returned following a successful read operation.

The webinos Contacts API combines features from the WAC and the W3C contact APIs.

The format of an individual contact is mostly taken from W3C, since it contains more information than the WAC version.

The available functions on the Contacts are mostly taken from the WAC specification, since they provide write functionality for contacts.

Interfaces and Dictionaries

Interface Webinos (partial interface)

Creates the webinos.contacts namespace.

WebIDL
         partial interface Webinos {

                     attribute Contacts contacts;
        };

Attributes

Contacts contacts

The object through which the contacts functionality can be accessed. No exceptions.

Interface Contacts

The Contacts interface exposes a database of contact information that may be retrieved.

WebIDL
        [NoInterfaceObject]
        interface Contacts {
        

             
             Contact createContact(optional ContactProps? contactProps);


                
                void addContact(ContactAddSuccessCB successCB, ContactErrorCB? errorCB, Contact contact);                


                void updateContact(ContactUpdateSuccessCB successCB, ContactErrorCB? errorCB, Contact contact);                


                void deleteContact(ContactDeleteSuccessCB successCB, ContactErrorCB? errorCB, DOMString id);          



                 
                PendingContactFindOp findContacts(ContactFindSuccessCB successCB, optional ContactErrorCB? errorCB, optional ContactFilter? filter);

        
        };

Multiple contact groups can be represented within this unified address book by specifying consistent categories values as part of individual Contact objects.

Multiple contact groups can be displayed by filtering on the required categories values via the Contacts find() operation.

The ServiceContacts interface is exposed on the Navigator object [NAVIGATOR].

Its goal is to provide an access point to the functionality in this specification.

Methods

createContact

The createContact() method creates an object that implements the Contact interface.

Signature
Contact createContact(optional ContactProps? contactProps);

When the optional contactProps are passed as an argument, the newly created contact is prepopulated with the supplied values.

If the contactProps attribute is omitted, the implementation MUST assign the default values to all contact attributes and attempt to create the instance of the Contact Interface. If the contactProps attribute passed as the input parameter contains only a subset of the ContactProps attributes with valid values, the implementation MUST assign the default values to the other attributes and attempt to create an instance of the Contact Interface. If the contact passed as input parameter contains valid values for all the contactProps attributes, the implementation MUST try to create the instance of Contact Interface.

This operation does not add the created contact to the Address Book, and an identifier (id attribute) is not assigned to the contact. The addContact method performs these tasks when invoked by the developer.

Code example
 var contact = window.webinos.contacts.createContact({
         name: "John Doe"
 });                        
 
Parameters
  • contactProps
    • Optional: Yes.
    • Nullable: Yes
    • Type: ContactProps
    • Description: The property to initially apply to the created contact
Return value
Contact The contact that was created
addContact

The addContact() method asynchronously adds a contact to the contacts.

Signature
void addContact(ContactAddSuccessCB successCB, ContactErrorCB? errorCB, Contact contact);

If any of the input parameters contain an invalid value, such as a null or undefined successCallback, the contact has any invalid value or the address book has some restrictions that cause the attempted insertion of the contact item to fail (e.g. limitations in the size of text attributes), the implementation MUST reject the request and invoke the errorCallback with a DOMException and code INVALID_VALUES_ERROR. Please note that in order to allow developer ignore errors errorCallback accepts null as a valid value.

If the contact is successfully added to the Address Book, the successCallback MUST be invoked. The successCallback includes a Contact element that describes the Contact that has been added and includes the assigned id attribute.

In any of the above cases where the errorCallback should be invoked as specified above, if the developer has not passed a valid ErrorCallback (e.g. it is null or undefined), no action is required (i.e. the error is not notified to the developer).

Code example
 var contact = window.webinos.contacts.createContact({
         name: "John Doe"
 });
 
 window.webinos.contacts.addContact(successwrite, error, contact);
 
 
 var successwrite = function(contact) {
         alert("Wrote " + contact.id);
 };
 
 var error = function(e) {
         alert("Error: " + e);
 };                
 
Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: ContactAddSuccessCB
    • Description: Function to call when the asynchronous operation completes successfully.
  • errorCB
    • Optional: No.
    • Nullable: Yes
    • Type: ContactErrorCB
    • Description: Function to call when the asynchronous operation fails.
  • contact
    • Optional: No.
    • Nullable: No
    • Type: Contact
    • Description: The contact to add to the contacts list.
Return value
void
updateContact

The updateContact() method asynchronously updates an existing contact in an address book.

Signature
void updateContact(ContactUpdateSuccessCB successCB, ContactErrorCB? errorCB, Contact contact);

If any of the input parameters contain an invalid value, such as a null or undefined successCallback, the contact has any invalid value or the address book has some restrictions that cause the attempted insertion of the contact item to fail (e.g. limitations in the size of text attributes), the implementation MUST reject the request and invoke the errorCallback with a DOMException and code INVALID_VALUES_ERROR. Please note that in order to allow developer ignore errors errorCallback accepts null as a valid value.

If the id attribute does not correspond to the id attribute of any contact in the address book, (e.g. there is not an existing contact to update matching the id) a DOMException with code NOT_FOUND_ERR MUST be returned.

If all the attributes are valid and the id attribute corresponds to an existing contact in the address book, the implementation MUST attempt to update the contact that corresponds to that identifier with the updated attributes.

If the contact is successfully updated, the SuccessCallback MUST be invoked.

In any of the above cases where the errorCallback should be invoked, if the developer has not passed a valid ErrorCallback (e.g. it is null or undefined), no action is required (i.e. he error is not notified to the developer).

Code example
  window.webinos.contacts.findContacts(toUpdate, errorCallback, {
                          name: "%John Doe%"
                  });
  
  function toUpdate(contactlist) {
          if (contactlist.length > 0) {
                  for (i = 0; i  contactlist.length; i++) {
                          contactlist[i].nickname = ["Jonny"];
                          window.webinos.contacts.updateContact(contactUpdatedCB, errorCallback, contactlist[i]);
                  }
          } else {
                  alert("No contact with the name 'John Doe' could be found");
          }
  }
  
  function contactUpdatedCB() {
          // The contact has been successfully updated
          alert("Contact 'John Doe' successfully updated");
  }
  
  function errorCallback(response) {
          alert("The following error occurred: " + response.code);
  }
 
Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: ContactUpdateSuccessCB
    • Description: Function to call when the asynchronous operation completes successfully.
  • errorCB
    • Optional: No.
    • Nullable: Yes
    • Type: ContactErrorCB
    • Description: Function to call when the asynchronous operation fails.
  • contact
    • Optional: No.
    • Nullable: No
    • Type: Contact
    • Description: The contact to update in the contacts list.
Return value
void
deleteContact

Deletes a contact from the address book asynchronously.

Signature
void deleteContact(ContactDeleteSuccessCB successCB, ContactErrorCB? errorCB, DOMString id);

The implementation MUST attempt to delete the contact that corresponds to that identifier.

If the contact is successfully deleted, the SuccessCallback MUST be invoked.

Code example
  window.webinos.contacts.findContacts(toDelete, errorCallback, {
                          name: "%John Doe%"
                  });
  
  function toDelete(contactlist) {
          if (contactlist.length > 0) {
                  for (i = 0; i  contactlist.length; i++) {
                          window.webinos.contacts.deleteContact(contactDeletedCB, errorCallback, contactlist[i].id);
                  }
          } else {
                  alert("No contact with the name 'John Doe' could be found");
          }
  }
  
  function contactDeletedCB() {
          // The contact has been successfully deleted
          alert("Contact 'John Doe' deleted");
  }
  
  function errorCallback(response) {
          alert("The following error occurred: " + response.code);
  }
 
Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: ContactDeleteSuccessCB
    • Description: Function to call when the asynchronous operation completes successfully.
  • errorCB
    • Optional: No.
    • Nullable: Yes
    • Type: ContactErrorCB
    • Description: Function to call when the asynchronous operation fails.
  • id
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: The id of the contact to delete from the contacts list.
Return value
void
findContacts

The findContacts() method returns an array of all Contacts that match the optionally supplied filter.

Signature
PendingContactFindOp findContacts(ContactFindSuccessCB successCB, optional ContactErrorCB? errorCB, optional ContactFilter? filter);

If the filter is passed and contains valid values, only those values that match the filter criteria as specified in the ContactFilter interface will be returned in the successCallback. If no filter is passed, the filter contains any invalid values, the filter is null or undefined, then the implementation MUST return the full list of contact items in the successCallback.

If no contacts are available or no contact matches the filter criteria, the successCallback will be invoked with an empty array.

If any other error occurs while trying to retrieve the contacts, the errorCallback function that was passed in the invocation MUST be called, passing a DOMException object with code UNKNOWN_ERROR.

In any of the above cases where the errorCallback should be invoked, as specified above, if the developer has not passed a valid ErrorCallback (e.g. it is null or undefined), no action is required and the developer is not notified of the error.

Code example
  window.webinos.contacts.findContacts(findSuccess, errorCallback, {
                          name: "%John Doe%"
                  });
  
  function findSuccess(contactlist) {
          if (contactlist.length > 0) {
                     alert(contactlist.length+" contacts with the name 'John Doe' found");
                  }
          } else {
                  alert("No contact with the name 'John Doe' could be found");
          }
  }
  
  function errorCallback(response) {
          alert("The following error occurred: " + response.code);
  }
 
Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: ContactFindSuccessCB
    • Description: Function to call when the asynchronous operation completes successfully.
  • errorCB
    • Optional: Yes.
    • Nullable: Yes
    • Type: ContactErrorCB
    • Description: Function to call when the asynchronous operation fails.
  • filter
    • Optional: Yes.
    • Nullable: Yes
    • Type: ContactFilter
    • Description: The search qualifier.
Return value
A pending operation object making it possible to cancel the findContacts operation

Interface PendingContactFindOp

The PendingContactFindOp interface

WebIDL
     [NoInterfaceObject] interface PendingContactFindOp {


        void cancel ();
     };

The PendingContactFindOp interface describes the object that is returned by the asynchronous find contacts sensor method. It makes it possible to abort this operation to a stop if it hasn't produced a result within a desired time or before a given event, thereby possibly reclaiming resources.

Methods

cancel

Method Cancel

Signature
void cancel();

Cancel the pending find contacts asynchronous operation. When this method is called, the user agent must immediately bring the operation to a stop and return. Allocated resources should be released and any ongoing related network operations should be terminated. An error callback is issued with the DOMError name "AbortError" is issued.

Dictionary ContactProps

ContactProps dictionary

WebIDL
        dictionary ContactProps {

                ContactName? name         = "";

                DOMString? nickname     = "";

                DOMString?  displayName = "";

                ContactAddress[]? addresses;

                ContactField[]? photos; 

                ContactField[]? phoneNumbers;

                ContactField[]? emails;

              ContactField[]?        ims;

              ContactOrganization[]? organizations;

              Date?                  birthday;

              DOMString?             gender;

              DOMString?             note;

              DOMString[]?           categories;

              ContactField[]?        urls;

              DOMString?             timezone;
        };

This interface is intended to be used to input parameters when contacts are created using the createContact method.

All the attributes are optional and by default are undefined unless otherwise stated in the parameter description.

Dictionary Members

ContactName? name

This attribute represents the full name of this Contact indicated by the name components associated with the ContactName object.

DOMString? nickname

This attribute contains the nickname (or a casual name) for this Contact.

DOMString? displayName

This attribute contains the name of this Contact in a form that is suitable for display to the user.

ContactAddress[] addresses

This attribute represents one or more physical addresses associated with this Contact.

ContactField[] photos

This attribute represents one or more photos associated with this Contact.

ContactField[] phoneNumbers

This attribute captures one or more phone numbers associated with this Contact.

ContactField[] emails

This attribute represents one or more email addresses associated with this Contact.

ContactField[] ims

This attribute represents one or more instant messaging identifiers associated with this Contact.

ContactOrganization[] organizations

This attribute represents one or more organizations associated with this Contact.

Date? birthday

This attribute contains birthday of this Contact.

DOMString? gender

This attribute contains the gender of this Contact. This attribute should have one of the following values:

DOMString? note

This attribute contains the personal notes (free-text) for this Contact that is managed by the user of the address book.

DOMString[] categories

This attribute contains one or more user-defined categories/tags/labels associated with this Contact. e.g. "family", "favourite", "cryptozoologists".

ContactField[] urls

This attribute represents one or more URLs associated with this Contact e.g. personal web page, blog.

DOMString? timezone

This attribute represents the time zone of this Contact.

Dictionary ContactFilter

ContactFilter dictionary

WebIDL
        dictionary ContactFilter {

                DOMString? id  ;

                DOMString? name  ;

                DOMString? nickname ;

                DOMString?  displayName;

                ContactAddress[]? addresses;

               DOMString?   photos; 

               DOMString?   phoneNumbers;

                DOMString? emails;

             DOMString?        ims;

              DOMString?  organizations;

              Date?                  birthday;

              DOMString?             gender;

              DOMString?             note;

               DOMString?           categories;

               DOMString?          urls;

              DOMString?             timezone;

             boolean?   multiple;

             Date      updatedSince;
              
        };

When this filter is supplied to the findContacts method, the result-set of that method MUST only contain the contact entries in the address book that match the filter values.

A contact matches the filter, if the attributes of the contact match all the attributes of the filter. If the filter contains values that are undefined or null, these MUST be ignored. I.e. the search is performed in a similar manner to a SQL "AND" operation.

An attribute of the contact matches the filter value according to to the following rule:

For filter attributes of type DOMString, an entry matches this value if its corresponding attribute is exactly the same as the filter attribute. However, if the filter contains U+0025 'PERCENT SIGN' wildcard character(s), the filter behavior is similar to the LIKE condition in SQL ('%' matches any string of any length - including zero length). In order to specify that a 'PERCENT SIGN' character is to be considered literally instead of interpreting it as a wildcard, developers may escape it with the backslash character. The matching is not case sensitive, e.g. "FOO" matches a "foo" or an "f%" filter.

Dictionary Members

DOMString? id

Used for filtering the Contact id attribute.

Contacts with id attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? name

Used for filtering the Contact name attribute.

Contacts with name attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? nickname

Used for filtering the Contact nickname attribute.

Contacts with nickname attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? displayName

Used for filtering the Contact displayName attribute.

Contacts with displayName attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

ContactAddress[] addresses

Used for filtering the Contact addresses attribute.

Contacts with at least one address in the addresses array matching all the specified address attributes in the supplied address object (either exactly or with the specified wildcards) match the filtering criteria. If the supplied address object includes null or undefined values for some attributes, these can be ignored.

DOMString? photos

Used for filtering the Contact photos attribute.

Contacts with photos attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? phoneNumbers

Used for filtering the Contact phoneNumbers attribute.

Contacts with phoneNumbers attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? emails

Used for filtering the Contact emails attribute.

Contacts with emails attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? ims

Used for filtering the Contact ims attribute.

Contacts with ims attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? organizations

Used for filtering the Contact organizations attribute.

Contacts with organizations attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

Date? birthday

Used for filtering the Contact birthday attribute.

Contacts with birthday attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? gender

Used for filtering the Contact gender attribute.

Contacts with gender attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? note

Used for filtering the Contact note attribute.

Contacts with note attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? categories

Used for filtering the Contact categories attribute.

Contacts with categories attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? urls

Used for filtering the Contact urls attribute.

Contacts with urls attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

DOMString? timezone

Used for filtering the Contact timezone attribute.

Contacts with timezone attribute that match this supplied attribute (either exactly or with the specified wildcards) match the filtering criteria.

boolean? multiple

A boolean value to indicate whether multiple Contact objects are wanted as part of the Contacts find() operation. By default this option is set to false.

No exceptions.

Date updatedSince

Return only contact records that have been updated on or after the given time, specified as an ECMAScript Date object.

This filter is applied to the revision field as defined in Contact.

No exceptions.

Interface Contact

The Contact interface captures the properties of a contact object.

WebIDL
        [NoInterfaceObject]
        interface Contact {
                        

             readonly attribute DOMString              id;

             attribute DOMString?             displayName;

             attribute  ContactName           name;

             attribute DOMString?             nickname;

             attribute ContactField[]?        phoneNumbers;

             attribute ContactField[]?        emails;

             attribute ContactAddress[]?      addresses;

             attribute ContactField[]?        ims;

             attribute ContactOrganization[]? organizations;

             attribute Date?                  revision;

             attribute Date?                  birthday;

             attribute DOMString?             gender;

             attribute DOMString?             note;

             attribute ContactField[]?        photos;

             attribute DOMString[]?           categories;

             attribute ContactField[]?        urls;

             attribute DOMString?             timezone;
        };

All Contact objects must include all attributes supported by the implementation, regardless of whether these attributes have been assigned a null value or not. If a supported attribute has not been assigned a value by the user or the implementation, then this attribute must still be present in the resulting Contact object and must have a value of null.

Additional attributes may be included according to the provisions detailed in Extended Contact Properties and Parameters. If an extended attribute is supported by the current implementation and has not been assigned a value by the user or the implementation, then this extended attribute must still be present in the resulting Contact object and must have a value of null.

Attributes

readonly DOMString id

A globally unique identifier for the given Contact object.

Each Contact instance must include a non-empty id value.

No exceptions.

This attribute is readonly.
DOMString? displayName

This attribute contains the name of this Contact in a form that is suitable for display to the user.

Each Contact must include either a displayName or the name attribute.

No exceptions.

ContactName name

This attribute represents the full name of this Contact indicated by the name components associated with the ContactName object.

Each Contact must include either a displayName or the name attribute.

No exceptions.

DOMString? nickname

This attribute contains the nickname (or a casual name) for this Contact.

No exceptions.

ContactField[] phoneNumbers

This attribute captures one or more phone numbers associated with this Contact.

No exceptions.

ContactField[] emails

This attribute represents one or more email addresses associated with this Contact.

No exceptions.

ContactAddress[] addresses

This attribute represents one or more physical addresses associated with this Contact.

No exceptions.

ContactField[] ims

This attribute represents one or more instant messaging identifiers associated with this Contact.

No exceptions.

ContactOrganization[] organizations

This attribute represents one or more organizations associated with this Contact.

No exceptions.

Date? revision

This attribute contains the timestamp information associated with this Contact, which represents the last known modification time. If no modification time exists, then this object contains the timestamp of the object's creation time.

No exceptions.

Date? birthday

This attribute contains birthday of this Contact.

The year value may be set to 0000 when the age of the Contact is private or the year is not available.

No exceptions.

DOMString? gender

This attribute contains the gender of this Contact. This attribute should have one of the following values:

male

female

undisclosed

Note however that this attribute may contain a value not listed above.

No exceptions.

DOMString? note

This attribute contains the personal notes (free-text) for this Contact that is managed by the user of the address book.

No exceptions.

ContactField[] photos

This attribute represents one or more photos associated with this Contact.

The photos must be specified in the value attribute of the ContactField object either by using a URL to an image resource or base64 encoded string of the image data.

No exceptions.

DOMString[] categories

This attribute contains one or more user-defined categories/tags/labels associated with this Contact. e.g. "family", "favourite", "cryptozoologists".

No exceptions.

ContactField[] urls

This attribute represents one or more URLs associated with this Contact e.g. personal web page, blog.

The web resources must be specified using the value attribute of the ContactField object, and its type field may be set to "blog" or "profile".

No exceptions.

DOMString? timezone

This attribute represents the time zone of this Contact.

It is recommended that names from the public-domain Olson database [TZDB] will be used as the value of this attribute, but this is not a restriction. For example, a value of America/New_York indicates the Contact is associated with the variable time zone of the New York region of the United States, including daylight saving time offsets experienced in that region.

It is also possible to use this attribute to express the timezone as a positive or negative difference from UTC, the 24-hour clock, units of hours and minutes (i.e. +hh:mm). For example, a value of +05:30 indicates the Contact is associated with a fixed time zone of GMT+05:30.

No exceptions.

Dictionary ContactName

The ContactName dictionary describes a contact's name.

WebIDL
        dictionary ContactName {

             DOMString? formatted;

             DOMString? familyName;

             DOMString? givenName;

            DOMString? middleName;

            DOMString? honorificPrefix;

            DOMString? honorificSuffix;
        };

Dictionary Members

DOMString? formatted

This attribute contains the full name, including all the individual components such as givenName, middleName, familyName, prefix, suffix as appropriate for the user's culture, and formatted for display (e.g. Mr. Joe Smith Jr).

No exceptions.

DOMString? familyName

This attribute contains the family name (also referred to as the last name) of this Contact.

No exceptions.

DOMString? givenName

This attribute contains the given name (also referred to as the first name) of this Contact.

No exceptions.

DOMString? middleName

This attribute contains the middle name of this Contact.

No exceptions.

DOMString? honorificPrefix

This attribute contains the honorific prefix (or title) of this Contact. E.g. Mr., Dr., Ms., Mrs.

No exceptions.

DOMString? honorificSuffix

This attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr.

No exceptions.

Dictionary ContactField

The ContactField dictionary is a reusable component that is used to capture contact fields of the Contact interface that have some modicum of structure.

WebIDL
        dictionary ContactField {

             DOMString  type;

             DOMString? value;

             boolean    pref;
        };

Dictionary Members

DOMString type

This attribute contains the type information for this ContactField and its content varies subject to the contact property this ContactField is representing. For example, if the ContactField is representing a phoneNumber property, the type attribute can be set to home, mobile; if the ContactField is representing the ims property, the type attribute could be set to xmpp, irc, bbm, etc.

No exceptions.

DOMString? value

This attribute contains the value for this ContactField and its content varies subject to the contact property this ContactField is representing. For example, if the ContactField is representing an email, the value attribute could be set to JoeSmith@example.com, and if the ContactField is representing a url, the value attribute can be set to http://www.example.org/joesmith, etc.

No exceptions.

boolean pref

This attribute indicates whether this instance of the ContactField is the preferred, or primary, value for the contact property this ContactField is representing in the Contact interface. By default, the value is false.

No exceptions.

Dictionary ContactAddress

The ContactAddress interface is a reusable component that is used to capture addresses within the Contact interface.

WebIDL
        dictionary ContactAddress {

             boolean    pref;

             DOMString? type;

             DOMString? formatted;

             DOMString? streetAddress;

             DOMString? locality;

             DOMString? region;

             DOMString? postalCode;

             DOMString? country;
        };

Dictionary Members

boolean pref

This attribute indicates whether this instance of the ContactAddress is the preferred, or primary, value for the contact. By default, the value is false.

No exceptions.

DOMString? type

This attribute contains the type of address this object is representing (e.g. work, home, premises, etc).

No exceptions.

DOMString? formatted

This attribute contains the full physical address including street, locality, region, postalCode, and country as appropriate, and formatted for display.

No exceptions.

DOMString? streetAddress

This attribute contains the street address corresponding to this ContactAddress.

No exceptions.

DOMString? locality

This attribute contains the locality (or city) name corresponding to this ContactAddress.

No exceptions.

DOMString? region

This attribute contains the region (or state/province) name corresponding to this ContactAddress.

No exceptions.

DOMString? postalCode

This attribute contains the postal code (or zip) corresponding to this ContactAddress.

No exceptions.

DOMString? country

This attribute contains the country name corresponding to this ContactAddress.

No exceptions.

Dictionary ContactOrganization

The ContactOrganization dictionary is a reusable component that is used to support contact organisations within the Contact interface.

WebIDL
     dictionary ContactOrganization {

             boolean    pref;

             DOMString? type;

             DOMString? name;

             DOMString? department;

             DOMString? title;
        };

Dictionary Members

boolean pref

This attribute indicates whether this instance of the ContactOrganization is the preferred, or primary, value for the contact. By default, the value is false.

No exceptions.

DOMString? type

This attribute contains the type of organization this object is representing.

No exceptions.

DOMString? name

The name of the organisation.

No exceptions.

DOMString? department

The department within which this Contact works.

No exceptions.

DOMString? title

The job title that the Contact holds inside this organisation.

No exceptions.

Callbacks

ContactFindSuccessCB

Callback on success of a find() operation

WebIDL
             callback ContactFindSuccessCB = void  (Contact[] contactObjs);
Signature
void ContactFindSuccessCB(Contact[] contactObjs);
Parameters
  • contactObjs
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: An array of Contact objects resulting from the given Contacts find() operation.
Return value
void

ContactAddSuccessCB

Callback on success of a addContact() operation

WebIDL
            callback ContactAddSuccessCB = void (Contact contact);
Signature
void ContactAddSuccessCB(Contact contact);
Parameters
  • contact
    • Optional: No.
    • Nullable: No
    • Type: Contact
    • Description: The contact that just has been added, including the contact id
Return value
void

ContactUpdateSuccessCB

Callback on success of a updateContact() operation

WebIDL
           callback ContactUpdateSuccessCB = void ();
Signature
void ContactUpdateSuccessCB();
Return value
void

ContactDeleteSuccessCB

Callback on success of a deleteContact() operation

WebIDL
                callback ContactDeleteSuccessCB = void ();
Signature
void ContactDeleteSuccessCB();
Return value
void

ContactErrorCB

Callback on failure of a find(), addContact(), updateContact(), deleteContact() operations

WebIDL
                 callback ContactErrorCB = void (DOMError error);
Signature
void ContactErrorCB(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: DOMError object capturing the type of the error
Return value
void

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/contacts.read
Read access to the address book.
http://webinos.org/api/contacts.write

Write access to the address book.

Full WebIDL

WebIDL
         partial interface Webinos {

                     attribute Contacts contacts;
        };  
        

        
        [NoInterfaceObject]
        interface Contacts {
        

             
             Contact createContact(optional ContactProps? contactProps);


                
                void addContact(ContactAddSuccessCB successCB, ContactErrorCB? errorCB, Contact contact);                


                void updateContact(ContactUpdateSuccessCB successCB, ContactErrorCB? errorCB, Contact contact);                


                void deleteContact(ContactDeleteSuccessCB successCB, ContactErrorCB? errorCB, DOMString id);          



                 
                PendingContactFindOp findContacts(ContactFindSuccessCB successCB, optional ContactErrorCB? errorCB, optional ContactFilter? filter);

        
        };
  

     [NoInterfaceObject] interface PendingContactFindOp {


        void cancel ();
     };

  

        dictionary ContactProps {

                ContactName? name         = "";

                DOMString? nickname     = "";

                DOMString?  displayName = "";

                ContactAddress[]? addresses;

                ContactField[]? photos; 

                ContactField[]? phoneNumbers;

                ContactField[]? emails;

              ContactField[]?        ims;

              ContactOrganization[]? organizations;

              Date?                  birthday;

              DOMString?             gender;

              DOMString?             note;

              DOMString[]?           categories;

              ContactField[]?        urls;

              DOMString?             timezone;
        };


        dictionary ContactFilter {

                DOMString? id  ;

                DOMString? name  ;

                DOMString? nickname ;

                DOMString?  displayName;

                ContactAddress[]? addresses;

               DOMString?   photos; 

               DOMString?   phoneNumbers;

                DOMString? emails;

             DOMString?        ims;

              DOMString?  organizations;

              Date?                  birthday;

              DOMString?             gender;

              DOMString?             note;

               DOMString?           categories;

               DOMString?          urls;

              DOMString?             timezone;

             boolean?   multiple;

             Date      updatedSince;
              
        };



        [NoInterfaceObject]
        interface Contact {
                        

             readonly attribute DOMString              id;

             attribute DOMString?             displayName;

             attribute  ContactName           name;

             attribute DOMString?             nickname;

             attribute ContactField[]?        phoneNumbers;

             attribute ContactField[]?        emails;

             attribute ContactAddress[]?      addresses;

             attribute ContactField[]?        ims;

             attribute ContactOrganization[]? organizations;

             attribute Date?                  revision;

             attribute Date?                  birthday;

             attribute DOMString?             gender;

             attribute DOMString?             note;

             attribute ContactField[]?        photos;

             attribute DOMString[]?           categories;

             attribute ContactField[]?        urls;

             attribute DOMString?             timezone;
        };
        

        dictionary ContactName {

             DOMString? formatted;

             DOMString? familyName;

             DOMString? givenName;

            DOMString? middleName;

            DOMString? honorificPrefix;

            DOMString? honorificSuffix;
        };

        

        dictionary ContactField {

             DOMString  type;

             DOMString? value;

             boolean    pref;
        };
        
        

        dictionary ContactAddress {

             boolean    pref;

             DOMString? type;

             DOMString? formatted;

             DOMString? streetAddress;

             DOMString? locality;

             DOMString? region;

             DOMString? postalCode;

             DOMString? country;
        };
     

     dictionary ContactOrganization {

             boolean    pref;

             DOMString? type;

             DOMString? name;

             DOMString? department;

             DOMString? title;
        };
        



             callback ContactFindSuccessCB = void  (Contact[] contactObjs);
            

 

            callback ContactAddSuccessCB = void (Contact contact);


      

           callback ContactUpdateSuccessCB = void ();


    
         

                callback ContactDeleteSuccessCB = void ();

   
       

                 callback ContactErrorCB = void (DOMError error);