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)
          Launches the address book so that the user can pick an address.
 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)
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.

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