Contacts

The Contacts API provides access to read, write, or select device contacts.

Usage
//Create new contact
var myContact = Contacts.create();
myContact.name = new ContactName(null, 'Doe', 'John');
myContact.phoneNumbers = [new ContactField('home', '123456789',true)];
myContact.save()
.then(()=> {
    console.log("Contact saved");
})
.catch((e)=> {
    console.error('Unable to save contact:', e);
});

...

//Find contacts
var options = new ContactFindOptions();
options.filter = "John";
options.multiple = true;

var fields = ["displayName", "phoneNumbers"];

Contacts.find(fields, options)
.then((result)=> {
    console.log(result);
    for (var i = 0; i < result.length; i++) {
        for (var j = 0; j < result[i].phoneNumbers.length; j++) {
            console.log("Pref: "    + result[i].phoneNumbers[j].pref + "\n" +
                        "Type: "    + result[i].phoneNumbers[j].type + "\n" +
                        "Value: "   + result[i].phoneNumbers[j].value );
        }
    }
    
})
.catch((e)=> {
    console.error('Unable to find contact:', e);
});
//Create new contact
var myContact = window.Contacts.create();
myContact.name = new window.ContactName(null, "Doe", "John");
myContact.phoneNumbers = [
    new window.ContactField("home", "123456789", true),
];
myContact
    .save()
    .then(() => {
        console.log("Contact saved");
    })
    .catch((e) => {
        console.error("Unable to save contact:", e);
    });

...

var options = new window.ContactFindOptions();
options.filter = "John";
options.multiple = true;

var fields = ["displayName", "phoneNumbers"];

window.Contacts.find(fields, options)
    .then((result) => {
        console.log(result);
        for (var i = 0; i < result.length; i++) {
            for (var j = 0; j < result[i].phoneNumbers.length; j++) {
                console.log(
                    "Pref: " +
                    result[i].phoneNumbers[j].pref +
                    "\n" +
                    "Type: " +
                    result[i].phoneNumbers[j].type +
                    "\n" +
                    "Value: " +
                    result[i].phoneNumbers[j].value
                );
            }
        }
    })
    .catch((e) => {
        console.error("Unable to find contact:", e);
    });
//Create new contact
var myContact = window.Contacts.create();
myContact.name = new window.ContactName(null, "Doe", "John");
myContact.phoneNumbers = [
    new window.ContactField("home", "123456789", true),
];
myContact
    .save()
    .then(() => {
        console.log("Contact saved");
    })
    .catch((e) => {
        console.error("Unable to save contact:", e);
    });

...

var options = new window.ContactFindOptions();
options.filter = "John";
options.multiple = true;

var fields = ["displayName", "phoneNumbers"];

window.Contacts.find(fields, options)
    .then((result) => {
        console.log(result);
        for (var i = 0; i < result.length; i++) {
            for (var j = 0; j < result[i].phoneNumbers.length; j++) {
                console.log(
                    "Pref: " +
                    result[i].phoneNumbers[j].pref +
                    "\n" +
                    "Type: " +
                    result[i].phoneNumbers[j].type +
                    "\n" +
                    "Value: " +
                    result[i].phoneNumbers[j].value
                );
            }
        }
    })
    .catch((e) => {
        console.error("Unable to find contact:", e);
    });
//Create new contact
var myContact = (<any>window).Contacts.create();
myContact.name = new (<any>window).ContactName(null, "Doe", "John");
myContact.phoneNumbers = [
    new (<any>window).ContactField("home", "123456789", true),
];
myContact
    .save()
    .then(() => {
        console.log("Contact saved");
    })
    .catch((e) => {
        console.error("Unable to save contact:", e);
    });

...

var options = new (<any>window).ContactFindOptions();
options.filter = "John";
options.multiple = true;

var fields = ["displayName", "phoneNumbers"];

(<any>window).Contacts.find(fields, options)
    .then((result) => {
        console.log(result);
        for (var i = 0; i < result.length; i++) {
            for (var j = 0; j < result[i].phoneNumbers.length; j++) {
                console.log(
                "Pref: " +
                result[i].phoneNumbers[j].pref +
                "\n" +
                "Type: " +
                result[i].phoneNumbers[j].type +
                "\n" +
                "Value: " +
                result[i].phoneNumbers[j].value
                );
            }
        }
    })
    .catch((e) => {
        console.error("Unable to find contact:", e);
    });
//Create new contact
var myContact = window.Contacts.create();
myContact.name = new window.ContactName(null, "Doe", "John");
myContact.phoneNumbers = [
    new window.ContactField("home", "123456789", true),
];
myContact
    .save()
    .then(() => {
        console.log("Contact saved");
    })
    .catch((e) => {
        console.error("Unable to save contact:", e);
    });
                      
...

var options = new window.ContactFindOptions();
options.filter = "John";
options.multiple = true;

var fields = ["displayName", "phoneNumbers"];

window.Contacts.find(fields, options)
    .then((result) => {
        console.log(result);
        for (var i = 0; i < result.length; i++) {
            for (var j = 0; j < result[i].phoneNumbers.length; j++) {
                console.log(
                    "Pref: " +
                    result[i].phoneNumbers[j].pref +
                    "\n" +
                    "Type: " +
                    result[i].phoneNumbers[j].type +
                    "\n" +
                    "Value: " +
                    result[i].phoneNumbers[j].value
                );
            }
        }
    })
    .catch((e) => {
        console.error("Unable to find contact:", e);
    });

Table of Contents

Classes

Contacts
create
 
create(properties: object): Contact

This method creates a new contact, but it does not persist the contact to device storage. To persist the contact to device storage, invoke contact.save().


PARAMETERS
properties: object an object whose properties will be examined to create a new Contact

RETURN
returns: Contact
PERMISSIONS

This method requires CONTACTS Permission set on Fawi Office - publish settings.

find
 
find(fields: string[], options: ContactFindOptions): Promise<Contact[]>

Return a promise that resolves with the array of Contact matching search criteria.


PARAMETERS
fields: string[] supported values for this parameter are enumerated ContactFieldType object or use ["*"] to searches all contact fields
options: ContactFindOptions that can be applied to contact searching

RETURN
returns: Promise<Contact[]>
PERMISSIONS

This method requires CONTACTS Permission set on Fawi Office - publish settings.

pickContact
 
pickContact(): Promise<Contact>

This function picks contact from phone using contact picker UI and returns a promise that resolves with the selected Contact object.


RETURN
returns: Promise<Contact>
PERMISSIONS

This method requires CONTACTS Permission set on Fawi Office - publish settings.

Contact

Contains information about a single contact defined by the interface Contact.

clone
 
clone(): Contact

Creates a deep copy of this Contact. With the contact ID set to null.


RETURN
returns: Contact
PERMISSIONS

This method requires CONTACTS Permission set on Fawi Office - publish settings.

remove
 
remove(): Promise<any>

Removes contact from device storage.


RETURN
returns: Promise<any>
PERMISSIONS

This method requires CONTACTS Permission set on Fawi Office - publish settings.

save
 
save(): Promise<any>

Persists contact to device storage.


RETURN
returns: Promise<any>
PERMISSIONS

This method requires CONTACTS Permission set on Fawi Office - publish settings.

Interfaces Used

Contact

 
Contact {    
    id : string; //unique identifier, should only be set by native code
    displayName : string; //name of this Contact, suitable for display to end users
    name : ContactName; //an object containing all components of a persons name
    nickname : string; //casual name by which to address the contact
    phoneNumbers : ContactField[]; //array of phone numbers
    emails : ContactField[]; //array of email addresses
    addresses : ContactAddress[]; //array of addresses
    ims : ContactField[]; //instant messaging user ids
    organizations : ContactOrganization[];
    birthday : string; //contact's birthday 
    note : string; //user notes about contact 
    photos : ContactField[]; //array of the contact's photos 
    categories : ContactField[]; //array of all the user-defined categories associated with the contact 
    urls : ContactField[];  //contact's web sites 
}

ContactAddress

 
ContactAddress {
    id? : string; //unique identifier, should only be set by native code
    pref? : boolean; //set to true if this ContactAddress contains the user's preferred value
    type? : string; //a string indicating what type of field this is
    formatted? : string; //full address formatted for display
    streetAddress? : string; //full street address
    locality? : string; //city or locality
    region? : string; //state or region
    postalCode? : string; //zip code or postal code
    country? : string; //country name
}

ContactField

 
ContactField {
    id? : string; //unique identifier, should only be set by native code
    type? : string; //a string indicating what type of field this is
    value? : string; //value of the field, such as a phone number or email address
    pref? : boolean; //set to true if this ContactField contains the user's preferred value
}

ContactName

 
ContactName {
    formatted? : string; //complete name of the contact
    familyName? : string; //contact's family name
    givenName? : string; //contact's given name
    middleName? : string; //contact's middle name
    honorificPrefix? : string; //contact's prefix (example Mrs. or Eng.)
    honorificSuffix? : string; //contact's suffix (example Esq.)
}

ContactOrganization

 
ContactOrganization {
    id? : string; //unique identifier, should only be set by native code
    pref? : boolean; //set to true if this ContactOrganization contains the user's preferred value
    type? : string; //a string that indicates what type of field this is
    name? : string; //name of the organizatio
    department? : string; //department the contract works for
    title? : string; //contact's title at the organization
}

ContactFindOptions

 
ContactFindOptions {
    filter? : string; //used to match contacts against
    multiple? : boolean; //used to determine if more than one contact should be returned
    desiredFields? : string[]; //Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields
    hasPhoneNumber? : boolean; //used to filter the search and only return contacts that have a phone number informed
}

Enumeration

ContactFieldType

 
enum ContactFieldType{
    addresses:      "addresses",
    birthday:       "birthday",
    categories:     "categories",
    country:        "country",
    department:     "department",
    displayName:    "displayName",
    emails:         "emails",
    familyName:     "familyName",
    formatted:      "formatted",
    givenName:      "givenName",
    honorificPrefix: "honorificPrefix",
    honorificSuffix: "honorificSuffix",
    id:             "id",
    ims:            "ims",
    locality:       "locality",
    middleName:     "middleName",
    name:           "name",
    nickname:       "nickname",
    note:           "note",
    organizations:  "organizations",
    phoneNumbers:   "phoneNumbers",
    photos:         "photos",
    postalCode:     "postalCode",
    region:         "region",
    streetAddress:  "streetAddress",
    title:          "title",
    urls:           "urls"
}

ContactError

 
enum ContactError{
    UNKNOWN_ERROR : 0,
    INVALID_ARGUMENT_ERROR : 1,
    TIMEOUT_ERROR : 2,
    PENDING_OPERATION_ERROR : 3,
    IO_ERROR : 4,
    NOT_SUPPORTED_ERROR : 5,
    OPERATION_CANCELLED_ERROR : 6,
    PERMISSION_DENIED_ERROR : 20
}