SHOW Signed

net.rim.blackberry.api.pdap
Interface BlackBerryContactList

All Superinterfaces:

ContactList, PIMList

public interface BlackBerryContactList

extends ContactList

Contains the functionality for the BlackBerry-specific implementation of a ContactList.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Since:

JDE 4.0.0

Inner Class Summary

static interface

BlackBerryContactList.AddressTypes Describes the various address types supported by the choose(javax.microedition.pim.Contact, int, boolean) method.

Field Summary

	static int	SORT_ORDER_COMPANY Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by company name.
	static int	SORT_ORDER_FIRST_NAME Returned by itemsSortOrder to indicate that the items in this BlackBerryContactList are sorted by first name.
	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

	Contact	choose(Contact previous, int type, boolean allowCrossService) Launches the address book so that the user can pick an address.
	int	getSortOrder() Returns the expected order of the results of a call to ContactList.items().
	Enumeration	itemsByName(Contact matching) Returns an enumeration of all items whose name field matches the name field in specified Contact.
	Enumeration	itemsByName(String matching) Returns an enumeration of all items whose name field matches the specified string.
	void	lookup(Contact matching, RemoteLookupListener listener) Initiates a remote lookup.
	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

Field Detail

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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:

• For fields that contain string data values, each individual word is matched for the length of the sentence. Individual words are defined locale specific and are case insensitive. A match is found if the specified search string is found within a string of a PIMItem's data field at the correct element position. For example, the search string "name" will be found within the field "Contact Name" and "First name", but will not be found 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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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:

• For fields that contain string data values, each individual word is matched for the length of the sentence. Individual words are defined locale specific and are case insensitive. A match is found if the specified search string is found within a string of a PIMItem's data field at the correct element position. For example, the search string "name" will be found within the field "Contact Name" and "First name", but will not be found 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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.