Contact

The Contact object represents a contact in the BlackBerry PIM. This object can be created to be used when launching the new contact screen using the invoke API or for direct interaction with the PIM storage itself.

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

View Supported Platform Table

APIOS 5.0OS 6.0OS 7.0PlayBookRipple
blackberry.pim.Contact Y Y Y  Y
find Y Y Y  Y
remove Y Y Y  Y
save Y Y Y  Y
setPicture Y Y Y  Y
anniversary Y Y Y  Y
birthday Y Y Y  Y
categories Y Y Y  Y
company Y Y Y  Y
email1 Y Y Y  Y
email2 Y Y Y  Y
email3 Y Y Y  Y
faxPhone Y Y Y  Y
firstName Y Y Y  Y
homeAddress Y Y Y  Y
homePhone Y Y Y  Y
homePhone2 Y Y Y  Y
jobTitle Y Y Y  Y
lastName Y Y Y  Y
mobilePhone Y Y Y  Y
note Y Y Y  Y
otherPhone Y Y Y  Y
pagerPhone Y Y Y  Y
picture Y Y Y  Y
pin Y Y Y  Y
title Y Y Y  Y
uid Y Y Y  Y
user1 Y Y Y  Y
user2 Y Y Y  Y
user3 Y Y Y  Y
user4 Y Y Y  Y
webpage Y Y Y  Y
workAddress Y Y Y  Y
workPhone Y Y Y  Y
workPhone2 Y Y Y  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 IDOS 5.0OS 6.0OS 7.0PlayBookRipple
<feature id="blackberry.pim.Contact" /> Y Y Y  Y
<feature id="blackberry.pim.Address" /> Y Y Y  Y
<feature id="blackberry.identity" /> Y Y Y  Y
<feature id="blackberry.find" /> Y Y Y  Y

Permission Elements (PlayBook Only)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

blackberry.pim.Contact

blackberry.pim.Contact ([service: blackberry.identity.Service])

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

The Contact object is an instance object, where if a new instance is desired, it must be created using the new keyword.



Parameter Type Description
service blackberry.identity.Service
Optional 		optional parameter specifying which service to create this contact for. If not provided, the default device service is used.

Code Example(s)

<script type="text/javascript"> 
  // Create the contact  
  var contact = new blackberry.pim.Contact();  
  contact.firstName = "John";  
  contact.lastName = "Doe";  
  contact.homePhone = "555-555-5555";  
  contact.save(); 
</script>

find

static Contact[] find([fieldFilter: blackberry.find.FilterExpression], [orderBy: String], [maxReturn: Number], [service: blackberry.identity.Service], [isAscending: Boolean])

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

This function looks up the contacts that match the expression provided.



Parameter Type Description
fieldFilter blackberry.find.FilterExpression
Optional 		Optional parameter that defines the search criteria for the find. If no value is provided the method will return all the contacts on the device.
orderBy String
Optional 		Optional 'orderBy' parameter specifying the field which the results will be sorted by. If 'isAscending' is not supplied or 'isAscending' is true, the sort results will be in an ascending order. If 'isAscending' is false, the sort results will be in a descending order.
maxReturn Number
Optional 		Optional integer parameter specifying the maximum number of results to return from the find. If not supplied or set to -1, it will return all results found.
service blackberry.identity.Service
Optional 		Optional parameter specifying which service you wish to search for contacts. If not supplied, the default service for contacts will be used.
isAscending Boolean
Optional 		optional 'isAscending' parameter specifying whether the sort order is ascending or descending. If not supplied or set to true, the results sorted by the field specified by 'orderBy' will be in an ascending order. If set to false, the sort results will be in a descending order. If no 'orderBy' value is specified, 'isAscending' is neglected.

remove

void remove()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

This method will remove a contact from the PIM storage.


save

void save()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

This method will save the changes made to the contact object.


setPicture

void setPicture(picture : Blob)

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

This function sets the picture for the contact.



Parameter Type Description
picture Blob The blob object represents the image.

Properties:

Property Type Description Supported Platform(s)
anniversary Date The date of the contact's anniversary.
 - BlackBerry OS 5.0+
 - Ripple Emulator
birthday Date The date of the contact's birthday.
 - BlackBerry OS 5.0+
 - Ripple Emulator
categories The list of categories associated to the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
company String Contains the company name of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
email1 String Contains the first email of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
email2 String Contains the second email of the contact. After save() is called, if there is no email1 specified, email2 will replace email1 and email2 will be empty.
 - BlackBerry OS 5.0+
 - Ripple Emulator
email3 String Contains the third email for the contact. After save() is called, if there is no email1 or email2 specified, email3 will replace email1 or email2 and email3 will be empty.
 - BlackBerry OS 5.0+
 - Ripple Emulator
faxPhone String Contains the fax number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
firstName String Contains the first name of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
homeAddress Address Contains the home address of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
homePhone String Contains the home telephone number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
homePhone2 String Contains the second home telephone number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
jobTitle String Contains the job title of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
lastName String Contains the last name of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
mobilePhone String Contains the mobile telephone number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
note String Contains any note or description related to the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
otherPhone String Contains other telephone number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
pagerPhone String Contains the pager number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
picture String
readonly 		It contains the base64-encoded string of the image object of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
pin String The contact's device PIN.
 - BlackBerry OS 5.0+
 - Ripple Emulator
title String Contains the title of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
uid String
readonly 		The unique identifier for this contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
user1 String The first user-defined field that contains extra information for the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
user2 String The second user-defined field that contains extra information for the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
user3 String The third user-defined field that contains extra information for the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
user4 String The fourth user-defined field that contains extra information for the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
webpage String Contains the web page URL of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
workAddress Address Contains the work address of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
workPhone String Contains the work telephone number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
workPhone2 String Contains the second work telephone number of the contact.
 - BlackBerry OS 5.0+
 - Ripple Emulator
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:16 GMT-0500 (EST)