uicc.contactmanager
Interface ContactsListView

All Known Subinterfaces:
GroupView

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

createContactViewInstance

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.

Returns:
new ContactView instance

startEnumeration

void startEnumeration()

Starts a new enumeration of all contacts in the list.


startEnumeration

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.

Parameters:
type - the type of the field searched for
attributesMask - mask of attributes of fields searched for
pattern - pattern of field values to look for; if null, all field values are accepted
patternOffset - pattern Offset
patternLength - pattern length

hasMoreContacts

boolean hasMoreContacts()

Checks if there are more contacts in the current contact enumeration.

Returns:
true if there is at least one more contact in the current enumeration

selectNextContact

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

Parameters:
contactView - ContactView instance that should represent the next contact in the enumeration.
Returns:
contact identifier, or -1 if the current enumeration reached its end.

selectContact

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.

Parameters:
contactView - ContactView instance that should represent the next contact that matches the identifier.
contactIdentifier - contact identifier of contact to get
Throws:
uicc.contactmanager.ContactManagerException: -
  • with reason WRONG_IDENTIFIER if the list contains no contact with the contactIdentifier provided.

removeContact

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:

Parameters:
contactIdentifier - identifier of the contact to be removed from the list
Throws:
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.

addContact

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.

Parameters:
contactView - A ContactView instance with FieldView values set according to the contact to be added.
Returns:
the new contact's identifier

getNumberOfContacts

int getNumberOfContacts()

Returns the number of contacts in the contacts list.

Returns:
number of contacts