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
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.pim.Contact Y Y Y      Y
blackberry.pim.Contact.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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<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 and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Constructors


Functions


Properties

Date anniversary
Date birthday
void categories
String company
String email1
String email2
String email3
String faxPhone
String firstName
Address homeAddress
String homePhone
String homePhone2
String jobTitle
String lastName
String mobilePhone
String note
String otherPhone
String pagerPhone
String picture
String pin
String title
String uid
String user1
String user2
String user3
String user4
String webpage
Address workAddress
String workPhone
String workPhone2

Constructors

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

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


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
service optional parameter specifying which service to create this contact for. If not provided, the default device service is used.

Code Example:
<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>

Functions

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


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


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
fieldFilter 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 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 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 Optional parameter specifying which service you wish to search for contacts. If not supplied, the default service for contacts will be used.
isAscending 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.

Code Example:
<script type="text/javascript">
  var c = new blackberry.pim.Contact();
  c.firstName = "Tom";
  c.lastName = "Sawyer";
  c.save();
  				
  c.firstName = "Huckleberry";
  c.lastName = "Finn";
  c.save();
				
  var fe = new blackberry.find.FilterExpression("uid", "==", c.uid);
  var res = blackberry.pim.Contact.find(fe); //Returns 1 item array as once you have saved there is a new unique UID. The UID searched was from the last contact saved hence the contact Huckleberry Finn should be the contact retrieved.

<\script>

void remove ()


This method will remove a contact from the PIM storage.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Code Example:
<script type="text/javascript">
  var c = new blackberry.pim.Contact();
  c.firstName = "Mad";
  c.lastName = "Hatter";
  c.save();

  var fe = new blackberry.find.FilterExpression("Hatter", "==", c.lastName);
  var results = blackberry.pim.Contact.find(fe); //Returns 1 item array

  results[0].remove();
<\script>

void save ()


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


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Code Example:
<script type="text/javascript">
  var c = new blackberry.pim.Contact();
  c.firstName = "Tom";
  c.lastName = "Sawyer";
  c.note = "Loves to paint fences";
  c.save();

  var fe = new blackberry.find.FilterExpression("Tom", "==", c.firstName);
  var results = blackberry.pim.Contact.find(fe); //Returns 1 item array

  results[0].note = "Bestfriend is Huck"; 
  results[0].save();
<\script>

void setPicture (picture : Blob)


This function sets the picture for the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
picture The blob object represents the image.

Code Example:
<script type="text/javascript">

  var file1 = "local:///data/pic1.jpg"
  var c = new blackberry.pim.Contact();
  c.firstName = "Huckleberry";
  c.lastName = "Finn";

  function handleOpenedFile(fullPath, blobData) // fullPath variable is part of the expected callback function syntax to access the path of the file. In this particular case you already have it through file1.
  {
      c.setPicture(blobData); 
  }

  blackberry.io.file.readFile(file, handleOpenedFile);
  c.save();

<\script>

Properties

Date anniversary


The date of the contact's anniversary.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Date birthday


The date of the contact's birthday.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

void categories


The list of categories associated to the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String company


Contains the company name of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String email1


Contains the first email of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String email2


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.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String email3


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.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String faxPhone


Contains the fax number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String firstName


Contains the first name of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Address homeAddress


Contains the home address of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String homePhone


Contains the home telephone number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String homePhone2


Contains the second home telephone number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String jobTitle


Contains the job title of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String lastName


Contains the last name of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String mobilePhone


Contains the mobile telephone number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String note


Contains any note or description related to the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String otherPhone


Contains other telephone number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String pagerPhone


Contains the pager number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

readonly String picture


It contains the base64-encoded string of the image object of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String pin


The contact's device PIN.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String title


Contains the title of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

readonly String uid


The unique identifier for this contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String user1


The first user-defined field that contains extra information for the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String user2


The second user-defined field that contains extra information for the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String user3


The third user-defined field that contains extra information for the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String user4


The fourth user-defined field that contains extra information for the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String webpage


Contains the web page URL of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Address workAddress


Contains the work address of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String workPhone


Contains the work telephone number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

String workPhone2


Contains the second work telephone number of the contact.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:35 GMT-0500 (EST)