Contacts

The contacts object provides functions for creating and finding contacts.


Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.pim.contacts.create           Y 
blackberry.pim.contacts.find           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.pim.contacts" />           Y 
Permission Elements (PlayBook and BlackBerry 10+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>access_pimdomain_contacts</rim:permit>
Permits your app to access contacts.

Functions

static blackberry.pim.contacts.Contact blackberry.pim.contacts.create ([properties : Object])


Returns a new Contact object. This method does not persist the Contact object to the device contacts database. To persist the Contact object to the device, invoke the Contact.save method.


Supported Platforms
 - BlackBerry 10


Parameters
properties Optional object literal that specifies the field values for the Contact object. The object should be in the following form (with any number of properties): 
{
    displayName: <display name - String>,
    name: <name - ContactName>,
    nickname: <nickname - String>,
    phoneNumbers: <phone numbers - ContactField[]>,
    emails: <email addresses - ContactField[]>,
    addresses: <addresses - ContactAddress[]>,
    ims: <IM addresses - ContactField[]>,
    organizations: <organization - ContactOrganization[]>,
    birthday: <birthday - Date>,
    note: <note - String>,
    photos: <photos - ContactField[]>,
    categories: <user defined categories - ContactField[]>,
    urls: <web pages - ContactField[]>
}

Code Example: 
function onSaveSuccess(contact) {
    console.log("Contact with id=" + contact.id + " is saved!");
}

function onSaveError(error) {
    console.log("Error saving contact: " + error.code);
}

function createContact() {
    var contacts = blackberry.pim.contacts,
        ContactField = contacts.ContactField,
        name = {},
        workPhone = { type: ContactField.WORK, value: "123-456-789" },
        workEmail = { type: ContactField.WORK, value: "abc@blah.com" },
        homeEmail = { type: ContactField.HOME, value: "hello@me.com" },
        contact;
        
    name.familyName = "Smith";
    name.givenName = "Joe";
    contact = contacts.create({
         "displayName": "Batman",
         "name": name,
         "phoneNumbers": [workPhone],
         "emails": [workEmail, homeEmail]
    });
    contact.save(onSaveSuccess, onSaveError);
}

static void blackberry.pim.contacts.find (contactFields : String[], findOptions : blackberry.pim.contacts.ContactFindOptions, onFindSuccess : function, [onFindError : function])


Queries the device contacts database. The search results are passed to the onFindSuccess callback function specified by the onFindSuccess parameter.


Supported Platforms
 - BlackBerry 10


Parameters
contactFields A String array of contact fields to be used as search qualifier. Only these fields will have values in the resulting Contact objects.
findOptions Options to be applied to the search.
onFindSuccess Success callback function that is invoked with the contacts returned from the contacts database.

contacts: The array of Contact objects from the search.
onFindError Optional error callback function. Invoked when error occurs. Possible errors are: permission denied error (if access_pimdomain_contacts is not specified) or illegal arguments error (if mandatory parameters are missing or invalid).

error: The blackberry.pim.contacts.ContactError object which contains the error code.

Code Example: 
var contacts = blackberry.pim.contacts,
    ContactFindOptions = contacts.ContactFindOptions;

function onFindSuccess(results) {
    console.log("Found " + results.length + " contacts in total");
}

function onFindError(error) {
    console.log("Error: " + error.code);
}

function searchContactsByName() {
    var searchFirstName = {
             "fieldName" : ContactFindOptions.SEARCH_FIELD_GIVEN_NAME,
             "fieldValue" : "John"
        },
        searchLastName = {
             "fieldName" : ContactFindOptions.SEARCH_FIELD_FAMILY_NAME,
             "fieldValue" : "Smith"
        },
        sortOrg = {
             "fieldName" : ContactFindOptions.SORT_FIELD_ORGANIZATION_NAME,
             "desc" : false
        },
        findOptions = {
             filter: [searchFirstName, searchLastName], // filter
             sort: [sortOrg],                           // sort
             limit: 20                                  // limit
        };
    // The first 20 contacts (based on specified sort specs) with given name "John"
    // and family name "Smith" will be returned
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

function listAllContacts() {
    var sort = [{
             "fieldName": ContactFindOptions.SORT_FIELD_FAMILY_NAME,
             "desc": false
        }, {
             "fieldName": ContactFindOptions.SORT_FIELD_GIVEN_NAME,
             "desc": true
        }],
        // no filter - return all contacts
        findOptions = { 
             // sort contacts first by family name (desc), then by given name (asc)
             sort: sort,  
             limit: 20     // limit - return up to 20 contacts
        };
    // The first 20 contacts (based on specified sort specs) will be returned
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

function listAllContactsWithEmptyFindOptions() {
    var findOptions = {};
    
    //Will return all contacts with no particular sort order
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

function findContactErrorMissingFilterValue() {
    var findOptions = {
          filter: [{
                "fieldName": ContactFindOptions.SEARCH_FIELD_GIVEN_NAME,
                "fieldValue": ""
          }, {
                "fieldName": ContactFindOptions.SEARCH_FIELD_FAMILY_NAME,
                "fieldValue": "Smith"
          }],
          sort: [{
                "fieldName": ContactFindOptions.SORT_FIELD_FAMILY_NAME,
                "desc": false
          }, {
                "fieldName": ContactFindOptions.SORT_FIELD_GIVEN_NAME,
                "desc": true
          }],
          limit: 2
       };
    // Error - illegal argument (reason: fieldValue = "" for first search field)
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:36 GMT-0500 (EST)