save

Purpose

Uses given parameters to add an entry to the user's address book.

Signature

save( contact, callbacks )

Returns

This method does not return anything.

Parameter

Name	Description
contact	A JavaScript object containing contact parameters. The object must be W3C Contact API specification compliant. However, certain limitations apply and have been listed below.
callbacks	An object containing two callback methods listed below.

The table below lists contact parameter limitations against the W3C Contact object specification.

Parameter	Description
name	Not supported on iOS.
honorificPrefix	Only one prefix is supported.
givenName	Only one name is supported. Name lists cannot be used.
additionalName	Only one name is supported. Name lists cannot be used.
familyName	Only one name is supported. Name lists cannot be used.
honorificSuffix	Only one suffix is supported.
nickname	Only one name is supported. Name lists cannot be used.
photo	On Android/iOS, only one data URI is supported. iOS returns thumbnails only.
categories	Not supported.
tel	Carrier name is not supported on iOS.
org	On Android/iOS, only one organization is supported.
jobTitle	On Android/iOS, only one job title is supported.
note	Only one note is supported on iOS.
impp	Not supported.
sex	Not supported.
genderIdentity	Not supported.

Callbacks object structure

The remove listener's callbacks object can be structured as follows:

{
    onSuccess: function (contact) { ... },
    onFailure: function (error) { ... }
}

Callback methods

Name	Description	Return type
onSuccess	A callback function that accepts an array of contact entries that match the query. The entries of the returned contacts array are consistent with the section 5.1 of the The Contact dictionary specification.	`undefined`
onFailure	Passed to notify that the process could not be completed. It passes an object that contains a description of an error.	`undefined`

Example

The following example illustrates the use of the method described above.

var contacts = launchbox.Contacts;

var newContact = {
  readOnly: true,
  name: ["name"],
  honorificPrefix: ["honorificPrefix"],
  givenName: ["givenName"],
  additionalName: ["additionalName"],
  familyName: ["familyName"],
  honorificSuffix: ["honorificSuffix"],
  nickname: ["nickname"],
  email: [{
      value: 'email1@my_mail_server.com',
      type: "work" },
    {
      value: 'email2@my_mail_server.com',
      type: "home" }],
  url: [{
      value: 'http://www.my_company.com',
      type: "work" }, 
    {
      value: 'http://www.my_private_site.net',
      type: "home" }],
  adr: [{
      type: "work",
      streetAddress: "streetAddress",
      postalCode: "11-222" },
    {
      type: "home",
      streetAddress: "streetAddress2",
      postalCode: "11-333" }],
  tel: [{
      type: "work",
      value: "123456789" },
    {
      type: "home",
      value: "987654321" }],
  org: ["Organization"],
  jobTitle: ["jobTitle"],
  bday: JSON.stringify(new Date()),
  note: ["This is a note."],
  anniversary: JSON.stringify(new Date())
};

var listener = {
  'onSuccess' : function(contact) {
    console.log("Contact successfully saved in device : " + JSON.stringify(contact)); },
  'onFailure' : function(error) {
    console.log("Error while saving contact. Error : " + error.code + " ," + error.description); }
};

contacts.save(newContact, listner);

Contacts methods