uicc.toolkit

Interface ProactiveResponseHandler

All Superinterfaces:

ViewHandler

public interface ProactiveResponseHandler
extends ViewHandler

The ProactiveResponseHandler interface contains basic methods to handle the Terminal Response data field. This class will be used by the Toolkit Applet to get the response to the Proactive commands. A class implementing the ProactiveResponseHandler interface is a Temporary JCRE Entry Point Object. The only way to get a ProactiveResponseHandler reference is through the getTheHandler() static method from ProactiveResponseHandlerSystem

Example of use:

 private byte[] data;
 data = new byte[32];                 // build a buffer

 ProactiveResponseHandler ProRespHdlr;            // get the system instance
 ProRespHdlr = ProactiveResponseHandlerSystem.getTheHandler();

 // get General Result
 byte result = ProRespHdlr.getGeneralResult();

 respHdlr.findTLV(TAG_DEVICE_IDENTITIES, 1);          // look for Device Identities
 byte sourceDev = ProRespHdlr.getValueByte((short)0);    // read Device Identities
 byte destinDev = ProRespHdlr.getValueByte((short)1);

                                                      // look for Text String element
 if (ProRespHdlr.findTLV(TAG_TEXT_STRING, (byte)1) == TLV_FOUND_CR_SET) {
     if ((short len = ProRespHdlr.getValueLength()) > 1) {
         // not empty string: to be copied
         ProRespHdlr.copyValue((short)1, data, (short)0, (short)(len - 1));
     }
 }
 

See Also:

ViewHandler, ProactiveHandler, ToolkitException

Method Summary

Modifier and Type	Method and Description
short	copyAdditionalInformation(byte[] dstBuffer, short dstOffset, short dstLength) Copies a part of the additional information field from the first Result TLV element of the current response data field.
short	copyChannelData(byte[] dstBuffer, short dstOffset, short dstLength) Copies parts of the Channel data string field from the first Channel data TLV element of the current response data field.
short	copyTextString(byte[] dstBuffer, short dstOffset) Copies the text string value from the first Text String TLV element of the current response data field.
short	getAdditionalInformationLength() Returns the length of the additional information field from the first Result TLV element of the current response data field.
byte	getChannelIdentifier() Returns the channelIdentifier value from the first Channel status TLV element in the current response data field.
short	getChannelStatus(byte channelIdentifier) Returns the value of the first Channel Status TLV element whose channel identifier is equal to the channelIdentifier parameter.
byte	getGeneralResult() Returns the general result byte of the Proactive command.
byte	getItemIdentifier() Returns the item identifier byte value from the first Item Identifier TLV element of the current response data field.
byte	getTextStringCodingScheme() Returns the data coding scheme byte from the first Text String TLV element of the current response data field.
short	getTextStringLength() Returns the text string length value from the first Text String TLV element of the current response data field.

Methods inherited from interface uicc.toolkit.ViewHandler

compareValue, copy, copyValue, findAndCompareValue, findAndCompareValue, findAndCopyValue, findAndCopyValue, findTLV, getCapacity, getLength, getValueByte, getValueLength, getValueShort

Method Detail

getGeneralResult

byte getGeneralResult()
               throws ToolkitException

Returns the general result byte of the Proactive command. If the element is available it becomes the TLV selected, else no TLV selected.

Returns:

general result of the command (first byte of Result TLV in Terminal Response)

Throws:

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Result TLV element
• OUT_OF_TLV_BOUNDARIES if the general result byte is missing in the Result Comprehension TLV

getAdditionalInformationLength

short getAdditionalInformationLength()
                              throws ToolkitException

Returns the length of the additional information field from the first Result TLV element of the current response data field. If the element is available it becomes the TLV selected, else no TLV is selected.

Returns:

additional information length

Throws:

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Result TLV element

copyAdditionalInformation

short copyAdditionalInformation(byte[] dstBuffer,
                                short dstOffset,
                                short dstLength)
                         throws java.lang.NullPointerException,
                                java.lang.ArrayIndexOutOfBoundsException,
                                ToolkitException

Copies a part of the additional information field from the first Result TLV element of the current response data field. If the element is available it becomes the TLV selected, else no TLV is selected.

Parameters:

dstBuffer - a reference to the destination buffer

dstOffset - the position in the destination buffer

dstLength - the data length to be copied

Returns:

dstOffset+dstLength

Throws:

java.lang.NullPointerException - if dstBuffer is null

java.lang.ArrayIndexOutOfBoundsException - if dstOffset or dstLength or both would cause access outside array bounds

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Result TLV element
• OUT_OF_TLV_BOUNDARIES if dstLength is greater than the value field of the available TLV

getItemIdentifier

byte getItemIdentifier()
                throws ToolkitException

Returns the item identifier byte value from the first Item Identifier TLV element of the current response data field. If the element is available it becomes the TLV selected, else no TLV is selected.

Returns:

item identifier

Throws:

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Item Identifier TLV element
• OUT_OF_TLV_BOUNDARIES if the item identifier byte is missing in the Item Identifier Comprehension TLV

getTextStringLength

short getTextStringLength()
                   throws ToolkitException

Returns the text string length value from the first Text String TLV element of the current response data field. The Data Coding Scheme byte is not taken into account. If the element is available it becomes the TLV selected, else no TLV is selected.

Returns:

text string length

Throws:

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element

getTextStringCodingScheme

byte getTextStringCodingScheme()
                        throws ToolkitException

Returns the data coding scheme byte from the first Text String TLV element of the current response data field. If the element is available it becomes the TLV selected, else no TLV is selected.

Returns:

text string coding scheme

Throws:

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element
• OUT_OF_TLV_BOUNDARIES if the Text String TLV is present with a length of 0 (no DCS byte)

copyTextString

short copyTextString(byte[] dstBuffer,
                     short dstOffset)
              throws java.lang.NullPointerException,
                     java.lang.ArrayIndexOutOfBoundsException,
                     ToolkitException

Copies the text string value from the first Text String TLV element of the current response data field. The Data Coding Scheme byte is not copied. If the element is available it becomes the TLV selected, else no TLV is selected.

Parameters:

dstBuffer - a reference to the destination buffer

dstOffset - the position in the destination buffer

Returns:

dstOffset + length of the copied value

Throws:

java.lang.NullPointerException - if dstBuffer is null

java.lang.ArrayIndexOutOfBoundsException - if dstOffset or dstOffset + (length of the TextString to be copied, without the Data Coding Scheme included), as specified for the returned value, would cause access outside array bounds.

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Text String TLV element

getChannelIdentifier

byte getChannelIdentifier()
                   throws ToolkitException

Returns the channelIdentifier value from the first Channel status TLV element in the current response data field. If the element is available it becomes the currently selected TLV, else no TLV is selected..

Returns:

channelIdentifier

Throws:

ToolkitException - - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable TLV element

OUT_OF_TLV_BOUNDARIES if the Comprehension TLV Channel Status length is equal to zero.

getChannelStatus

short getChannelStatus(byte channelIdentifier)
                throws ToolkitException

Returns the value of the first Channel Status TLV element whose channel identifier is equal to the channelIdentifier parameter. If the element is available it becomes the currently selected TLV element, else no TLV is selected.

Parameters:

channelIdentifier -

Returns:

channel identifier and status : MSB = byte 1 of the Channel Status TLV value (byte 3 of the Channel Status TLV element), LSB = byte 2 of the Channel Status TLV value (byte 4 of the Channel Status TLV element).

Throws:

ToolkitException - with the following reason codes:

• UNAVAILABLE_ELEMENT if no Channel Status TLV element with the right identifier could be found
• OUT_OF_TLV_BOUNDARIES if a Channel Status TLV element with the right identifier could be found but its value is less than 2 bytes long

copyChannelData

short copyChannelData(byte[] dstBuffer,
                      short dstOffset,
                      short dstLength)
               throws java.lang.NullPointerException,
                      java.lang.ArrayIndexOutOfBoundsException,
                      ToolkitException

Copies parts of the Channel data string field from the first Channel data TLV element of the current response data field. If the element is available it becomes the currently selected TLV, else no TLV is selected.

Parameters:

dstBuffer - a reference to the destination buffer

dstOffset - the position in the destination buffer

dstLength - the data length to be copied

Returns:

dstOffset+dstLength

Throws:

java.lang.NullPointerException - - if dstBuffer is null

java.lang.ArrayIndexOutOfBoundsException - - if dstOffset or dstLength or both would cause access outside array bounds

ToolkitException - - with the following reason codes:

• UNAVAILABLE_ELEMENT in case of unavailable Result TLV element
• >code>OUT_OF_TLV_BOUNDARIES if dstLength is greater than the value field of the available TLV