SHOW Signed
 

net.rim.blackberry.api.pdap
Interface BlackBerryContactList

All Superinterfaces:
BlackBerryPIMList, ContactList, PIMList

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:
JDE 4.0.0

Inner Class Summary
 Category: Signed static interface BlackBerryContactList.AddressTypes
          Describes the various address types supported by the 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
 
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 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(Contact matching)
          Returns an enumeration of all items whose name field matches the name field in specified Contact.
 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  void lookup(Contact matching, RemoteLookupListener listener)
          Initiates a remote lookup.
 Category: Signed  void lookup(String 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, isFieldLabelSettable, removeListener, setFieldLabel
 

Field Detail

SEARCH_CONTACTS

public 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.
Since:
JDE 4.2.0
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.

SEARCH_GROUPS

public 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.
Since:
JDE 4.2.0
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.

SORT_ORDER_COMPANY

public static final int SORT_ORDER_COMPANY
Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by company name.
Since:
JDE 4.1.0
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.

SORT_ORDER_FIRST_NAME

public static final int SORT_ORDER_FIRST_NAME
Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by first name.
Since:
JDE 4.1.0
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.

SORT_ORDER_LAST_NAME

public static final int SORT_ORDER_LAST_NAME
Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by last name.
Since:
JDE 4.1.0
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.
Method Detail

addListener

public 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 correspoding 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.
Since:
JDE 4.2.0
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.

choose

public PIMItem choose()
Launches the address book so that the user can pick an address.
Returns:
PIMItem for the Contact or BlackBerryContactGroup selected by the user.
Since:
JDE 4.2.1
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.

choose

public Contact choose(Contact previous,
                      int type,
                      boolean allowCrossService)
Deprecated. Use 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.
Since:
JDE 4.0.0
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.

getByUID

public 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.
Since:
JDE 4.6.0
See Also:
getByUID(String, int), 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.

getByUID

public 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.
Since:
JDE 4.6.0
See Also:
SEARCH_CONTACTS, 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.

getSortOrder

public int getSortOrder()
Returns the expected order of the results of a call to ContactList.items().
Returns:
One of SORT_ORDER_FIRST_NAME, SORT_ORDER_LAST_NAME or SORT_ORDER_COMPANY.
Since:
JDE 4.1.0
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.

items

public 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.
Since:
JDE 4.2.0
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.

items

public 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:

  • Individual words are defined locale specific and are case insensitive. For fields that contain string data values, a match is found if the specified search string is found anywhere within a string of a PIMItem's data field. For example, the search string "name" will be found within the field "Contact Name" and "First NAME", as well as within the field "lastname".
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.
Since:
JDE 4.2.0
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.

itemsByName

public 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:

  • Individual words are defined locale specific and are case insensitive. For the NAME_FAMILY and NAME_GIVEN elements of the NAME field, a match is found if the specified search string is a prefix of a word in the Contact.NAME field. For example, the search string "name" will be found within the field "Contact Name" and "First NAME", but not within the field "lastname".
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.
Since:
JDE 4.1.0
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.

itemsByName

public 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:

  • Individual words are defined locale specific and are case insensitive. A match is found if the specified search string is a prefix of a word in the Contact.NAME field. For example, the search string "name" will be found within the field "Contact Name" and "First NAME", but not within the field "lastname".
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.
Since:
JDE 4.1.0
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.

itemsByName

public 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:

  • Individual words are defined locale specific and are case insensitive. A match is found if the specified search string is a prefix of a word in the Contact.NAME field. For example, the search string "name" will be found within the field "Contact Name" and "First NAME", but not within the field "lastname".
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.
Since:
JDE 4.2.0
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.

lookup

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

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

Parameters:
matching - Contact used for matching fields.
listener - Remote lookup listener.
Throws:
IllegalArgumentException - If you provide a bad parameter.
Since:
JDE 4.0.0
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.

lookup

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

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

Parameters:
matching - String used for matching fields.
listener - Remote lookup listener.
Throws:
IllegalArgumentException - If you provide a bad parameter.
Since:
JDE 4.0.0
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.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.