uicc.contactmanager
Interface GroupsListView


public interface GroupsListView

A group list is a list of all groups defined for a contact manager.

Within a group list, each group is assigned a unique numeric identifier.
Each group belongs to a unique group list.

GroupsListView instances provide:

The GroupsListView class also provides a factory method to create a GroupView instance.

Multiple GroupsListView instances may be created by the same or different applications. Although they may represent the same groups 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 addGroup(byte[] name, short nameOffset, short nameLength)
           Creates a new group and adds it to the groups list.
 GroupView createGroupViewInstance()
           Factory method used to create a GroupView instance.
 int getNumberOfGroups()
           Returns the number of groups in the groups list.
 boolean hasMoreGroups()
           Checks if there are more groups in the current group enumeration.
 void removeGroup(int groupIdentifier)
           Removes a group from the groups list.
 void selectGroup(GroupView groupView, int groupIdentifier)
           Binds a GroupView instance to a group that matches the provided groupIdentifier.
 int selectNextGroup(GroupView groupView)
           Binds a GroupView instance with the next group in the current enumeration.
 void startEnumeration()
           Starts a new enumeration of all groups in the list.
 void startEnumeration(int contactIdentifier)
           Stars the enumeration of all groups in the groups list, that contain a specific contact.
 

Method Detail

createGroupViewInstance

GroupView createGroupViewInstance()

Factory method used to create a GroupView instance.

The instance is initially created in the DESELECTED state.
See the description of the GroupView interface for detailed information about its complete life cycle.

The new instance is owned by the calling application.

Returns:
new GroupView instance

startEnumeration

void startEnumeration()

Starts a new enumeration of all groups in the list.


startEnumeration

void startEnumeration(int contactIdentifier)

Stars the enumeration of all groups in the groups list, that contain a specific contact.

In addition to the filtering mechanism described here, all requirements of the method startEnumeration() apply to this method.

Parameters:
contactIdentifier - identifier of the contact to look for

hasMoreGroups

boolean hasMoreGroups()

Checks if there are more groups in the current group enumeration.

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

selectNextGroup

int selectNextGroup(GroupView groupView)

Binds a GroupView instance with the next group in the current enumeration.

The order in which the groups are enumerated is unspecified.

After successful operation, the GroupView instance is in the SELECTED state, and is bound to the next group 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 GroupView instance is in DESELECTED state.

Parameters:
groupView - GroupView instance to bind to the next group in the enumeration.
Returns:
group identifier, or -1 if the current enumeration reached its end.

selectGroup

void selectGroup(GroupView groupView,
                 int groupIdentifier)

Binds a GroupView instance to a group that matches the provided groupIdentifier.

After successful operation, the GroupView instance is in SELECTED state, and is bound to the selected group.

After unsuccessful operation, the GroupView instance is in DESELECTED state.

Parameters:
groupView - GroupView instance to bind with the next group that matches the identifier.
groupIdentifier - group identifier of group to get
Throws:
uicc.contactmanager.ContactManagerException: -
  • with reason WRONG_IDENTIFIER if the list contains no group with the groupIdentifier provided.

addGroup

int addGroup(byte[] name,
             short nameOffset,
             short nameLength)

Creates a new group and adds it to the groups list.

The new group is set with the provided group name, in a way that is similar to a call to method GroupView.setGroupName() with the parameters name, nameOffset and nameLength.

When a group is added to a groups list, any enumeration over the same groups list currently in progress may or may not include the new group, depending on the implementation.

Parameters:
name - name of the group to set
nameOffset - offset in name buffer
nameLength - length of name buffer
Returns:
the new group's identifier

removeGroup

void removeGroup(int groupIdentifier)

Removes a group from the groups list.

This method fails in the following cases:

Parameters:
groupIdentifier - identifier of the group to be removed from the list
Throws:
uicc.contactmanager.ContactManagerException - with the following reasons:
  • WRONG_IDENTIFIER if groupIdentifier does not identify any group in the groups list.
  • ITEM_SELECTED if the group to be removed is currently selected by a GroupView instance.
  • ENUMERATION_IN_PROGRESS if a conflicting enumeration is currently in progress.

getNumberOfGroups

int getNumberOfGroups()

Returns the number of groups in the groups list.

Returns:
number of groups in the group list