uicc.contactmanager
Interface FieldView


public interface FieldView

A FieldView instance represents a field in a contact managed by the contact manager.

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

When it is created, a FieldView instance is in DESELECTED state:

Successful invocation of the methods ContactView.getField() and ContactView.nextField() result in binding the instance to a specific field in the contact:

A field is always associated to a field descriptor in the field descriptors list of the containing contact manager.

The FieldView class provides methods to retrieve and update the field's unformatted or formatted value (binary, Phone number, name or Address).

Methods to read and update field value binary contents can be invoked iteratively for smaller parts of the entire field:


Field Summary
static short ADDR_COUNTRY
          Key for the sub-field in a formatted address, containing the country of a particular address.
static short ADDR_EXTRA
          Key for the sub-field in a formatted address, containing any extra info of a particular address.
static short ADDR_LOCALITY
          Key for the sub-field in a formatted address, containing the locality (for example, a city) of a particular address.
static short ADDR_POBOX
          Key for the sub-field in a formatted address, containing the post office box of a particular address.
static short ADDR_POSTALCODE
          Key for the sub-field in a formatted address, containing the postal code (for example, a zip code) of a particular address.
static short ADDR_REGION
          Key for the sub-field in a formatted address, containing the region (for example, a province, state, or territory) of a particular address.
static short ADDR_STREET
          Key for the sub-field in a formatted address, containing the street information of a particular address.
static int ATTR_AIFF
          Attribute specifying a AIFF audio format
static int ATTR_ANY
          Attribute specifying any attributes
static int ATTR_AVI
          Attribute specifying a AVI video format
static int ATTR_BBS
          Attribute specifying a BBS phone number
static int ATTR_BMP
          Attribute specifying a BMP image format
static int ATTR_CAR
          Attribute specifying a car phone number
static int ATTR_CELL
          Attribute specifying a cell phone number
static int ATTR_CGM
          Attribute specifying a CGM image format
static int ATTR_DIB
          Attribute specifying a DIB image format
static int ATTR_DOM
          Attribute specifying a domestic address
static int ATTR_FAX
          Attribute specifying a fax phone number
static int ATTR_GIF
          Attribute specifying a GIF image format
static int ATTR_HOME
          Attribute specifying a home address or phone number
static int ATTR_INTERNET
          Attribute specifying a internet mail address
static int ATTR_INTL
          Attribute specifying an international address
static int ATTR_ISDN
          Attribute specifying a ISDN phone number
static int ATTR_JPEG
          Attribute specifying a JPEG image format
static int ATTR_MET
          Attribute specifying a MET image format
static int ATTR_MODEM
          Attribute specifying a modem phone number
static int ATTR_MPEG
          Attribute specifying a MPEG video format
static int ATTR_MPEG2
          Attribute specifying a MPEG2 video format
static int ATTR_MSG
          Attribute specifying a messaging service phone number
static int ATTR_PAGER
          Attribute specifying a pager phone number
static int ATTR_PARCEL
          Attribute specifying a parcel address
static int ATTR_PCM
          Attribute specifying a PCM audio format
static int ATTR_PDF
          Attribute specifying a PDF format
static int ATTR_PGP
          Attribute specifying a PGP key
static int ATTR_PICT
          Attribute specifying a PICT image format
static int ATTR_PMB
          Attribute specifying a PMB image format
static int ATTR_POSTAL
          Attribute specifying a postal address
static int ATTR_PREF
          Attribute specifying a preferred phone number
static int ATTR_PS
          Attribute specifying a PS format
static int ATTR_QTIME
          Attribute specifying a Quick Time video format
static int ATTR_TIFF
          Attribute specifying a TIFF image format
static int ATTR_VIDEO
          Attribute specifying a video phone number
static int ATTR_VOICE
          Attribute specifying a voice phone number
static int ATTR_WAVE
          Attribute specifying a WAVE audio format
static int ATTR_WMF
          Attribute specifying a WMF image format
static int ATTR_WORK
          Attribute specifying a work address or phone number
static int ATTR_X509
          Attribute specifying a X509 certificate key
static short NAME_FAMILY
          Key for the sub-field in a formatted name, containing the family name.
static short NAME_GIVEN
          Key for the sub-field in a formatted name, containing the given name.
static short NAME_OTHER
          Key for the sub-field in a formatted name, containing other alternate name or names.
static short NAME_PREFIX
          Key for the sub-field in a formatted name, containing a prefix to a name.
static short NAME_SUFFIX
          Key for the sub-field in a formatted name, containing a suffix to a name.
static short TYPE_ADDR
          Field type specifying an address for this contact.
static short TYPE_BDAY
          Field type for the birthday of the contact.
static short TYPE_EMAIL
          Field type for an e-mail address.
static short TYPE_FORMATED_ADDR
          Field type specifying an address for this contact.
static short TYPE_FORMATTED_NAME
          Field type represents a formatted version of a name for the contact entry.
static short TYPE_NAME
          Field type specifying the name for this contact.
static short TYPE_NOTE
          Field type specifying supplemental information or a comment associated with a Contact.
static short TYPE_PHOTO
          Field type specifying a photo for a Contact.
static short TYPE_PHOTO_URL
          Field type specifying a photo url of a Contact.
static short TYPE_REVISION
          Field type specifying the last modification date and time of a Contact item.
static short TYPE_ROLE
          Field type specifying a contact role
static short TYPE_TEL
          Field type for a voice telephone number.
static short TYPE_TITLE
          Field type specifying the job title for a Contact.
static short TYPE_UID
          Field type specifying a unique ID for a Contact.
static short TYPE_URL
          Field type specifying the uniform resource locator for a Contact.
 
Method Summary
 int getAttributes()
           Returns field attributes.
 int getFieldDescriptorIdentifier()
          Returns the FieldDescriptor identifier of the field.
 int getFieldSize()
           Returns the field's size.
 short getType()
           Returns the field type.
 short readBinary(byte[] buffer, short offset, short maxLength)
           Reads a sequence of bytes from the field value.
 short readFormattedAddressField(short key, byte[] buffer, short offset, short length)
           Reads a subfield from a formatted address.
 short readFormattedName(short key, byte[] buffer, short offset, short length)
           Reads a subfield from a formatted name.
 short readPhoneNumber(byte[] buffer, short offset, short length)
           Reads the field as a phone number with the following format: 1st byte represents the TON-NPI following bytes represent the phone number encoded in packed BCD format.
 void setAdditionalAttributes(int additionalAttributes)
           Sets additional field attributes to this field.
 short updateBinary(byte[] buffer, short offset, short length)
           Updates the field value with a sequence of bytes.
 short updateFormattedAddressField(short key, byte[] buffer, short offset, short length)
           Updates a subfield of a formatted address.
 short updateFormattedName(short key, byte[] buffer, short offset, short length)
           Updates a subfield of a formatted name.
 short updatePhoneNumber(byte[] buffer, short offset, short length)
           Updates the field as a phone number with following format: 1st byte represents the TON-NPI following bytes represent the phone number encoded in BCD format.
 

Field Detail

TYPE_ADDR

static final short TYPE_ADDR
Field type specifying an address for this contact.

See Also:
Constant Field Values

TYPE_FORMATED_ADDR

static final short TYPE_FORMATED_ADDR
Field type specifying an address for this contact.

See Also:
Constant Field Values

TYPE_BDAY

static final short TYPE_BDAY
Field type for the birthday of the contact.

See Also:
Constant Field Values

TYPE_FORMATTED_NAME

static final short TYPE_FORMATTED_NAME
Field type represents a formatted version of a name for the contact entry.

See Also:
Constant Field Values

TYPE_NAME

static final short TYPE_NAME
Field type specifying the name for this contact.

See Also:
Constant Field Values

TYPE_TEL

static final short TYPE_TEL
Field type for a voice telephone number.

See Also:
Constant Field Values

TYPE_PHOTO

static final short TYPE_PHOTO
Field type specifying a photo for a Contact.

See Also:
Constant Field Values

TYPE_PHOTO_URL

static final short TYPE_PHOTO_URL
Field type specifying a photo url of a Contact. SCE: is it usefull since we have URL?

See Also:
Constant Field Values

TYPE_EMAIL

static final short TYPE_EMAIL
Field type for an e-mail address.

See Also:
Constant Field Values

TYPE_NOTE

static final short TYPE_NOTE
Field type specifying supplemental information or a comment associated with a Contact.

See Also:
Constant Field Values

TYPE_REVISION

static final short TYPE_REVISION
Field type specifying the last modification date and time of a Contact item.

See Also:
Constant Field Values

TYPE_TITLE

static final short TYPE_TITLE
Field type specifying the job title for a Contact.

See Also:
Constant Field Values

TYPE_UID

static final short TYPE_UID
Field type specifying a unique ID for a Contact.

See Also:
Constant Field Values

TYPE_URL

static final short TYPE_URL
Field type specifying the uniform resource locator for a Contact.

See Also:
Constant Field Values

TYPE_ROLE

static final short TYPE_ROLE
Field type specifying a contact role

See Also:
Constant Field Values

ATTR_DOM

static final int ATTR_DOM
Attribute specifying a domestic address

See Also:
Constant Field Values

ATTR_INTL

static final int ATTR_INTL
Attribute specifying an international address

See Also:
Constant Field Values

ATTR_POSTAL

static final int ATTR_POSTAL
Attribute specifying a postal address

See Also:
Constant Field Values

ATTR_PARCEL

static final int ATTR_PARCEL
Attribute specifying a parcel address

See Also:
Constant Field Values

ATTR_HOME

static final int ATTR_HOME
Attribute specifying a home address or phone number

See Also:
Constant Field Values

ATTR_WORK

static final int ATTR_WORK
Attribute specifying a work address or phone number

See Also:
Constant Field Values

ATTR_PREF

static final int ATTR_PREF
Attribute specifying a preferred phone number

See Also:
Constant Field Values

ATTR_VOICE

static final int ATTR_VOICE
Attribute specifying a voice phone number

See Also:
Constant Field Values

ATTR_FAX

static final int ATTR_FAX
Attribute specifying a fax phone number

See Also:
Constant Field Values

ATTR_MSG

static final int ATTR_MSG
Attribute specifying a messaging service phone number

See Also:
Constant Field Values

ATTR_CELL

static final int ATTR_CELL
Attribute specifying a cell phone number

See Also:
Constant Field Values

ATTR_PAGER

static final int ATTR_PAGER
Attribute specifying a pager phone number

See Also:
Constant Field Values

ATTR_BBS

static final int ATTR_BBS
Attribute specifying a BBS phone number

See Also:
Constant Field Values

ATTR_MODEM

static final int ATTR_MODEM
Attribute specifying a modem phone number

See Also:
Constant Field Values

ATTR_CAR

static final int ATTR_CAR
Attribute specifying a car phone number

See Also:
Constant Field Values

ATTR_ISDN

static final int ATTR_ISDN
Attribute specifying a ISDN phone number

See Also:
Constant Field Values

ATTR_VIDEO

static final int ATTR_VIDEO
Attribute specifying a video phone number

See Also:
Constant Field Values

ATTR_INTERNET

static final int ATTR_INTERNET
Attribute specifying a internet mail address

See Also:
Constant Field Values

ATTR_GIF

static final int ATTR_GIF
Attribute specifying a GIF image format

See Also:
Constant Field Values

ATTR_CGM

static final int ATTR_CGM
Attribute specifying a CGM image format

See Also:
Constant Field Values

ATTR_WMF

static final int ATTR_WMF
Attribute specifying a WMF image format

See Also:
Constant Field Values

ATTR_BMP

static final int ATTR_BMP
Attribute specifying a BMP image format

See Also:
Constant Field Values

ATTR_MET

static final int ATTR_MET
Attribute specifying a MET image format

See Also:
Constant Field Values

ATTR_PMB

static final int ATTR_PMB
Attribute specifying a PMB image format

See Also:
Constant Field Values

ATTR_DIB

static final int ATTR_DIB
Attribute specifying a DIB image format

See Also:
Constant Field Values

ATTR_PICT

static final int ATTR_PICT
Attribute specifying a PICT image format

See Also:
Constant Field Values

ATTR_TIFF

static final int ATTR_TIFF
Attribute specifying a TIFF image format

See Also:
Constant Field Values

ATTR_PDF

static final int ATTR_PDF
Attribute specifying a PDF format

See Also:
Constant Field Values

ATTR_PS

static final int ATTR_PS
Attribute specifying a PS format

See Also:
Constant Field Values

ATTR_JPEG

static final int ATTR_JPEG
Attribute specifying a JPEG image format

See Also:
Constant Field Values

ATTR_MPEG

static final int ATTR_MPEG
Attribute specifying a MPEG video format

See Also:
Constant Field Values

ATTR_MPEG2

static final int ATTR_MPEG2
Attribute specifying a MPEG2 video format

See Also:
Constant Field Values

ATTR_AVI

static final int ATTR_AVI
Attribute specifying a AVI video format

See Also:
Constant Field Values

ATTR_QTIME

static final int ATTR_QTIME
Attribute specifying a Quick Time video format

See Also:
Constant Field Values

ATTR_WAVE

static final int ATTR_WAVE
Attribute specifying a WAVE audio format

See Also:
Constant Field Values

ATTR_PCM

static final int ATTR_PCM
Attribute specifying a PCM audio format

See Also:
Constant Field Values

ATTR_AIFF

static final int ATTR_AIFF
Attribute specifying a AIFF audio format

See Also:
Constant Field Values

ATTR_X509

static final int ATTR_X509
Attribute specifying a X509 certificate key

See Also:
Constant Field Values

ATTR_PGP

static final int ATTR_PGP
Attribute specifying a PGP key

See Also:
Constant Field Values

ATTR_ANY

static final int ATTR_ANY
Attribute specifying any attributes

See Also:
Constant Field Values

ADDR_COUNTRY

static final short ADDR_COUNTRY
Key for the sub-field in a formatted address, containing the country of a particular address.

See Also:
Constant Field Values

ADDR_EXTRA

static final short ADDR_EXTRA
Key for the sub-field in a formatted address, containing any extra info of a particular address.

See Also:
Constant Field Values

ADDR_LOCALITY

static final short ADDR_LOCALITY
Key for the sub-field in a formatted address, containing the locality (for example, a city) of a particular address.

See Also:
Constant Field Values

ADDR_POBOX

static final short ADDR_POBOX
Key for the sub-field in a formatted address, containing the post office box of a particular address.

See Also:
Constant Field Values

ADDR_POSTALCODE

static final short ADDR_POSTALCODE
Key for the sub-field in a formatted address, containing the postal code (for example, a zip code) of a particular address.

See Also:
Constant Field Values

ADDR_REGION

static final short ADDR_REGION
Key for the sub-field in a formatted address, containing the region (for example, a province, state, or territory) of a particular address.

See Also:
Constant Field Values

ADDR_STREET

static final short ADDR_STREET
Key for the sub-field in a formatted address, containing the street information of a particular address.

See Also:
Constant Field Values

NAME_FAMILY

static final short NAME_FAMILY
Key for the sub-field in a formatted name, containing the family name.

See Also:
Constant Field Values

NAME_GIVEN

static final short NAME_GIVEN
Key for the sub-field in a formatted name, containing the given name.

See Also:
Constant Field Values

NAME_OTHER

static final short NAME_OTHER
Key for the sub-field in a formatted name, containing other alternate name or names.

See Also:
Constant Field Values

NAME_PREFIX

static final short NAME_PREFIX
Key for the sub-field in a formatted name, containing a prefix to a name.

See Also:
Constant Field Values

NAME_SUFFIX

static final short NAME_SUFFIX
Key for the sub-field in a formatted name, containing a suffix to a name.

See Also:
Constant Field Values
Method Detail

getFieldDescriptorIdentifier

int getFieldDescriptorIdentifier()
Returns the FieldDescriptor identifier of the field.

Returns:
field descriptor identifier
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in UNBOUND state.

getAttributes

int getAttributes()

Returns field attributes.

The field attributes value is an integer interpreted as a bit field, where each bit is set when a specific attribute is present.

The meanings and bit values of attributes are defined in ATTR_* constants.

Returns:
field attributes
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.

setAdditionalAttributes

void setAdditionalAttributes(int additionalAttributes)

Sets additional field attributes to this field.

Additional attributes are used to set specific attributes to a contact field, for example:

The additional attributes are provided in an integer value interpreted as a bit field, where each bits position represents an additional attribute.

Binary operations can be used to combine attributes, for example: ( ATTR_HOME | ATTR_POSTAL | ATTR_PREF )

Any attempt to set as additional attributes, mandatory attributes defined in the field descriptor that corresponds to the field, is ignored.

Parameters:
additionalAttributes - additional field attributes
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.

getType

short getType()

Returns the field type.

Returns:
field type
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.

readBinary

short readBinary(byte[] buffer,
                 short offset,
                 short maxLength)

Reads a sequence of bytes from the field value.

The first call to the method since the instance has been bound to a field reads from the beginning of the field value.

Subsequent calls to the method will read bytes still unread.

After the end of the field's value has been reached, all subsequent calls do not modify the buffer provided and return 0, until the instance is bound to another field.

Parameters:
buffer - buffer to copy the bytes into
offset - stating offset in the buffer
maxLength - maximum length to read
Returns:
number of bytes read, 0 if no more bytes to read or empty field
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_FIELD_TYPE if the field is not a binary field.

updateBinary

short updateBinary(byte[] buffer,
                   short offset,
                   short length)

Updates the field value with a sequence of bytes.

The first call to the method since the instance has been bound to a field erases any value previously defined and updates the field value, starting with the first byte.

Subsequent calls to the method will append additional data to the field value.

If appending all bytes provided to the method would overflow the maximum field size defined by the related field descriptor, the bytes are updated up to this maximum size only, and the number of bytes actually written is returned.

Parameters:
buffer - buffer containing bytes used to update the field
offset - starting offset in the buffer
length - number of bytes to update
Returns:
number of bytes actually written
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_FIELD_TYPE if the field is not a binary field.

getFieldSize

int getFieldSize()

Returns the field's size.

This is the size of the value currently stored in the field.

Returns:
current field size in bytes
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.

readPhoneNumber

short readPhoneNumber(byte[] buffer,
                      short offset,
                      short length)

Reads the field as a phone number with the following format:

Parameters:
buffer - buffer to copy the value into
offset - stating offset in the buffer
length - maximum length to read
Returns:
number of bytes read, 0 if no more bytes to read or empty field
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_FIELD_TYPE if the field is not a phone number.

updatePhoneNumber

short updatePhoneNumber(byte[] buffer,
                        short offset,
                        short length)

Updates the field as a phone number with following format:

Parameters:
buffer - buffer containing the new value
offset - stating offset in the buffer
length - length to update
Returns:
number of bytes updated
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_FIELD_TYPE if the field is not a phone number.

readFormattedAddressField

short readFormattedAddressField(short key,
                                byte[] buffer,
                                short offset,
                                short length)

Reads a subfield from a formatted address.

The subfield value is in UTF-8 format.

Parameters:
key - key that identifies the sub-field in the formatted address: ADDR_COUNTRY ,ADDR_EXTRA, ADDR_LOCALITY, ADDR_POBOX, ADDR_POSTALCODE, ADDR_REGION, ADDR_STREET
buffer - buffer to copy the subfield value into
offset - starting offset in the buffer
length - maximum length to read
Returns:
length read
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_KEY if key refers to an unknown subfield.
  • WRONG_FIELD_TYPE if the field is not a formatted address.

updateFormattedAddressField

short updateFormattedAddressField(short key,
                                  byte[] buffer,
                                  short offset,
                                  short length)

Updates a subfield of a formatted address.

The subfield value is in UTF-8 format.

Parameters:
key - key that identifies the sub-field in the formatted address: ADDR_COUNTRY ,ADDR_EXTRA, ADDR_LOCALITY, ADDR_POBOX, ADDR_POSTALCODE, ADDR_REGION, ADDR_STREET
buffer - buffer containing the new subfield value
offset - starting offset in the buffer
length - number of bytes to update
Returns:
Number of bytes updated
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_KEY if key refers to an unknown subfield.
  • WRONG_FIELD_TYPE if the field is not a formatted address.

readFormattedName

short readFormattedName(short key,
                        byte[] buffer,
                        short offset,
                        short length)

Reads a subfield from a formatted name.

The subfield value is in UTF-8 format.

Parameters:
key - key that identifies the sub-field in formatted name: NAME_FAMILY NAME_GIVEN, NAME_OTHER NAME_PREFIX, NAME_SUFFIX
buffer - buffer to copy the subfield value into
offset - starting offset in the buffer
length - maximum length to read
Returns:
length read
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_KEY if index refers to an unknown subfield.
  • WRONG_FIELD_TYPE if the field is not a formatted name.

updateFormattedName

short updateFormattedName(short key,
                          byte[] buffer,
                          short offset,
                          short length)

Updates a subfield of a formatted name.

The subfield value is in UTF-8 format.

Parameters:
key - key that identifies the sub-field in the formatted name: NAME_FAMILY NAME_GIVEN, NAME_OTHER NAME_PREFIX, NAME_SUFFIX
buffer - buffer containing the new subfield value
offset - starting offset in the buffer
length - number of bytes to update
Returns:
number of bytes updated
Throws:
uicc.contactmanager.ContactManagerException, - with reason:
  • WRONG_STATE if FieldView object is in DESELECTED state.
  • WRONG_KEY if index refers to an unknown subfield.
  • WRONG_FIELD_TYPE if the field is not a formatted name.