net.rim.blackberry.api.pdap
Interface BlackBerryContactList

All Superinterfaces:
ContactList, PIMList, BlackBerryPIMList

public interface BlackBerryContactList
extends ContactList, BlackBerryPIMList

Contains the functionality for the BlackBerry-specific implementation of a contact list.

Using Contact Groups

To retrieve BlackBerryContactGroup objects, invoke any of the items() methods that take an integer search type argument, and pass a value that is bitwise-ored with the constant BlackBerryContactList.SEARCH_GROUPS. The standard items() methods defined in PIMList will return only Contact objects.

In the following two examples, list is an instance of BlackBerryContactList.

Invoking

   list.items(BlackBerryContactList.SEARCH_GROUPS)
returns an enumeration over all BlackBerryContactGroup objects, but not BlackBerryContact objects.

Invoking

   list.items(BlackBerryContactList.SEARCH_GROUPS|BlackBerryContactList.SEARCH_CONTACTS)
returns an enumeration over all BlackBerryContactGroup objects and all BlackBerryContact objects.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

Nested Class Summary
Category: Signed static interface BlackBerryContactList.AddressTypes
          Describes the various address types supported by the BlackBerryContactList.choose(javax.microedition.pim.Contact, int, boolean) method.
 
Field Summary
Category: Signed static int SEARCH_CONTACTS
          Passed to items() and itemsByPhoneNumber() to indicate that the returned enumeration should contain only Contact objects.
Category: Signed static int SEARCH_GROUPS
          Passed to items() and itemsByPhoneNumber() to indicate that the returned enumeration should contain BlackBerryContactGroup objects.
Category: Signed static int SORT_ORDER_COMPANY
          Returned by getSortOrder() to indicate that the items in this BlackBerryContactList are sorted by company name.
Category: Signed static int SORT_ORDER_FIRST_NAME
          Returned by getSortOrder() to indicate that the items in this BlackBerryContactList are sorted by first name.
Category: Signed static int SORT_ORDER_LAST_NAME
          Returned by getSortOrder() to indicate that the items in this BlackBerryContactList are sorted by last name.
 
Fields inherited from interface javax.microedition.pim.PIMList
UNCATEGORIZED
 
Fields inherited from interface javax.microedition.pim.PIMList
UNCATEGORIZED
 
Method Summary
Category: Signed  void addListener(PIMListListener listener, boolean includeGroups)
          Adds a listener to this contact list.
Category: Signed  PIMItem choose()
          Launches the contacts application so that the user can pick a contact.
Category: Signed  Contact choose(Contact previous, int type, boolean allowCrossService)
          Deprecated. Use BlackBerryContactList.choose() instead.
Category: Signed  BlackBerryContact getByUID(String uid)
          Finds a contact by its UID.
Category: Signed  PIMItem getByUID(String uid, int searchType)
          Finds a contact and/or contact group by its UID.
Category: Signed  int getSortOrder()
          Returns the expected order of the results of a call to ContactList.items().
Category: Signed  Enumeration items(int searchType)
          Returns an enumeration of all items of the requested type in this BlackBerryContactList.
Category: Signed  Enumeration items(String matching, int searchType)
          Returns an enumeration of all items that match the fields contained within a specified string.
Category: Signed  Enumeration itemsByName(String matching)
          Returns an enumeration of all items whose name field matches the specified string.
Category: Signed  Enumeration itemsByName(String matching, int searchType)
          Returns an enumeration of all items whose name field matches the specified string.
Category: Signed  Enumeration itemsByName(Contact matching)
          Returns an enumeration of all items whose name field matches the name field in the specified contact.
Category: Signed  Enumeration itemsByPhoneNumber(String matching)
          Returns an enumeration of all contacts whose phone numbers match the specified string.
Category: Signed  Enumeration itemsByPhoneNumber(String matching, int searchType)
          Returns an enumeration of all contacts whose phone numbers match the specified string.
Category: Signed  void lookup(String matching, RemoteLookupListener listener)
          Initiates a remote lookup.
Category: Signed  void lookup(Contact matching, RemoteLookupListener listener)
          Initiates a remote lookup.
 
Methods inherited from interface javax.microedition.pim.ContactList
createContact, importContact, removeContact
 
Methods inherited from interface javax.microedition.pim.PIMList
addCategory, close, deleteCategory, getArrayElementLabel, getAttributeLabel, getCategories, getFieldDataType, getFieldLabel, getName, getSupportedArrayElements, getSupportedAttributes, getSupportedFields, isCategory, isSupportedArrayElement, isSupportedAttribute, isSupportedField, items, items, items, itemsByCategory, maxCategories, maxValues, renameCategory, stringArraySize
 
Methods inherited from interface net.rim.blackberry.api.pdap.BlackBerryPIMList
addListener, getPIMListUID, isFieldLabelSettable, isWirelessSyncCapable, isWirelessSyncEnabled, removeListener, setFieldLabel, size
 
Methods inherited from interface javax.microedition.pim.PIMList
addCategory, close, deleteCategory, getArrayElementLabel, getAttributeLabel, getCategories, getFieldDataType, getFieldLabel, getName, getSupportedArrayElements, getSupportedAttributes, getSupportedFields, isCategory, isSupportedArrayElement, isSupportedAttribute, isSupportedField, items, items, items, itemsByCategory, maxCategories, maxValues, renameCategory, stringArraySize
 



Field Detail

SORT_ORDER_FIRST_NAME

static final int SORT_ORDER_FIRST_NAME
Returned by getSortOrder() to indicate that the items in this BlackBerryContactList are sorted by first name.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

SORT_ORDER_LAST_NAME

static final int SORT_ORDER_LAST_NAME
Returned by getSortOrder() to indicate that the items in this BlackBerryContactList are sorted by last name.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

SORT_ORDER_COMPANY

static final int SORT_ORDER_COMPANY
Returned by getSortOrder() to indicate that the items in this BlackBerryContactList are sorted by company name.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

SEARCH_CONTACTS

static final int SEARCH_CONTACTS
Passed to items() and itemsByPhoneNumber() to indicate that the returned enumeration should contain only Contact objects. This can be combined with SEARCH_GROUPS using the | operator.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

SEARCH_GROUPS

static final int SEARCH_GROUPS
Passed to items() and itemsByPhoneNumber() to indicate that the returned enumeration should contain BlackBerryContactGroup objects. This can be combined with SEARCH_CONTACTS using the | operator.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0


Method Detail

lookup

void lookup(String matching,
            RemoteLookupListener listener)
            throws IllegalArgumentException
Initiates a remote lookup.

The results are passed to your provided RemoteLookupListener's items() method.

The lookup is done in the contact list that is associated with a BlackBerry Enterprise Server (BES) account. It does not matter which contact list instance this method is invoked on as it will do the same thing on all contact lists.

Parameters:
matching - String used for matching fields.
listener - Remote lookup listener.
Throws:
IllegalArgumentException - If listener is null.
See Also:
BlackBerryContactList.lookup(Contact, RemoteLookupListener)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

lookup

void lookup(Contact matching,
            RemoteLookupListener listener)
            throws IllegalArgumentException
Initiates a remote lookup.

The results are passed to your provided RemoteLookupListener's items() method.

The lookup is done in the contact list that is associated with a BlackBerry Enterprise Server (BES) account. It does not matter which contact list instance this method is invoked on as it will do the same thing on all contact lists.

Parameters:
matching - Contact used for matching fields.
listener - Remote lookup listener.
Throws:
IllegalArgumentException - If listener is null.
See Also:
BlackBerryContactList.lookup(String, RemoteLookupListener)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

choose

Contact choose(Contact previous,
               int type,
               boolean allowCrossService)
Deprecated. Use BlackBerryContactList.choose() instead.

Launches the contacts application so that the user can pick a contact.

Parameters:
previous - Contact used as the starting point in the contact list (can be null).
type - One of the address types defined by the BlackBerryContactList.AddressTypes interface.
allowCrossService - If true, permit selection of addresses that use a different service (for example, BWC), otherwise, false.
Returns:
Next contact of provided type after provided starting point.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

choose

PIMItem choose()
Launches the contacts application so that the user can pick a contact. Only entries from this contact list are displayed to the user from which to select.

Returns:
PIMItem for the Contact or BlackBerryContactGroup selected by the user, null if user did not make a selection.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.1

itemsByName

Enumeration itemsByName(String matching)
                        throws PIMException
Returns an enumeration of all items whose name field matches the specified string. Lastname and the firstname fields are matched. The matching algorithm works as follows:

Parameters:
matching - The string used for the name field; the empty string matches all contacts in the list and is identical to invoking PIMList.items().
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - if an error occurs with the list, or if the list has already been closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

itemsByName

Enumeration itemsByName(Contact matching)
                        throws PIMException
Returns an enumeration of all items whose name field matches the name field in the specified contact. Lastname and the firstname fields are matched. The matching algorithm works as follows:

Parameters:
matching - The Contact used for matching fields; if the Contact.NAME field is not set or is set but both Contact.NAME_GIVEN and Contact.NAME_FAMILY are set to null then this method returns all contacts and is identical to invoking PIMList.items().
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - if an error occurs with the list, or if the list has already been closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getSortOrder

int getSortOrder()
Returns the expected order of the results of a call to ContactList.items().

The sort order is a global setting that applies to all contact lists. Therefore, this method will return the same value regardless of which contact list instance it is invoked on. The sort order can be changed by the user in the Options screen of the BlackBerry contacts application.

Returns:
One of BlackBerryContactList.SORT_ORDER_FIRST_NAME, BlackBerryContactList.SORT_ORDER_LAST_NAME, or BlackBerryContactList.SORT_ORDER_COMPANY.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

items

Enumeration items(int searchType)
                  throws PIMException
Returns an enumeration of all items of the requested type in this BlackBerryContactList.

Parameters:
searchType - One or a combination of BlackBerryContactList.SEARCH_CONTACTS or BlackBerryContactList.SEARCH_GROUPS.
Returns:
An enumeration containing all items of the requested type.
Throws:
PIMException - if the list is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

items

Enumeration items(String matching,
                  int searchType)
                  throws PIMException
Returns an enumeration of all items that match the fields contained within a specified string.

The enumeration will contain items with fields containing the String argument.

The matching algorithm works as follows:

Parameters:
matching - The string used for matching fields.
searchType - One or a combination of BlackBerryContactList.SEARCH_CONTACTS or BlackBerryContactList.SEARCH_GROUPS.
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - if an error occurs with the list, or if the list has already been closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

itemsByName

Enumeration itemsByName(String matching,
                        int searchType)
                        throws PIMException
Returns an enumeration of all items whose name field matches the specified string. Lastname and the firstname fields are matched on Contact items, Name field is matched for BlackBerryContactGroup items. The matching algorithm works as follows:

Parameters:
matching - The string used for the name field; the empty string matches all contacts and/or contact groups (as specified by the searchType parameter) in the list and is identical to invoking items(searchType).
searchType - One or a combination of BlackBerryContactList.SEARCH_CONTACTS or BlackBerryContactList.SEARCH_GROUPS.
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - if an error occurs with the list, or if the list has already been closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

addListener

void addListener(PIMListListener listener,
                 boolean includeGroups)
Adds a listener to this contact list.

The includeGroups parameter can be used to specify whether this listener should also receive notification of changes to BlackBerryContactGroup objects. If includeGroups is set to true then the listener will receive change events for BlackBerryContactGroup objects, as well as notifications of any changes made to BlackBerryContact objects in this list. Listeners added using this method with includeGroups set to true should perform an instanceof check on the parameter they are passed before performing a cast on the object.

Calling this method with the includeGroups set to false is equivalent to calling the BlackBerryPIMList.addListener(PIMListListener) method.

Note that the listener will remain associated with the native device database even after the corresponding PIM list has been deleted. To remove the listener use BlackBerryPIMList.removeListener(net.rim.blackberry.api.pdap.PIMListListener). method.

Parameters:
listener - The listener to add.
includeGroups - If true, the listener will be notified about events relating to contact groups, as well as contacts. If false, the listener will be notified only about events relating to contacts.
Throws:
NullPointerException - if listener is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

getByUID

BlackBerryContact getByUID(String uid)
                           throws PIMException
Finds a contact by its UID.

This method returns the object returned from this.getByUID(uid, SEARCH_CONTACTS) if the returned object is an instance of BlackBerryContact. This method returns null if the returned object is null or an instance of a type other than BlackBerryContact (such as BlackBerryContactGroup).

Parameters:
uid - The UID for which to search; may be null, in which case this method will behave as if the UID was not found.
Returns:
If a contact with the specified UID is found in this list then its BlackBerryContact object is returned; otherwise, returns null.
Throws:
PIMException - if an error occurs searching (for example, the list is closed).
SecurityException - if the list was opened in a mode that does not allow reading.
See Also:
BlackBerryContactList.getByUID(String, int), BlackBerryContactList.SEARCH_CONTACTS
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

getByUID

PIMItem getByUID(String uid,
                 int searchType)
                 throws PIMException
Finds a contact and/or contact group by its UID.

Parameters:
uid - The UID for which to search; may be null, in which case this method will behave as if the UID was not found.
searchType - One or a combination of BlackBerryContactList.SEARCH_CONTACTS or BlackBerryContactList.SEARCH_GROUPS.
Returns:
If a contact or contact group with the specified UID is found in this list then its Contact or BlackBerryContactGroup object is returned, respectively, provided that its type is included in the specified searchType; otherwise, returns null.
Throws:
PIMException - if an error occurs searching (for example, the list is closed).
SecurityException - if the list was opened in a mode that does not allow reading.
See Also:
BlackBerryContactList.SEARCH_CONTACTS, BlackBerryContactList.SEARCH_GROUPS
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

itemsByPhoneNumber

Enumeration itemsByPhoneNumber(String matching)
                               throws PIMException
Returns an enumeration of all contacts whose phone numbers match the specified string. Each of the enumeration items is a PIMItem, which you can cast to BlackBerryContact.

Parameters:
matching - A phone number as a String. Formatting is ignored. For example, either "(519)555-0123" or "1-519-555-0123" will match "5195550123". Note that using PIMList.items(PIMItem matching) to look up contacts requires the input to match exactly the phone number of contacts in contact lists.
Returns:
An enumeration containing matched contacts. An empty enumeration is returned if the contact list is empty, a match is not found, the phone number is from a private, unknown or emergency call, or the call is a voice mail or for SIM startup.
Throws:
PIMException - if the list is closed or write only, the device is locked, or the contact list is protected.
IllegalArgumentException - if the phone number is null or zero in length.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

itemsByPhoneNumber

Enumeration itemsByPhoneNumber(String matching,
                               int searchType)
                               throws PIMException
Returns an enumeration of all contacts whose phone numbers match the specified string. The enumeration may contain groups if the lookup is done on the default contact list. Each of the enumeration items is a PIMItem. Use instanceof to determine the type of the returned object, which can be either BlackBerryContact or BlackBerryContactGroup.

Parameters:
matching - A phone number as a String. Formatting is ignored. For example, either "(519)555-0123" or "1-519-555-0123" will match "5195550123". Note that using PIMList.items(PIMItem matching) to look up contacts requires the input to match exactly the phone number of contacts in contact lists.
searchType - One or a combination of BlackBerryContactList.SEARCH_CONTACTS or BlackBerryContactList.SEARCH_GROUPS.
Returns:
An enumeration containing matched contacts (and/or contact groups if the contact list is the default one). An empty enumeration is returned if the contact list is empty, a match is not found, the phone number is from a private, unknown or emergency call, or the call is a voice mail or for SIM startup.
Throws:
PIMException - if the list is closed or write only, the device is locked, or the contact list is protected.
IllegalArgumentException - if the phone number is null or zero in length.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.