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.4.0
See Also:
ViewHandler, EnvelopeResponseHandler, ProactiveHandler, ToolkitException

Method Summary
 short getCapacity()
          Returns the maximum size of the Simple TLV list managed by the handler.
 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.
 short getUserDataLength()
          Looks for the TP-User Data field in the first TPDU TLV element contained in the Envelope Handler 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.
 
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 value retrieved by using getValueByte is meaningless when the message is Concatenated. To retrieve the TP-User-Data-Length the method getUserDataLength() shall be used.
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 TS 03.48 Single or Concatenated 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 offset of the first byte following the TS 03.48 Command Packet structure.
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 or Concatenated 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
  • OUT_OF_TLV_BOUNDARIES if the Simple TLV Channel Status length is equal to 0.

getCapacity

public short getCapacity()
                  throws ToolkitException
Returns the maximum size of the Simple TLV list managed by the handler.

Returns:
size in bytes
ToolkitException

getUserDataLength

public short getUserDataLength()
                        throws ToolkitException
Looks for the TP-User Data field in the first TPDU TLV element contained in the Envelope Handler 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:
the length of the User Data contained in the first SMS TPDU TLV element.
Throws:
ToolkitException - with the following reason codes:
  • UNAVAILABLE_ELEMENT in case of unavailable TPDU TLV element or wrong data format