uicc.contactmanager
Interface ContactView


public interface ContactView

A ContactView instance represents a contact in the contact manager.

Each contact is a collection of fields.
Within a contact, each field is assigned a numeric identifier, that indicates the related field descriptor in the field descriptors list.

A ContactView instance may successively represent multiple contacts throughout its lifetime.
It is good practice, for an application that needs to manipulate contacts, to create one ContactView instance at installation, that will be re-used throughout the application's lifetime.

A ContactView instance provides an enumeration scheme to enumerate all fields that belong to it, or a subset of them defined by specified filtering criteria.

An instance is necessarily in one of the following states:

More detailed description of the behavior of a ContactView instance in these states is given below:

The ContactView class also provides a factory method to create a FieldView instance.


Method Summary
 FieldView createFieldInstance()
           Factory method used to create a FieldView instance.
 void deselect()
           If a contact is currently SELECTED by the instance, deselect the contact.
 int getContactIdentifier()
           Returns the contact identifier.
 boolean hasMoreFields()
           Checks if there are more fields in the current field enumeration.
 void selectField(FieldView fieldView, int fieldDescriptorIdentifier)
           Selects the field from the contact whose descriptor matches the specified fieldDescriptorIdentifier, and set fieldView to represent the selected field.
 int selectNextField(FieldView fieldView)
           Selects the next field in the current enumeration, and set fieldView to represent the selected field.
 void startEnumeration()
           Starts a new enumeration of all fields in the contact.
 void startEnumeration(short type, int attributesMask, byte[] pattern, short patternOffset, short patternLength)
           Starts a new enumeration of fields in the contact that match specific criteria.
 

Method Detail

getContactIdentifier

int getContactIdentifier()

Returns the contact identifier.

The identifier is -1 as long as the instance is in state DESELECTED.

Returns:
contact identifier

createFieldInstance

FieldView createFieldInstance()

Factory method used to create a FieldView instance.

The FieldView instance is owned by the calling application.

Returns:
new FieldView instance

startEnumeration

void startEnumeration()

Starts a new enumeration of all fields in the contact.

Throws:
uicc.contactmanager.ContactManagerException - with reason:
  • WRONG_STATE if ContactView object is DESELECTED

startEnumeration

void startEnumeration(short type,
                      int attributesMask,
                      byte[] pattern,
                      short patternOffset,
                      short patternLength)

Starts a new enumeration of fields in the contact that match specific criteria.

Only fields that match a specific type, attributes and a value pattern will participate in the enumeration.
The attributesMask parameter is an integer, where each bit represents a specific attribute, as defined by the FieldView.ATTR_* constants. Bits set indicate the attributes that a field must have in order to participate in the enumeration: fields that don't have these attributes won't participate. Bits with value 0 are ignored.
The value pattern is a string that specifies the field values that should match. It may have three forms:

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

Parameters:
type - type of the selected fields
attributesMask - mask indicating the required attributes of the selected fields
pattern - Byte array containing the pattern that the selected fields should match. If null, no pattern-based filtering is done.
patternOffset - Starting offset of the pattern in the pattern byte array.
patternLength - Length of the pattern.
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if ContactView object is DESELECTED

hasMoreFields

boolean hasMoreFields()

Checks if there are more fields in the current field enumeration.

Returns:
true if there is at least one more field, false otherwise
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if ContactView object is DESELECTED

selectNextField

int selectNextField(FieldView fieldView)

Selects the next field in the current enumeration, and set fieldView to represent the selected field.

The order in which the fields are enumerated is unspecified.

Parameters:
fieldView - FieldView object that must represent the next field in the enumeration.
Returns:
field descriptor identifier, or -1 if the enumeration reached its end.
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if ContactView object is DESELECTED

selectField

void selectField(FieldView fieldView,
                 int fieldDescriptorIdentifier)

Selects the field from the contact whose descriptor matches the specified fieldDescriptorIdentifier, and set fieldView to represent the selected field.

Parameters:
fieldView - FieldView object that must represent the matching field.
fieldDescriptorIdentifier - field descriptor identifier of field to get.
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_IDENTIFIER if the field descriptors list contains no field with identifier fieldDescriptorIdentifier;
  • WRONG_STATE if ContactView object is DESELECTED.

deselect

void deselect()

If a contact is currently SELECTED by the instance, deselect the contact.

After a successful call to this method, the instance is in DESELECTED state.