|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface ContactsListView
A contact list is the collection of all contacts managed by a contact manager.
Within a contact list, each contact is assigned a numeric identifier,
that is unique within the contact list.
The identifier for each contact is assigned by the containing contact list
and is only significant within the parent contact manager.
An object that realizes the ContactsListView
interface represents a contact list.
It represents the same contacts list since its creation, during its whole lifetime.
Each ContactsListView
instance provides an independent enumeration scheme
to enumerate all contacts that belong to the list, or a subset of them defined by
specified filtering criteria.
ContactsListView
instances also provide a factory method to create an instance
of the ContactView
interface.
Multiple ContactsListView
instances may be created by the same or different
applications. Although they may represent the same contacts list, each of them has its
own state.
This particularly applies to the current enumeration progress, which is specific to
each instance.
Method Summary | |
---|---|
int |
addContact(ContactView contactView)
Adds a contact to the contacts list. |
ContactView |
createContactViewInstance()
Factory method used to create an instance of the ContactView interface. |
int |
getNumberOfContacts()
Returns the number of contacts in the contacts list. |
boolean |
hasMoreContacts()
Checks if there are more contacts in the current contact enumeration. |
void |
removeContact(int contactIdentifier)
Removes a contact from the contacts list. |
void |
selectContact(ContactView contactView,
int contactIdentifier)
Binds a ContactView instance to the contact that matches the provided
contactIdentifier . |
int |
selectNextContact(ContactView contactView)
Binds a ContactView instance with the next contact in the current enumeration. |
void |
startEnumeration()
Starts a new enumeration of all contacts in the list. |
void |
startEnumeration(short type,
int attributesMask,
byte[] pattern,
short patternOffset,
short patternLength)
Starts a new enumeration of contacts that match specific criteria. |
Method Detail |
---|
ContactView createContactViewInstance()
Factory method used to create an instance of the ContactView
interface.
The instance is initially created in the DESELECTED state.
See the description of the ContactView
interface for detailed information
about its complete life cycle.
At its creation, the ContactView
instance, is readily setup with the list of
fields specified in the field descriptors list associated to the contact manager related to
the contacts list instance that created it.
The new instance is owned by the calling application.
ContactView
instancevoid startEnumeration()
Starts a new enumeration of all contacts in the list.
ContactsListView
instance can process one enumeration at a time.selectNextContact()
.
void startEnumeration(short type, int attributesMask, byte[] pattern, short patternOffset, short patternLength)
Starts a new enumeration of contacts that match specific criteria.
Only contacts, for which a field matches a specific type, attributes and a value pattern,
will participate in the enumeration.
The type, attributes and value pattern matching rules are described in the ContactView
interface's description.
A contact participates in the enumeration if at least one of its fields matches the
type, attributes and value pattern specified.
In addition to the filtering mechanism described here, all requirements of the method
startEnumeration()
apply to this method.
type
- the type of the field searched forattributesMask
- mask of attributes of fields searched forpattern
- pattern of field values to look for; if null, all field values are acceptedpatternOffset
- pattern OffsetpatternLength
- pattern lengthboolean hasMoreContacts()
Checks if there are more contacts in the current contact enumeration.
true
if there is at least one more contact in the current enumerationint selectNextContact(ContactView contactView)
Binds a ContactView
instance with the next contact in the current enumeration.
The order in which the contacts are enumerated is unspecified.
After successful operation, the ContactView
instance is in the SELECTED state,
and is bound to the next contact in the current enumeration.
If the current enumeration has not been started, or already reached its end,
or after unsuccessful operation for any reason, the ContactView
instance
is in DESELECTED state.
contactView
- ContactView
instance that should represent the next contact in the enumeration.
void selectContact(ContactView contactView, int contactIdentifier)
Binds a ContactView
instance to the contact that matches the provided
contactIdentifier
.
After successful operation, the ContactView
instance is in SELECTED state,
and is the contact specified is selected.
After unsuccessful operation, the ContactView
instance is in DESELECTED state.
contactView
- ContactView
instance that should represent the next contact that
matches the identifier.contactIdentifier
- contact identifier of contact to get
uicc.contactmanager.ContactManagerException
:
- WRONG_IDENTIFIER
if the list contains no contact with the
contactIdentifier
provided.void removeContact(int contactIdentifier)
Removes a contact from the contacts list.
If the removed contact also belongs to one or more groups, it is also removed from these groups.
This method fails in the following cases:
ContactView
instance is currently bound to the removed contact.ContactsListView
or GroupView
related the same contact manager, other than the method's
target.
contactIdentifier
- identifier of the contact to be removed from the list
uicc.contactmanager.ContactManagerException
- with the following reasons:
WRONG_IDENTIFIER
if contactIdentifier
does not identify any contact in the contacts list.ITEM_SELECTED
if the contact to be removed is currently selected
by a ContactView
.ENUMERATION_IN_PROGRESS
if a conflicting enumeration is
currently in progress.int addContact(ContactView contactView)
Adds a contact to the contacts list.
The contact to be added is represented by an instance of ContactView
that is in DESELECTED state, whose fields have been set to the appropriate values.
When a contact is added to a contacts list, any enumeration over the same contacts list currently in progress may or may not include the new contact, depending on the implementation.
After successful completion of this operation, the ContactView
instance is
in SELECTED state, and is bound to the newly created contact.
contactView
- A ContactView
instance with FieldView
values set according
to the contact to be added.
int getNumberOfContacts()
Returns the number of contacts in the contacts list.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |