/*
*
*
* Copyright 1990-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
//-----------------------------------------------------------------------------
// PACKAGE DEFINITION
//-----------------------------------------------------------------------------
package sim.toolkit;
//-----------------------------------------------------------------------------
// IMPORTS
//-----------------------------------------------------------------------------
/**
*
* The ProactiveResponseHandler class contains basic methods to handle the
* <b>Terminal
* Response</b> data field. This class will be used by the Toolkit applet to
* get the response to the Proactive commands. No constructor is available for
* the Toolkit applet. The ProactiveResponseHandler class is a <b>Temporary
* JCRE Entry Point Object</b>. The only way to get a ProactiveResponseHandler
* reference is through the <code>getTheHandler()</code> static method.<p>
*
* Example of use:<pre><code>
*
* private byte[] data;
* data = new byte[32]; // build a buffer
*
* ProactiveResponseHandler ProRespHdlr; // get the system instance
* ProRespHdlr = ProactiveResponseHandler.getTheHandler();
*
* // get General Result
* byte result = ProRespHdlr.getGeneralResult();
*
* // look for Device Identities
* respHdlr.findTLV(TAG_DEVICE_IDENTITIES, 1);
*
* // read Device Identities
* byte sourceDev = ProRespHdlr.getValueByte((short)0);
* 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));
* }
* }
* </code></pre>
*
* @version 8.3.0
* @see ViewHandler
* @see ProactiveHandler
* @see ToolkitException
*/
public final class ProactiveResponseHandler extends ViewHandler {
// ------------------------------- Constructors ---------------------------
/**
* Constructor
*/
private ProactiveResponseHandler() {
}
// ------------------------------- Public methods -------------------------
/**
* Returns the single system instance of the
* ProactiveResponseHandler class. The applet shall get the
* reference of the handler at its triggering, the beginning of
* the processToolkit method.
*
* @return reference of the system instance
*
* @exception ToolkitException with the following reason codes:
* <ul> <li><code>HANDLER_NOT_AVAILABLE</code> if the handler
* is busy.</ul>
*/
public static ProactiveResponseHandler getTheHandler()
throws ToolkitException {
return null;
}
/**
* Returns the general result byte of the Proactive command.
* If the element is available it becomes the TLV selected.
*
* @return general result of the command (first byte of Result TLV in
* Terminal Response)
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable
* Result TLV element
* <li><code>OUT_OF_TLV_BOUNDARIES</code> if the general result
* byte is missing in the Result Simple TLV</ul>
*/
public byte getGeneralResult() throws ToolkitException {
return 0;
}
/**
* 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.
*
* @return additional information length
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable Result
* TLV element</ul>
*/
public short getAdditionalInformationLength() throws ToolkitException {
return 0;
}
/**
* 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.
*
* <p>
* Notes:<ul>
* <li><em>If </em><code>dstOffset</code><em> or
* </em><code>dstLength</code><em> parameter is negative an
* </em><code>ArrayIndexOutOfBoundsException</code>
* <em> exception is thrown and no copy is performed.</em>
* <li><em>If </em><code>dstOffset+dstLength</code><em> is
* greater than </em><code>dstBuffer.length</code><em>, the length
* of the </em><code>dstBuffer</code><em> array an
* </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
* and no copy is performed.</em>
* </ul>
*
* @param dstBuffer a reference to the destination buffer
* @param dstOffset the position in the destination buffer
* @param dstLength the data length to be copied
*
* @return <code>dstOffset+dstLength</code>
*
* @exception NullPointerException if <code>dstBuffer</code> is
* <code>null</code>
* @exception ArrayIndexOutOfBoundsException if copyAdditionalInformation
* would cause access of data outside array bounds.
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable
* Result TLV element
* <li><code>OUT_OF_TLV_BOUNDARIES</code> if <code>dstLength</code>
* is greater than the value field of the available TLV</ul>
*/
public short copyAdditionalInformation(byte[] dstBuffer,
short dstOffset,
short dstLength)
throws NullPointerException,
ArrayIndexOutOfBoundsException,
ToolkitException {
return 0;
}
/**
* 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.
*
* @return item identifier
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable
* Item Identifier TLV element
* <li><code>OUT_OF_TLV_BOUNDARIES</code> if the item identifier
* byte is missing in the Item Identifier Simple TLV</ul>
*/
public byte getItemIdentifier() throws ToolkitException {
return 0;
}
/**
* 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.
*
* @return text string length
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable Text
* String TLV element</ul>
*/
public short getTextStringLength() throws ToolkitException {
return 0;
}
/**
* 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.
*
* @return text string coding scheme
*
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable Text
* String TLV element
* <li><code>OUT_OF_TLV_BOUNDARIES</code> if the Text String TLV is
* present with a length
* of 0 (no DCS byte)</ul>
*/
public byte getTextStringCodingScheme() throws ToolkitException {
return 0;
}
/**
* 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.
*
* @param dstBuffer a reference to the destination buffer
* @param dstOffset the position in the destination buffer
*
* @return <code>dstOffset</code> + length of the copied value
*
* @exception NullPointerException if <code>dstBuffer</code> is
* <code>null</code>
* @exception ArrayIndexOutOfBoundsException if <code>dstOffset or
* dstOffset + (length of the TextString to be copied,
* without the Data Coding Scheme included)</code>, as specified for
* the returned value, would cause access outside array bounds.
* @exception ToolkitException with the following reason codes: <ul>
* <li><code>UNAVAILABLE_ELEMENT</code> in case of unavailable Text
* String TLV element</ul>
*/
public short copyTextString(byte[] dstBuffer, short dstOffset)
throws NullPointerException,
ArrayIndexOutOfBoundsException,
ToolkitException {
return 0;
}
}