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.

Parameters

Name	Description
contact	A JavaScript object containing contact parameters. The object must be compliant with the 2013 definition of the W3C Contacts Manager API specification. 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 Contacts Manager 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 entry that matches the query. The entry is consistent with section 11 of the 2013 definition of the W3C Contacts Manager API specification specification. undefined

onFailure

Name	Description	Return type
onSuccess	A callback function that accepts an entry that matches the query. The entry is consistent with section 11 of the 2013 definition of the W3C Contacts Manager API specification specification.	`undefined`
onFailure	Passed to notify that the process could not be completed. It passes an object that contains a description of an error, as listed in the Constants table of the Contacts article. { code, description }	`undefined`

Passed to notify that the process could not be completed. It passes an object that contains a description of an error, as listed in the Constants table of the Contacts article.

{
  code,
  description
}

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