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 ContactList.

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 only return Contact objects.

For example, invoking

   list.items(BlackBerryContactList.SEARCH_GROUPS)
where list is an instance of BlackBerryContactList, will return an enumeration over all BlackBerryContactGroup objects, but not BlackBerryContact objects. Another example is invoking
   list.items(BlackBerryContactList.SEARCH_GROUPS|BlackBerryContactList.SEARCH_CONTACTS)
which will return 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 to indicate that the returned enumeration should contain only Contact objects.
Category: Signed static int SEARCH_GROUPS
          Passed to items to indicate that the returned enumeration should contain BlackBerryContactGroup objects.
Category: Signed static int SORT_ORDER_COMPANY
          Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by company name.
Category: Signed static int SORT_ORDER_FIRST_NAME
          Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by first name.
Category: Signed static int SORT_ORDER_LAST_NAME
          Returned by itemsSortOrder 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 address book so that the user can pick an address.
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 specified Contact.
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 itemsSortOrder 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 itemsSortOrder 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 itemsSortOrder 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 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 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 ContactList that is associated with a BlackBerry Enterprise Server (BES) account. It does not matter which ContactList instance this method is invoked on as it will do the same thing on all ContactLists.

Parameters:
matching - String used for matching fields.
listener - Remote lookup listener.
Throws:
IllegalArgumentException - If you provide a bad parameter.
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 ContactList that is associated with a BlackBerry Enterprise Server (BES) account. It does not matter which ContactList instance this method is invoked on as it will do the same thing on all ContactLists.

Parameters:
matching - Contact used for matching fields.
listener - Remote lookup listener.
Throws:
IllegalArgumentException - If you provide a bad parameter.
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 address book so that the user can pick an address.

Parameters:
previous - Contact used as the starting point in the address book (may be null).
type - One of the address types defined by the BlackBerryContactList.AddressTypes interface.
allowCrossService - If true, permit selection of addresses that will use a different service (ie, BWC etc); otherwise, false.
Returns:
Contact 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 address book so that the user can pick an address. Only entries from this ContactList will be displayed to the user from which to select.

Returns:
PIMItem for the Contact or BlackBerryContactGroup selected by the user; returns 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 - Thrown 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 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 - Thrown 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 ContactLists. Therefore, this method will return the same value regardless of which ContactList instance on which it is invoked. The sort order can be changed by the user in the Options screen of the BlackBerry Address Book application.

Returns:
One of SORT_ORDER_FIRST_NAME, SORT_ORDER_LAST_NAME or 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 SEARCH_CONTACTS or SEARCH_GROUPS.
Returns:
An enumeration containing all items of the requested type.
Throws:
PIMException - Thrown 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 SEARCH_CONTACTS or SEARCH_GROUPS.
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - Thrown 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 SEARCH_CONTACTS or SEARCH_GROUPS.
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - Thrown 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 if this listener should also receive notification of changes to BlackBerryContactGroup objects. If includeGroups is set to true then the listener object 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 the 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 only be notified about events relating to contacts.
Throws:
NullPointerException - if listener==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 or null if the returned object is null or a 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, if not found, returns null.
Throws:
PIMException - if an error occurs searching (eg. 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 - a combination of the SEARCH_ constants indicating which types are candidate for consideration.
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, if not found, returns null.
Throws:
PIMException - if an error occurs searching (eg. 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





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.