ProactiveHandler.java

/*
 *   
 *
 * 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
//-----------------------------------------------------------------------------

/**
 *
 * This class is the basic class for the definition of 
 * <b>Proactive commands
 * </b>. Low level methods, as <code>init()</code>, <code>appendTLV()</code>...
 * will be used to handle generic Proactive commands (standard or future
 * definitions...). The ProactiveHandler class is a <b>Temporary JCRE Entry 
 * Point Object</b>.
 * The Toolkit applets, which need to send Proactive commands,
 * shall call the <code>getTheHandler()</code> static method to get the
 * reference of this system instance.<p>
 *
 * Example of use:<pre><code>
 *                                      // constants definition
 * private static final byte MY_COMMAND = (byte)0x33;
 * private static final byte MY_TAG     = (byte)0x45;
 *
 * ProactiveHandler proHdlr;            // get the system instance
 * proHdlr = ProactiveHandler.getTheHandler();
 *
 *                                      // build and send a new Proactive 
 *                                      // command
 * proHdlr.init(MY_COMMAND, (byte)0, DEV_ID_ME);
 * proHdlr.appendTLV((byte)(MY_TAG | TAG_SET_CR),
 *                (byte)0);
 * short len = proHdlr.getLength();     // length should be 14 !
 * byte result = proHdlr.send();
 *
 * private byte[] text = new byte[12];  // byte array definition
 * text[0] = (byte)'S';                 // text, in 8-bit format, is "SAT"
 * text[1] = (byte)'A';
 * text[2] = (byte)'T';
 *                                      // build and send a DisplayText command
 * result = proHdlr.initDisplayText((byte)0x80, DCS_8_BIT_DATA, 
 *                                  text, (short)0, (short)3);
 * result = proHdlr.send();
 * </code></pre>
 *
 * @version 8.3.0
 *
 * @see ViewHandler
 * @see EditHandler
 * @see ProactiveResponseHandler
 * @see ToolkitException
 */
public final class ProactiveHandler extends EditHandler {

    // ------------------------------- Constructors ---------------------------
    /**
     * Constructor
     */
    private ProactiveHandler() {
    }


    // ------------------------------- Public methods -------------------------
    /**
     * Returns the single system instance of the ProactiveHandler 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 ProactiveHandler getTheHandler() throws ToolkitException {
        return null;
    }

    /**
     * Initializes the next Proactive command with Command Details and Device
     * Identities TLV.
     * The source device is always the SIM card. The command number is
     * generated by the method. The Comprehension Required flags are set.
     * After the method invocation no TLV is selected.
     *
     * @param type the command type
     * @param qualifier the command qualifier
     * @param dstDevice the destination device
     */
    public void init(byte type,
                     byte qualifier,
                     byte dstDevice) {
    }

    /**
     * Sends the current Proactive command.
     *
     * @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> if the Result Simple TLV 
     *      is missing.
     *      <li><code>OUT_OF_TLV_BOUNDARIES</code> if the general result 
     *      byte is missing in the Result Simple TLV.</ul>
     */
    public byte send() throws ToolkitException {
        return 0;
    }

    /**
     * Builds a Display Text Proactive command without sending the command. 
     * The Comprehension
     * Required flags are all set to 1.
     * After the method invocation no TLV is selected.
     *
     * <p>
     * Notes:<ul>
     * <li><em>If </em><code>offset</code><em> or </em><code>length</code><em> 
     * parameter is negative an 
     * </em><code>ArrayIndexOutOfBoundsException</code>
     * <em> exception is thrown and no proactive command is build.</em>
     * <li><em>If </em><code>offset+length</code><em> is greater than 
     * </em><code>buffer.length</code><em>, the length
     * of the </em><code>buffer</code><em> array an 
     * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
     * and no proactive command is build.</em> 
     * </ul> 
     *
     * @param qualifier Display Text command qualifier
     * @param dcs data coding scheme
     * @param buffer reference to the text string source buffer
     * @param offset offset of the text string in the source buffer
     * @param length length of the text string in the source buffer
     *
     * @exception NullPointerException if <code>buffer</code> is 
     * <code>null</code>
     * @exception ArrayIndexOutOfBoundsException if initDisplayText would 
     * cause access of data outside array bounds
     * @exception ToolkitException with the following reason codes: <ul>
     *      <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer 
     *          is to small to put the requested data </ul>
     */
    public void initDisplayText(byte qualifier,
                                byte dcs,
                                byte[] buffer,
                                short offset,
                                short length) throws NullPointerException,
                                            ArrayIndexOutOfBoundsException,
                                            ToolkitException {
    }

    /**
     * Builds a Get Inkey Proactive command without sending the command. 
     * The Comprehension
     * Required flags are all set to 1.
     * After the method invocation no TLV is selected.
     *
     * <p>
     * Notes:<ul>
     * <li><em>If </em><code>offset</code><em> or 
     * </em><code>length</code><em> parameter is negative an 
     * </em><code>ArrayIndexOutOfBoundsException</code>
     * <em> exception is thrown and no proactive command is build.</em>
     * <li><em>If </em><code>offset+length</code><em> is greater than 
     * </em><code>buffer.length</code><em>, the length
     * of the </em><code>buffer</code><em> array an 
     * </em><code>ArrayIndexOutOfBoundsException</code><em> exception 
     * is thrown and no proactive command is build.</em> 
     * </ul> 
     *
     * @param qualifier Get Inkey command qualifier
     * @param dcs data coding scheme
     * @param buffer reference to the displayed text string source buffer
     * @param offset offset of the displayed text string in the source buffer
     * @param length length of the displayed text string in the source buffer
     *
     * @exception NullPointerException if <code>buffer</code> is 
     * <code>null</code>
     * @exception ArrayIndexOutOfBoundsException if initGetInkey would 
     * cause access of data outside array bounds.
     * @exception ToolkitException with the following reason codes: <ul>
     *      <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
     *      is to small to put the requested data</ul>	  
     */
    public void initGetInkey(byte qualifier,
                             byte dcs,
                             byte[] buffer,
                             short offset,
                             short length) throws NullPointerException,
                                        ArrayIndexOutOfBoundsException,
                                        ToolkitException {
    }

    /**
     * Initialize the building of a Get Input Proactive command. The 
     * Comprehension Required flags are all set to 1.
     * The following command parameters (i.e. TLVs) may be appended to the
     * command before sending it: Default Text.
     * After the method invocation no TLV is selected.
     *
     * <p>
     * Notes:<ul>
     * <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
     * parameter is negative an 
     * </em><code>ArrayIndexOutOfBoundsException</code>
     * <em> exception is thrown and no proactive command is build.</em>
     * <li><em>If </em><code>offset+length</code><em>is greater than 
     * </em><code>buffer.length</code><em>, the length
     * of the </em><code>buffer</code><em> array an 
     * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
     * and no proactive command is build.</em> 
     * </ul> 
     *
     * @param qualifier Get Input command qualifier
     * @param dcs data coding scheme
     * @param buffer reference to the displayed text string source buffer
     * @param offset offset of the displayed text string in the source buffer
     * @param length length of the displayed text string in the source buffer
     * @param minRespLength minimal length of the response text string
     * @param maxRespLength maximal length of the response text string
     *
     * @exception NullPointerException if <code>buffer</code> is 
     * <code>null</code>
     * @exception ArrayIndexOutOfBoundsException if initGetInput would cause 
     * access of data outside array bounds.
     * @exception ToolkitException with the following reason codes: <ul>
     *      <li><code>HANDLER_OVERFLOW</code> if the ProactiveHandler buffer
     *      is to small to put the requested data</ul>
     */
    public void initGetInput(byte qualifier,
                             byte dcs,
                             byte[] buffer,
                             short offset,
                             short length,
                             short minRespLength,
                             short maxRespLength) throws NullPointerException,
                                                ArrayIndexOutOfBoundsException,
                                                ToolkitException {
    }
}