Contact

The Contact object represents a contact in the device PIM. It can be obtained by calling blackberry.pim.contacts.create() or blackberry.pim.contacts.find()


Learning Resources:

Sample - Working with Contacts Sample that demonstrates how to use the BlackBerry Contacts API [BlackBerry Community Samples on GitHub].

Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
clone           Y 
remove           Y 
save           Y 
activities           Y 
addresses           Y 
anniversary           Y 
birthday           Y 
categories           Y 
displayName           Y 
emails           Y 
favorite           Y 
faxNumbers           Y 
id           Y 
ims           Y 
name           Y 
news           Y 
nickname           Y 
note           Y 
organizations           Y 
pagerNumbers           Y 
phoneNumbers           Y 
photos           Y 
ringtone           Y 
socialNetworks           Y 
sourceAccounts           Y 
urls           Y 
videoChat           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

blackberry.pim.contacts.Contact clone ()


Returns a new Contact object that is a deep copy of the calling object, with the id property set to null.


Supported Platforms
 - BlackBerry 10

void remove (onRemoveSuccess : function, onRemoveError : function)


Removes the contact from the device contacts database. An error callback is called with a blackberry.pim.contacts.ContactError object if the removal is unsuccessful.


Supported Platforms
 - BlackBerry 10


Parameters
onRemoveSuccess The callback function that will be invoked when the contact is removed successfully.
onRemoveError The callback function that will be invoked when the contact cannot be removed.

error: The blackberry.pim.contacts.ContactError object which contains the error code. Possible errors are: permission denied error (if access_pimdomain_contacts is not specified) or illegal arguments error (if mandatory parameters are missing or invalid).

void save (onSaveSuccess : function, onSaveError : function)


Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists.


Supported Platforms
 - BlackBerry 10


Parameters
onSaveSuccess The callback function that will be invoked when the contact is saved successfully.

contact: The Contact object.
onSaveError The callback function that will be invoked when the contact cannot be saved. 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.

Properties

readonly blackberry.pim.contacts.ContactActivity[] activities


An array of the contact's latest activities.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactAddress[] addresses


An array of all the contact's addresses.


Supported Platforms
 - BlackBerry 10

Date anniversary


The anniversary of the contact.


Supported Platforms
 - BlackBerry 10

Date birthday


The birthday of the contact.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] categories


An array of all the contacts user defined categories.


Supported Platforms
 - BlackBerry 10

String displayName


The name of this Contact, suitable for display to end-users.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] emails


An array of all the contact's email addresses.
Possible types: HOME, WORK, OTHER


Supported Platforms
 - BlackBerry 10

Boolean favorite


Whether this contact is a favorite.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] faxNumbers


An array of all the contact's fax numbers.
Possible types: HOME, WORK, DIRECT, OTHER


Supported Platforms
 - BlackBerry 10

readonly String id


A globally unique identifier.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] ims


An array of all the contact's IM addresses.
Possible types: BbmPin, Aim, Aliwangwang, GoogleTalk, Sametime, Icq, Irc, Jabber, MsLcs, Msn, Qq, Skype, YahooMessenger, YahooMessengerJapan


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactName name


An object containing all components of a person's name.


Supported Platforms
 - BlackBerry 10

readonly blackberry.pim.contacts.ContactNews[] news


An array of the contact's latest online news.


Supported Platforms
 - BlackBerry 10

String nickname


A casual name to address the contact by.


Supported Platforms
 - BlackBerry 10

String note


A note about the contact.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactOrganization[] organizations


An array of all the contact's organizations.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] pagerNumbers


An array of all the contact's pager numbers.
Possible types: HOME, WORK, OTHER


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] phoneNumbers


An array of all the contact's phone numbers.
Possible types: HOME, WORK, MOBILE, OTHER


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactPhoto[] photos


An array of the contact's photos.


Supported Platforms
 - BlackBerry 10

String ringtone


Ringtone for the contact.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] socialNetworks


An array of the contact's social networks.
Possible types: LinkedIn, Facebook, Twitter, Gist


Supported Platforms
 - BlackBerry 10

readonly blackberry.pim.contacts.ContactAccount[] sourceAccounts


Retrieves a list of the accounts of the sources for this Contact.
Contacts can be merged from multiple accounts to form a single contact. For example, contacts might be merged from a personal account and a work account. If the same contact exists in both accounts, the contact information is merged into a single contact that includes all of the information from both accounts. This function returns all of the accounts that are sources for this contact.


Supported Platforms
 - BlackBerry 10

blackberry.pim.contacts.ContactField[] urls


An array of web pages associated to the contact.
Possible types: blog, resume, portfolio, personal, company, other


Supported Platforms
 - BlackBerry 10

String[] videoChat


An array of the contact's video chat IDs


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:05 GMT-0500 (EST)