|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface BlackBerryContactList
Contains the functionality for the BlackBerry-specific implementation of a contact list.
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.
Nested Class Summary | ||
---|---|---|
|
static interface |
BlackBerryContactList.AddressTypes
Describes the various address types supported by the BlackBerryContactList.choose(javax.microedition.pim.Contact, int, boolean) method. |
Field Summary | ||
---|---|---|
|
static int |
SEARCH_CONTACTS
Passed to items() and itemsByPhoneNumber() to indicate that the returned enumeration should contain
only Contact objects. |
|
static int |
SEARCH_GROUPS
Passed to items() and itemsByPhoneNumber() to indicate that the returned enumeration should contain
BlackBerryContactGroup objects. |
|
static int |
SORT_ORDER_COMPANY
Returned by getSortOrder() to indicate that the items in this BlackBerryContactList
are sorted by company name. |
|
static int |
SORT_ORDER_FIRST_NAME
Returned by getSortOrder() to indicate that the items in this BlackBerryContactList
are sorted by first name. |
|
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 | ||
---|---|---|
|
void |
addListener(PIMListListener listener,
boolean includeGroups)
Adds a listener to this contact list. |
|
PIMItem |
choose()
Launches the contacts application so that the user can pick a contact. |
|
Contact |
choose(Contact previous,
int type,
boolean allowCrossService)
Deprecated. Use BlackBerryContactList.choose() instead. |
|
BlackBerryContact |
getByUID(String uid)
Finds a contact by its UID. |
|
PIMItem |
getByUID(String uid,
int searchType)
Finds a contact and/or contact group by its UID. |
|
int |
getSortOrder()
Returns the expected order of the results of a call to ContactList.items() . |
|
Enumeration |
items(int searchType)
Returns an enumeration of all items of the requested type in this BlackBerryContactList . |
|
Enumeration |
items(String matching,
int searchType)
Returns an enumeration of all items that match the fields contained within a specified string. |
|
Enumeration |
itemsByName(String matching)
Returns an enumeration of all items whose name field matches the specified string. |
|
Enumeration |
itemsByName(String matching,
int searchType)
Returns an enumeration of all items whose name field matches the specified string. |
|
Enumeration |
itemsByName(Contact matching)
Returns an enumeration of all items whose name field matches the name field in the specified contact. |
|
Enumeration |
itemsByPhoneNumber(String matching)
Returns an enumeration of all contacts whose phone numbers match the specified string. |
|
Enumeration |
itemsByPhoneNumber(String matching,
int searchType)
Returns an enumeration of all contacts whose phone numbers match the specified string. |
|
void |
lookup(String matching,
RemoteLookupListener listener)
Initiates a remote lookup. |
|
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 |
---|
static final int SORT_ORDER_FIRST_NAME
getSortOrder()
to indicate that the items in this BlackBerryContactList
are sorted by first name.
static final int SORT_ORDER_LAST_NAME
getSortOrder()
to indicate that the items in this BlackBerryContactList
are sorted by last name.
static final int SORT_ORDER_COMPANY
getSortOrder()
to indicate that the items in this BlackBerryContactList
are sorted by company name.
static final int SEARCH_CONTACTS
items()
and itemsByPhoneNumber()
to indicate that the returned enumeration should contain
only Contact
objects.
This can be combined with SEARCH_GROUPS
using the | operator.
static final int SEARCH_GROUPS
items()
and itemsByPhoneNumber()
to indicate that the returned enumeration should contain
BlackBerryContactGroup
objects.
This can be combined with SEARCH_CONTACTS
using the | operator.
Method Detail |
---|
void lookup(String matching, RemoteLookupListener listener) throws IllegalArgumentException
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.
matching
- String used for matching fields.listener
- Remote lookup listener.
IllegalArgumentException
- If listener
is null
.BlackBerryContactList.lookup(Contact, RemoteLookupListener)
void lookup(Contact matching, RemoteLookupListener listener) throws IllegalArgumentException
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.
matching
- Contact used for matching fields.listener
- Remote lookup listener.
IllegalArgumentException
- If listener
is null
.BlackBerryContactList.lookup(String, RemoteLookupListener)
Contact choose(Contact previous, int type, boolean allowCrossService)
BlackBerryContactList.choose()
instead.
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
.
PIMItem choose()
PIMItem
for the Contact
or BlackBerryContactGroup
selected by the user,
null
if user did not make a selection.Enumeration itemsByName(String matching) throws PIMException
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".
matching
- The string used for the name field; the empty string matches all
contacts in the list and is identical to invoking PIMList.items()
.
PIMItems
.
PIMException
- if an error occurs with the list, or if the
list has already been closed.Enumeration itemsByName(Contact matching) throws PIMException
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".
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()
.
PIMItems
.
PIMException
- if an error occurs with the list, or if the
list has already been closed.int getSortOrder()
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.
BlackBerryContactList.SORT_ORDER_FIRST_NAME
, BlackBerryContactList.SORT_ORDER_LAST_NAME
,
or BlackBerryContactList.SORT_ORDER_COMPANY
.Enumeration items(int searchType) throws PIMException
BlackBerryContactList
.
searchType
- One or a combination of BlackBerryContactList.SEARCH_CONTACTS
or BlackBerryContactList.SEARCH_GROUPS
.
PIMException
- if the list is closed.Enumeration items(String matching, int searchType) throws PIMException
The enumeration will contain items with fields containing the
String
argument.
The matching algorithm works as follows:
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".
matching
- The string used for matching fields.searchType
- One or a combination of BlackBerryContactList.SEARCH_CONTACTS
or BlackBerryContactList.SEARCH_GROUPS
.
PIMItems
.
PIMException
- if an error occurs with the list, or if the
list has already been closed.Enumeration itemsByName(String matching, int searchType) throws PIMException
Contact
items,
Name field is matched for BlackBerryContactGroup
items.
The matching algorithm works as follows:
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".
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
.
PIMItems
.
PIMException
- if an error occurs with the list, or if the
list has already been closed.void addListener(PIMListListener listener, boolean includeGroups)
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.
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.
NullPointerException
- if listener
is null
.BlackBerryContact getByUID(String uid) throws PIMException
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
).
uid
- The UID for which to search; may be null
, in which case this method
will behave as if the UID was not found.
BlackBerryContact
object is returned; otherwise, returns null
.
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.BlackBerryContactList.getByUID(String, int)
,
BlackBerryContactList.SEARCH_CONTACTS
PIMItem getByUID(String uid, int searchType) throws PIMException
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
.
Contact
or BlackBerryContactGroup
object is returned, respectively,
provided that its type is included in the specified searchType
; otherwise,
returns null
.
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.BlackBerryContactList.SEARCH_CONTACTS
,
BlackBerryContactList.SEARCH_GROUPS
Enumeration itemsByPhoneNumber(String matching) throws PIMException
PIMItem
,
which you can cast to BlackBerryContact
.
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.
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.Enumeration itemsByPhoneNumber(String matching, int searchType) throws PIMException
PIMItem
.
Use instanceof
to determine the type of the returned object, which can be either BlackBerryContact
or BlackBerryContactGroup
.
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
.
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.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.