sim.toolkit
Class EnvelopeHandler

java.lang.Object
  |
  +--sim.toolkit.ViewHandler
        |
        +--sim.toolkit.EnvelopeHandler

public final class EnvelopeHandler
extends ViewHandler

The EnvelopeHandler class contains basic methods to handle the Envelope data field. This class will be used by the Toolkit applet in order to have access to the current Envelope information. No constructor is available for the Toolkit applet. The EnvelopeHandler class is a Temporary JCRE Entry Point Object. The only way to get a EnvelopeHandler reference is through the getTheHandler() static method.

Toolkit Applet Example:


 private static final byte MY_TAG = (byte)0x54;
 private byte[] data;
 data = new byte[32];

 void processToolkit(byte event) throws ToolkitException {
     // get the EnvelopeHandler system instance
     EnvelopeHandler theEnv = EnvelopeHandler.getTheHandler();
     // look for MY_TAG TLV
     if (theEnv.findTLV(MY_TAG, (byte)1) != TLV_NOT_FOUND) {
         // check first element byte
         if (theEnv.getValueByte((short)0) == (byte)1) {
             // copy element part into data buffer
             theEnv.copyValue((short)1,
                              data,
                              (short)0,
                              (short)(theEnv.getValueLength() - 1));
         }
     }
 }
 

Version:
5.0.1
See Also:
ViewHandler, EnvelopeResponseHandler, ProactiveHandler, ToolkitException

Method Summary
 byte getChannelIdentifier()
          Returns the channel indentifier value from the first Channel status TLV element
in the current Envelope data field.
 byte getEnvelopeTag()
          Returns the Envelope BER-TLV tag.
 byte getItemIdentifier()
          Returns the item identifier byte value from the first Item Identifier TLV element in the current Envelope data field.
 short getSecuredDataLength()
          Looks for the length of the Secured Data from the Command Packet in the first SMS TPDU or Cell Broadcast Page Simple TLV contained in the Envelope handler.
 short getSecuredDataOffset()
          Looks for the Secured Data from the Command Packet in the first SMS TPDU or Cell Broadcast Page Simple TLV contained in the Envelope handler.
static EnvelopeHandler getTheHandler()
          Returns the single system instance of the EnvelopeHandler class.
 short getTPUDLOffset()
          Looks for the TP-UDL field in the first TPDU TLV element in the Envelope data field.
 
Methods inherited from class sim.toolkit.ViewHandler
compareValue, copy, copyValue, findAndCompareValue, findAndCompareValue, findAndCopyValue, findAndCopyValue, findTLV, getLength, getValueByte, getValueLength
 
Methods inherited from class java.lang.Object
equals
 

Method Detail

getTheHandler

public static EnvelopeHandler getTheHandler()
                                     throws ToolkitException
Returns the single system instance of the EnvelopeHandler class. The applet shall get the reference of the handler at its triggering, the beginning of the processToolkit method.
Returns:
reference of the system instance
Throws:
ToolkitException - with the following reason codes:
  • HANDLER_NOT_AVAILABLE if the handler is busy.

getEnvelopeTag

public byte getEnvelopeTag()
Returns the Envelope BER-TLV tag.
Returns:
Envelope BER-TLV tag

getTPUDLOffset

public short getTPUDLOffset()
                     throws ToolkitException
Looks for the TP-UDL field in the first TPDU TLV element in the Envelope data field. This method can be used on the events EVENT_FORMATTED_SMS_PP_ENV, EVENT_FORMATTED_SMS_PP_UPD, EVENT_UNFORMATTED_SMS_PP_ENV, EVENT_UNFORMATTED_SMS_PP_UPD. If the element is available it becomes the TLV selected.
Returns:
TPUDL offset in the first TPDU TLV element if TPUDL exists. The TPUD length can be recovered by using the getValueByte method in Handler class.
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or if the TPUDL field does not exist

getSecuredDataOffset

public short getSecuredDataOffset()
                           throws ToolkitException
Looks for the Secured Data from the Command Packet in the first SMS TPDU or Cell Broadcast Page Simple TLV contained in the Envelope handler. This can be used on the events: - EVENT_FORMATTED_SMS_PP_ENV, EVENT_FORMATTED_SMS_PP_UPD, if the SMS TP-UD is formatted according to GSM03.48 Single Short Message. - EVENT_FORMATTED_SMS_CB, if the Cell Broadcast Page is formatted according to GSM 03.48. If the element is available it becomes the TLV selected.
Returns:
the offset of the Secured Data first byte in the first SMS TPDU or Cell Broadcast Page TLV element. If the Secured Data length is zero the value returned shall be the SMS TPDU TLV length.
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable SMS TPDU or Cell Broadcast Page TLV element or wrong data format

getSecuredDataLength

public short getSecuredDataLength()
                           throws ToolkitException
Looks for the length of the Secured Data from the Command Packet in the first SMS TPDU or Cell Broadcast Page Simple TLV contained in the Envelope handler. This can be used on the events: - EVENT_FORMATTED_SMS_PP_ENV, EVENT_FORMATTED_SMS_PP_UPD, if the SMS TP-UD is formatted according to GSM03.48 Single Short Message. - EVENT_FORMATTED_SMS_CB, if the Cell Broadcast Page is formatted according to GSM 03.48. If the element is available it becomes the TLV selected.
Returns:
the length of the Secured Data contained in the first SMS TPDU or Cell Broadcast Page TLV element (without padding bytes). If the Secured Data length is zero, no exception shall be thrown.
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable SMS TPDU or Cell Broadcast Page TLV element or wrong data format

getItemIdentifier

public byte getItemIdentifier()
                       throws ToolkitException
Returns the item identifier byte value from the first Item Identifier TLV element in the current Envelope data field. If the element is available it becomes the TLV selected.
Returns:
item identifier
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable TLV element
  • OUT_OF_TLV_BOUNDARIES if the item identifier byte is missing in the Item Identifier Simple TLV

getChannelIdentifier

public byte getChannelIdentifier()
                          throws ToolkitException
Returns the channel indentifier value from the first Channel status TLV element
in the current Envelope data field. If the element is available it becomes the currently
selected TLV.
Returns:
channel identfier
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable TLV element