APDU (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.framework
Class APDU

    java.lang.Object
      javacard.framework.APDU

    @TransactionType(value=NOT_SUPPORTED)
    public final class APDU

extends Object

Application Protocol Data Unit (APDU) is the communication format between the card and the off-card applications. The format of the APDU is defined in ISO specification 7816-4.

This class only supports messages which conform to the structure of command and response defined in ISO 7816-4. The behavior of messages which use proprietary structure of messages is undefined. This class optionally supports extended length fields but only when the currently selected applet implements the `javacardx.apdu.ExtendedLength` interface.

The `APDU` object is owned by the Java Card runtime environment. The `APDU` class maintains a byte array buffer which is used to transfer incoming APDU header and data bytes as well as outgoing data. The buffer length must be at least 133 bytes ( 5 bytes of header and 128 bytes of data ). The Java Card runtime environment must zero out the APDU buffer before each new message received from the CAD.

The Java Card runtime environment designates the `APDU` object as a temporary Java Card runtime environment Entry Point Object (See Runtime Environment Specification, Java Card Platform, Connected Edition, chapter 6 for details). A temporary Java Card runtime environment Entry Point Object can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components.

The Java Card runtime environment similarly marks the APDU buffer as a global array (See Runtime Environment Specification, Java Card Platform, Connected Edition , chapter 6 for details). A global array can be accessed from any applet context. References to global arrays cannot be stored in class variables or instance variables or array components.

The applet receives the `APDU` instance to process from the Java Card runtime environment in the `Applet.process(APDU)` method, and the first five header bytes [ CLA, INS, P1, P2, P3 ] are available in the APDU buffer. (The header format is the ISO7816-4 defined 7 byte extended APDU format with a 3 byte Lc field when the Lc field in the incoming APDU header is 3 bytes long).

The `APDU` class API is designed to be transport protocol independent. In other words, applets can use the same APDU methods regardless of whether the underlying protocol in use is T=0 or T=1 (as defined in ISO 7816-3).

The incoming APDU data size may be bigger than the APDU buffer size and may therefore need to be read in portions by the applet. Similarly, the outgoing response APDU data size may be bigger than the APDU buffer size and may need to be written in portions by the applet. The `APDU` class has methods to facilitate this.

For sending large byte arrays as response data, the `APDU` class provides a special method `sendBytesLong()` which manages the APDU buffer.

     // The purpose of this example is to show most of the methods
     // in use and not to depict any particular APDU processing

     class MyApplet extends javacard.framework.Applet {
         // ...
         public void process(APDU apdu){
      // ...
      byte[] buffer = apdu.getBuffer();
      byte cla = buffer[ISO7816.OFFSET_CLA];
      byte ins = buffer[ISO7816.OFFSET_INS];
      ...
      // assume this command has incoming data
      // Lc tells us the incoming apdu command length
      short bytesLeft = (short) (buffer[ISO7816.OFFSET_LC] & 0x00FF);
      if (bytesLeft < (short)55) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH );

      short readCount = apdu.setIncomingAndReceive();
      while ( bytesLeft > 0){
          // process bytes in buffer[5] to buffer[readCount+4];
          bytesLeft -= readCount;
          readCount = apdu.receiveBytes ( ISO7816.OFFSET_CDATA );
          }
      //
      //...
      //
      // Note that for a short response as in the case illustrated here
      // the three APDU method calls shown : setOutgoing(),setOutgoingLength() & sendBytes()
      // could be replaced by one APDU method call : setOutgoingAndSend().

      // construct the reply APDU
      short le = apdu.setOutgoing();
      if (le < (short)2) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH );
      apdu.setOutgoingLength( (short)3 );

      // build response data in apdu.buffer[ 0.. outCount-1 ];
      buffer[0] = (byte)1; buffer[1] = (byte)2; buffer[3] = (byte)3;
      apdu.sendBytes ( (short)0 , (short)3 );
      // return good complete status 90 00
      }
         // ...
     }

The `APDU` class also defines a set of `STATE_..` constants which represent the various processing states of the `APDU` object based on the methods invoked and the state of the data transfers. The `getCurrentState()` method returns the current state.

Note that the state number assignments are ordered as follows: STATE_INITIAL < STATE_PARTIAL_INCOMING < STATE_FULL_INCOMING < STATE_OUTGOING < STATE_OUTGOING_LENGTH_KNOWN < STATE_PARTIAL_OUTGOING < STATE_FULL_OUTGOING.

The following are processing error states and have negative state number assignments : STATE_ERROR_NO_T0_GETRESPONSE, STATE_ERROR_T1_IFD_ABORT, STATE_ERROR_IO and STATE_ERROR_NO_T0_REISSUE.

Note:

- The method descriptions use the ISO7816-4 notation for the various APDU I/O cases of input and output directions. For example - T=0 (Case 2S) protocol - refers to short length outbound only case using the T=0 protocol. The perspective of the notation used in the method descriptions is that of the card(ICC) as seen at the transport layer(TPDU). External transformations of the APDU I/O case may have occurred at the CAD and therefore not visible to the card.

See Also:
  `APDUException`, `ISOException`

Field Summary
`static byte` | `PROTOCOL_MEDIA_CONTACTLESS_TYPE_A` Transport protocol Media - Contactless Type A
`static byte` | `PROTOCOL_MEDIA_CONTACTLESS_TYPE_B` Transport protocol Media - Contactless Type B
`static byte` | `PROTOCOL_MEDIA_DEFAULT` Transport protocol Media - Contacted Asynchronous Half Duplex
`static byte` | `PROTOCOL_MEDIA_MASK` Media nibble mask in protocol byte
`static byte` | `PROTOCOL_MEDIA_USB` Transport protocol Media - USB
`static byte` | `PROTOCOL_T0` ISO 7816 transport protocol type T=0.
`static byte` | `PROTOCOL_T1` ISO 7816 transport protocol type T=1.
`static byte` | `PROTOCOL_TYPE_MASK` Type nibble mask in protocol byte
`static byte` | `STATE_ERROR_IO` This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.IO_ERROR` has been thrown.
`static byte` | `STATE_ERROR_NO_T0_GETRESPONSE` This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.NO_T0_GETRESPONSE` has been thrown.
`static byte` | `STATE_ERROR_NO_T0_REISSUE` This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.NO_T0_REISSUE` has been thrown.
`static byte` | `STATE_ERROR_T1_IFD_ABORT` This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.T1_IFD_ABORT` has been thrown.
`static byte` | `STATE_FULL_INCOMING` This is the state of a `APDU` object when all the incoming data been received.
`static byte` | `STATE_FULL_OUTGOING` This is the state of a `APDU` object when all outbound data has been transferred.
`static byte` | `STATE_INITIAL` This is the state of a new `APDU` object when only the command header is valid.
`static byte` | `STATE_OUTGOING` This is the state of a new `APDU` object when data transfer mode is outbound but length is not yet known.
`static byte` | `STATE_OUTGOING_LENGTH_KNOWN` This is the state of a `APDU` object when data transfer mode is outbound and outbound length is known.
`static byte` | `STATE_PARTIAL_INCOMING` This is the state of a `APDU` object when incoming data has partially been received.
`static byte` | `STATE_PARTIAL_OUTGOING` This is the state of a `APDU` object when some outbound data has been transferred but not all.

Method Summary
`byte[]` | `getBuffer()` Returns the APDU buffer byte array.
`static byte` | `getCLAChannel()` Returns the logical channel number associated with the current `APDU` command based on the CLA byte.
`static APDU` | `getCurrentAPDU()` This method is called during the `Applet.process(APDU)` method to obtain a reference to the current `APDU` object.
`static byte[]` | `getCurrentAPDUBuffer()` This method is called during the `Applet.process(APDU)` method to obtain a reference to the current APDU buffer.
`byte` | `getCurrentState()` This method returns the current processing state of the `APDU` object.
`static short` | `getInBlockSize()` Returns the configured incoming block size.
`short` | `getIncomingLength()` Returns the incoming data length(Lc).
`byte` | `getNAD()` Returns the Node Address byte (NAD) in T=1 protocol, and 0 in T=0 protocol.
`short` | `getOffsetCdata()` Returns the offset within the APDU buffer for incoming command data.
`static short` | `getOutBlockSize()` Returns the configured outgoing block size.
`static byte` | `getProtocol()` Returns the ISO 7816 transport protocol type, T=1 or T=0 in the low nibble and the transport media in the upper nibble in use.
`boolean` | `isCommandChainingCLA()` Returns whether the current `APDU` command is the first or part of a command chain.
`boolean` | `isISOInterindustryCLA()` Returns whether the current `APDU` command CLA byte corresponds to an interindustry command as defined in ISO 7816-4:2005 specification.
`boolean` | `isSecureMessagingCLA()` Returns `true` if the encoding of the current `APDU` command based on the CLA byte indicates secure messaging.
`boolean` | `isValidCLA()` Returns whether the current `APDU` command CLA byte is valid.
`short` | `receiveBytes(short bOff)` Gets as many data bytes as will fit without APDU buffer overflow, at the specified offset `bOff`.
`void` | `sendBytes(short bOff, short len)` Sends `len` more bytes from APDU buffer at specified offset `bOff`.
`void` | `sendBytesLong(byte[] outData, short bOff, short len)` Sends `len` more bytes from `outData` byte array starting at specified offset `bOff`.
`short` | `setIncomingAndReceive()` This is the primary receive method.
`short` | `setOutgoing()` This method is used to set the data transfer direction to outbound and to obtain the expected length of response (Le).
`void` | `setOutgoingAndSend(short bOff, short len)` This is the "convenience" send method.
`void` | `setOutgoingLength(short len)` Sets the actual length of response data.
`short` | `setOutgoingNoChaining()` This method is used to set the data transfer direction to outbound without using chaining mode and to obtain the expected length of response (Le).
`static void` | `waitExtension()` Requests additional processing time from CAD.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### STATE_INITIAL

    public static final byte STATE_INITIAL

  This is the state of a new `APDU` object when only the command header is valid.

  See Also:
    Constant Field Values

### STATE_PARTIAL_INCOMING

    public static final byte STATE_PARTIAL_INCOMING

  This is the state of a `APDU` object when incoming data has partially been received.

  See Also:
    Constant Field Values

### STATE_FULL_INCOMING

    public static final byte STATE_FULL_INCOMING

  This is the state of a `APDU` object when all the incoming data been received.

  See Also:
    Constant Field Values

### STATE_OUTGOING

    public static final byte STATE_OUTGOING

  This is the state of a new `APDU` object when data transfer mode is outbound but length is not yet known.

  See Also:
    Constant Field Values

### STATE_OUTGOING_LENGTH_KNOWN

    public static final byte STATE_OUTGOING_LENGTH_KNOWN

  This is the state of a `APDU` object when data transfer mode is outbound and outbound length is known.

  See Also:
    Constant Field Values

### STATE_PARTIAL_OUTGOING

    public static final byte STATE_PARTIAL_OUTGOING

  This is the state of a `APDU` object when some outbound data has been transferred but not all.

  See Also:
    Constant Field Values

### STATE_FULL_OUTGOING

    public static final byte STATE_FULL_OUTGOING

  This is the state of a `APDU` object when all outbound data has been transferred.

  See Also:
    Constant Field Values

### STATE_ERROR_NO_T0_GETRESPONSE

    public static final byte STATE_ERROR_NO_T0_GETRESPONSE

  This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.NO_T0_GETRESPONSE` has been thrown.

  See Also:
    Constant Field Values

### STATE_ERROR_T1_IFD_ABORT

    public static final byte STATE_ERROR_T1_IFD_ABORT

  This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.T1_IFD_ABORT` has been thrown.

  See Also:
    Constant Field Values

### STATE_ERROR_IO

    public static final byte STATE_ERROR_IO

  This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.IO_ERROR` has been thrown.

  See Also:
    Constant Field Values

### STATE_ERROR_NO_T0_REISSUE

    public static final byte STATE_ERROR_NO_T0_REISSUE

  This error state of a `APDU` object occurs when an `APDUException` with reason code `APDUException.NO_T0_REISSUE` has been thrown.

  See Also:
    Constant Field Values

### PROTOCOL_MEDIA_MASK

    public static final byte PROTOCOL_MEDIA_MASK

  Media nibble mask in protocol byte

  See Also:
    Constant Field Values

### PROTOCOL_TYPE_MASK

    public static final byte PROTOCOL_TYPE_MASK

  Type nibble mask in protocol byte

  See Also:
    Constant Field Values

### PROTOCOL_T0

    public static final byte PROTOCOL_T0

  ISO 7816 transport protocol type T=0.

  See Also:
    Constant Field Values

### PROTOCOL_T1

    public static final byte PROTOCOL_T1

  ISO 7816 transport protocol type T=1. This constant is also used to denote the T=CL variant for contactless cards defined in ISO14443-4.

  See Also:
    Constant Field Values

### PROTOCOL_MEDIA_DEFAULT

    public static final byte PROTOCOL_MEDIA_DEFAULT

  Transport protocol Media - Contacted Asynchronous Half Duplex

  See Also:
    Constant Field Values

### PROTOCOL_MEDIA_CONTACTLESS_TYPE_A

    public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A

  Transport protocol Media - Contactless Type A

  See Also:
    Constant Field Values

### PROTOCOL_MEDIA_CONTACTLESS_TYPE_B

    public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_B

  Transport protocol Media - Contactless Type B

  See Also:
    Constant Field Values

### PROTOCOL_MEDIA_USB

    public static final byte PROTOCOL_MEDIA_USB

  Transport protocol Media - USB

  See Also:
    Constant Field Values

Method Detail

### getBuffer

    public byte[] getBuffer()

  Returns the APDU buffer byte array.

  Note:

  - References to the APDU buffer byte array may be stored in local variables or method parameters.
  - References to the APDU buffer byte array cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Connected Edition, chapter 6 for details.

  Returns:
    byte array containing the APDU buffer

### getInBlockSize

    public static short getInBlockSize()

  Returns the configured incoming block size. In T=1 protocol, this corresponds to IFSC (information field size for ICC), the maximum size of incoming data blocks into the card. In T=0 protocol, this method returns 1. IFSC is defined in ISO 7816-3.

  This information may be used to ensure that there is enough space remaining in the APDU buffer when `receiveBytes()` is invoked.

  Notes:

  - On `receiveBytes()` the `bOff` param should account for this potential blocksize.
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns `0`.``

  Returns:
    incoming block size setting
  See Also:
    `receiveBytes(short)`

### getOutBlockSize

    public static short getOutBlockSize()

  Returns the configured outgoing block size. In T=1 protocol, this corresponds to IFSD (information field size for interface device), the maximum size of outgoing data blocks to the CAD. In T=0 protocol, this method returns 258 (accounts for 2 status bytes). IFSD is defined in ISO 7816-3.

  This information may be used prior to invoking the `setOutgoingLength()` method, to limit the length of outgoing messages when chaining mode is not allowed. See Runtime Environment Specification, Java Card Platform, Classic Edition, chapter 9.4 for details.

  Notes:

  - On `setOutgoingLength()` the `len` param should account for this potential blocksize.
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns `0`.``

  Returns:
    outgoing block size setting
  See Also:
    `setOutgoingLength(short)`

### getProtocol

    public static byte getProtocol()

  Returns the ISO 7816 transport protocol type, T=1 or T=0 in the low nibble and the transport media in the upper nibble in use. Note:
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns `0`.``

  Returns:
    the protocol media and type in progress Valid nibble codes are listed in `PROTOCOL_*` constants above. See `PROTOCOL_T0`.

### getNAD

    public byte getNAD()

  Returns the Node Address byte (NAD) in T=1 protocol, and 0 in T=0 protocol. This may be used as additional information to maintain multiple contexts.

  Returns:
    NAD transport byte as defined in ISO 7816-3

### setOutgoing

    public short setOutgoing()
                      throws APDUException,
                             ISOException

  This method is used to set the data transfer direction to outbound and to obtain the expected length of response (Le). This method should only be called on a case 2 or case 4 command, otherwise erroneous behavior may result.

  Notes.

  - On a case 4 command, the `setIncomingAndReceive()` must be invoked prior to calling this method. Otherwise, erroneous behavior may result in T=0 protocol.
  - Any remaining incoming data will be discarded.
  - In T=0 (Case 4S) protocol, this method will return 256 with normal semantics.
  - In T=0 (Case 2E, 4S, 4E) protocol, this method will return 32767 when the currently selected applet implements the `javacardx.apdu.ExtendedLength` interface.
  - In T=1 (Case 2E, 4E) protocol, this method will return 32767 when the Le field in the APDU command is 0x0000 and the currently selected applet implements the `javacardx.apdu.ExtendedLength` interface.
  - This method sets the state of the `APDU` object to `STATE_OUTGOING`.

  Returns:
    Le, the expected length of response
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if this method, or `setOutgoingNoChaining()` method already invoked.
    - `APDUException.IO_ERROR` on I/O error.
    `ISOException` - with the following reason codes:
    - `ISO7816.SW_WRONG_LENGTH` if Le field received during the T=1 APDU protocol is greater than 32767 and not 0x0000.

### setOutgoingNoChaining

    public short setOutgoingNoChaining()
                                throws APDUException,
                                       ISOException

  This method is used to set the data transfer direction to outbound without using chaining mode and to obtain the expected length of response (Le). This method should be used in place of the `setOutgoing()` method by applets which need to be compatible with legacy CAD/terminals which do not support chaining mode. See Runtime Environment Specification, Java Card Platform, Classic Edition, chapter 9.4 for details.

  Notes.

  - On a case 4 command, the `setIncomingAndReceive()` must be invoked prior to calling this method. Otherwise, erroneous behavior may result in T=0 protocol.
  - Any remaining incoming data will be discarded.
  - In T=0 (Case 4S) protocol, this method will return 256 with normal semantics.
  - In T=0 (Case 2E, 4S, 4E) protocol, this method will return 256 when the currently selected applet implements the `javacardx.apdu.ExtendedLength` interface.
  - When this method is used, the `waitExtension()` method cannot be used.
  - In T=1 protocol, retransmission on error may be restricted.
  - In some cases of the T=0 protocol, the outbound transfer must be performed without using `(ISO7816.SW_BYTES_REMAINING_00+count)` response status chaining. See the Runtime Environment Specification, Java Card Platform, Classic Edition, chapter 9.4 for details.
  - In T=1 protocol, the outbound transfer must not set the More(M) Bit in the PCB of the I block. See ISO 7816-3.
  - This method sets the state of the `APDU` object to `STATE_OUTGOING`.

  Returns:
    Le, the expected length of response data
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if this method, or `setOutgoing()` method already invoked.
    - `APDUException.IO_ERROR` on I/O error
    `ISOException` - with the following reason codes:
    - `ISO7816.SW_WRONG_LENGTH` if Le field received during the T=1 APDU protocol is greater than 32767 and not 0x0000.

### setOutgoingLength

    public void setOutgoingLength(short len)
                           throws APDUException

  Sets the actual length of response data. If a length of `0` is specified, no data will be output.

  Note:

  - In T=0 (Case 2&4) protocol, the length is used by the Java Card runtime environment to prompt the CAD for GET RESPONSE commands.
  - This method sets the state of the `APDU` object to `STATE_OUTGOING_LENGTH_KNOWN`.

  Parameters:
    `len` - the length of response data
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setOutgoing()` or `setOutgoingNoChaining()` not called or if `setOutgoingAndSend()` already invoked, or this method already invoked.
    - `APDUException.BAD_LENGTH` if any one of the following is true:
      - `len` is negative.
      - `len` is greater than 256 and the currently selected applet does not implement the `javacardx.apdu.ExtendedLength` interface.
      - T=0 protocol is in use, non BLOCK CHAINED data transfer is requested and `len` is greater than 256.
      - T=1 protocol is in use, non BLOCK CHAINED data transfer is requested and `len` is greater than (IFSD-2), where IFSD is the Outgoing Block Size. The -2 accounts for the status bytes in T=1.
    - `APDUException.NO_T0_GETRESPONSE` if T=0 protocol is in use and the CAD does not respond to `(ISO7816.SW_BYTES_REMAINING_00+count)` response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.
    - `APDUException.NO_T0_REISSUE` if T=0 protocol is in use and the CAD does not respond to `(ISO7816.SW_CORRECT_LENGTH_00+count)` response status by re-issuing same APDU command on the same origin logical channel number as that of the current APDU command with the corrected length.
    - `APDUException.IO_ERROR` on I/O error.
  See Also:
    `getOutBlockSize()`

### receiveBytes

    public short receiveBytes(short bOff)
                       throws APDUException

  Gets as many data bytes as will fit without APDU buffer overflow, at the specified offset `bOff`. Gets all the remaining bytes if they fit.

  Notes:

  - The space in the buffer must allow for incoming block size.
  - In T=1 protocol, if all the remaining bytes do not fit in the buffer, this method may return less bytes than the maximum incoming block size (IFSC).
  - In T=0 protocol, if all the remaining bytes do not fit in the buffer, this method may return less than a full buffer of bytes to optimize and reduce protocol overhead.
  - In T=1 protocol, if this method throws an `APDUException` with `T1_IFD_ABORT` reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more input data can be received. No output data can be transmitted. No error status response can be returned.
  - This method sets the state of the `APDU` object to `STATE_PARTIAL_INCOMING` if all incoming bytes are not received.
  - This method sets the state of the `APDU` object to `STATE_FULL_INCOMING` if all incoming bytes are received.

  Parameters:
    `bOff` - the offset into APDU buffer
  Returns:
    number of bytes read. Returns 0 if no bytes are available
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setIncomingAndReceive()` not called or if `setOutgoing()` or `setOutgoingNoChaining()` previously invoked.
    - `APDUException.BUFFER_BOUNDS` if not enough buffer space for incoming block size or if `bOff` is negative.
    - `APDUException.IO_ERROR` on I/O error.
    - `APDUException.T1_IFD_ABORT` if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
  See Also:
    `getInBlockSize()`

### setIncomingAndReceive

    public short setIncomingAndReceive()
                                throws APDUException

  This is the primary receive method. Calling this method indicates that this APDU has incoming data. This method gets as many bytes as will fit without buffer overflow in the APDU buffer following the header. It gets all the incoming bytes if they fit.

  This method should only be called on a case 3 or case 4 command, otherwise erroneous behavior may result.

  Notes:

  - In T=0 ( Case 3&4 ) protocol, the P3 param is assumed to be Lc.
  - Data is read into the buffer at offset 5 for normal APDU semantics.
  - Data is read into the buffer at offset 7 for an extended length APDU (Case 3E/4E).
  - In T=1 protocol, if all the incoming bytes do not fit in the buffer, this method may return less bytes than the maximum incoming block size (IFSC).
  - In T=0 protocol, if all the incoming bytes do not fit in the buffer, this method may return less than a full buffer of bytes to optimize and reduce protocol overhead.
  - This method sets the transfer direction to be inbound and calls `receiveBytes(5)` for normal semantics or `receiveBytes(7)` for extended semantics.
  - This method may only be called once in a `Applet.process()` method.
  - This method sets the state of the `APDU` object to `STATE_PARTIAL_INCOMING` if all incoming bytes are not received.
  - This method sets the state of the `APDU` object to `STATE_FULL_INCOMING` if all incoming bytes are received.

  Returns:
    number of data bytes read. The Le byte, if any, is not included in the count. Returns 0 if no bytes are available.
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setIncomingAndReceive()` already invoked or if `setOutgoing()` or `setOutgoingNoChaining()` previously invoked.
    - `APDUException.IO_ERROR` on I/O error.
    - `APDUException.T1_IFD_ABORT` if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
  See Also:
    `getIncomingLength()`, `getOffsetCdata()`

### sendBytes

    public void sendBytes(short bOff,
                          short len)
                   throws APDUException

  Sends `len` more bytes from APDU buffer at specified offset `bOff`.

  If the last part of the response is being sent by the invocation of this method, the APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD. Requiring that the buffer not be altered allows the implementation to reduce protocol overhead by transmitting the last part of the response along with the status bytes.

  Notes:

  - If `setOutgoingNoChaining()` was invoked, output chaining mode must not be used. See Runtime Environment Specification, Java Card Platform, Classic Edition chapter 9.4 for details.
  - In T=0 protocol, if `setOutgoingNoChaining()` was invoked, Le bytes must be transmitted before `(ISO7816.SW_BYTES_REMAINING_00+remaining bytes)` response status is returned.
  - In T=0 protocol, if this method throws an `APDUException` with `NO_T0_GETRESPONSE` or `NO_T0_REISSUE` reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.
  - In T=1 protocol, if this method throws an `APDUException` with `T1_IFD_ABORT` reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.
  - This method sets the state of the `APDU` object to `STATE_PARTIAL_OUTGOING` if all outgoing bytes have not been sent.
  - This method sets the state of the `APDU` object to `STATE_FULL_OUTGOING` if all outgoing bytes have been sent.

  Parameters:
    `bOff` - the offset into APDU buffer
    `len` - the length of the data in bytes to send
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setOutgoingLength()` not called or `setOutgoingAndSend()` previously invoked or response byte count exceeded or if `APDUException.NO_T0_GETRESPONSE` or `APDUException.NO_T0_REISSUE` or `APDUException.T1_IFD_ABORT` previously thrown.
    - `APDUException.BUFFER_BOUNDS` if `bOff` is negative or `len` is negative or `bOff+len` exceeds the buffer size.
    - `APDUException.IO_ERROR` on I/O error.
    - `APDUException.NO_T0_GETRESPONSE` if T=0 protocol is in use and the CAD does not respond to `(ISO7816.SW_BYTES_REMAINING_00+count)` response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.
    - `APDUException.NO_T0_REISSUE` if T=0 protocol is in use and the CAD does not respond to `(ISO7816.SW_CORRECT_LENGTH_00+count)` response status by re-issuing same APDU command on the same origin logical channel number as that of the current APDU command with the corrected length.
    - `APDUException.T1_IFD_ABORT` if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
  See Also:
    `setOutgoing()`, `setOutgoingNoChaining()`

### sendBytesLong

    public void sendBytesLong(byte[] outData,
                              short bOff,
                              short len)
                       throws APDUException,
                              SecurityException

  Sends `len` more bytes from `outData` byte array starting at specified offset `bOff`.

  If the last of the response is being sent by the invocation of this method, the APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD. Requiring that the buffer not be altered allows the implementation to reduce protocol overhead by transmitting the last part of the response along with the status bytes.

  The Java Card runtime environment may use the APDU buffer to send data to the CAD.

  Notes:

  - If `setOutgoingNoChaining()` was invoked, output chaining mode must not be used. See Runtime Environment Specification, Java Card Platform, Classic Edition chapter 9.4 for details.
  - In T=0 protocol, if `setOutgoingNoChaining()` was invoked, Le bytes must be transmitted before `(ISO7816.SW_BYTES_REMAINING_00+remaining bytes)` response status is returned.
  - In T=0 protocol, if this method throws an `APDUException` with `NO_T0_GETRESPONSE` or `NO_T0_REISSUE` reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.
  - In T=1 protocol, if this method throws an `APDUException` with `T1_IFD_ABORT` reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.
  - This method sets the state of the `APDU` object to `STATE_PARTIAL_OUTGOING` if all outgoing bytes have not been sent.
  - This method sets the state of the `APDU` object to `STATE_FULL_OUTGOING` if all outgoing bytes have been sent.

  Parameters:
    `outData` - the source data byte array
    `bOff` - the offset into OutData array
    `len` - the byte length of the data to send
  Throws:
    `SecurityException` - if the `outData` array is not accessible in the caller's context
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setOutgoingLength()` not called or `setOutgoingAndSend()` previously invoked or response byte count exceeded or if `APDUException.NO_T0_GETRESPONSE` or `APDUException.NO_T0_REISSUE` or `APDUException.NO_T0_REISSUE` previously thrown.
    - `APDUException.IO_ERROR` on I/O error.
    - `APDUException.NO_T0_GETRESPONSE` if T=0 protocol is in use and CAD does not respond to `(ISO7816.SW_BYTES_REMAINING_00+count)` response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.
    - `APDUException.T1_IFD_ABORT` if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
  See Also:
    `setOutgoing()`, `setOutgoingNoChaining()`

### setOutgoingAndSend

    public void setOutgoingAndSend(short bOff,
                                   short len)
                            throws APDUException

  This is the "convenience" send method. It provides for the most efficient way to send a short response which fits in the buffer and needs the least protocol overhead. This method is a combination of `setOutgoing(), setOutgoingLength( len )` followed by `sendBytes ( bOff, len )`. In addition, once this method is invoked, `sendBytes()` and `sendBytesLong()` methods cannot be invoked and the APDU buffer must not be altered.

  Sends `len` byte response from the APDU buffer starting at the specified offset `bOff`.

  Notes:

  - No other `APDU` send methods can be invoked.
  - The APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD.
  - The actual data transmission may only take place on return from `Applet.process()`
  - This method sets the state of the `APDU` object to `STATE_FULL_OUTGOING`.

  Parameters:
    `bOff` - the offset into APDU buffer
    `len` - the bytelength of the data to send
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setOutgoing()` or `setOutgoingAndSend()` previously invoked.
    - `APDUException.IO_ERROR` on I/O error.
    - `APDUException.BAD_LENGTH` if `len` is negative or greater than 256 and the currently selected applet does not implement the `javacardx.apdu.ExtendedLength` interface.

### getCurrentState

    public byte getCurrentState()

  This method returns the current processing state of the `APDU` object. It is used by the `BasicService` class to help services collaborate in the processing of an incoming APDU command. Valid codes are listed in `STATE_*` constants above. See `STATE_INITIAL`.

  Returns:
    the current processing state of the APDU
  See Also:
    `javacard.framework.service.BasicService`

### getCurrentAPDU

    public static APDU getCurrentAPDU()
                               throws SecurityException

  This method is called during the `Applet.process(APDU)` method to obtain a reference to the current `APDU` object.

  Notes:

  - Do not call this method directly or indirectly from within a method invoked remotely via Java Card RMI method invocation from the client. The APDU object and APDU buffer are reserved for use by RMIService. Remote method parameter data may become corrupted.
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns `null`.``

  Returns:
    the current `APDU` object being processed by the dispatched APDU processing thread, null otherwise
  Throws:
    `SecurityException` - if
    - the current context is not the context of the currently selected applet instance or
    - this method was not called, directly or indirectly, from the applet's process method (called directly by the Java Card runtime environment), or
    - the method is called during applet installation or deletion.

### getCurrentAPDUBuffer

    public static byte[] getCurrentAPDUBuffer()
                                       throws SecurityException

  This method is called during the `Applet.process(APDU)` method to obtain a reference to the current APDU buffer. This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns null.

  Notes:

  - Do not call this method directly or indirectly from within a method invoked remotely via Java Card RMI method invocation from the client. The `APDU` object and APDU buffer are reserved for use by `RMIService`. Remote method parameter data may become corrupted.
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns `null`.``

  Returns:
    the APDU buffer of the `APDU` object being processed by the dispatched APDU processing thread, null otherwise
  Throws:
    `SecurityException` - if
    - the current context is not the context of the currently selected applet or
    - this method was not called, directly or indirectly, from the applet's process method (called directly by the Java Card runtime environment), or
    - the method is called during applet installation or deletion.

### getCLAChannel

    public static byte getCLAChannel()

  Returns the logical channel number associated with the current `APDU` command based on the CLA byte. A number in the range 0-19 based on the CLA byte encoding is returned if the command contains logical channel encoding. If the command does not contain logical channel information, 0 is returned.

  Notes:

  - This method returns 0 if the CLA bits (b8,b7,b6) is %b001 which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2005 specification.
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns `0`.``

  See Runtime Environment Specification, Java Card Platform, Classic Edition, chapter 4.3 for encoding details.

  Returns:
    logical channel number, if present, within the CLA byte, 0 otherwise

### waitExtension

    public static void waitExtension()
                              throws APDUException

  Requests additional processing time from CAD. The implementation should ensure that this method needs to be invoked only under unusual conditions requiring excessive processing times. This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method returns null.

  Notes:

  - In T=0 protocol, a NULL procedure byte is sent to reset the work waiting time (see ISO 7816-3).
  - In T=1 protocol, the implementation needs to request the same T=0 protocol work waiting time quantum by sending a T=1 protocol request for wait time extension(see ISO 7816-3).
  - If the implementation uses an automatic timer mechanism instead, this method may do nothing.
  - This method can only be called in the context of the currently selected applet. If this method is called from a thread other than one dispatched by the applet container for APDU processing, this method throws `APDUException` exception with reason code `APDUException.ILLEGAL_USE`.

  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setOutgoingNoChaining()` previously invoked or if this method is called from a thread other than one dispatched by the applet container for APDU processing
    - `APDUException.IO_ERROR` on I/O error

### isCommandChainingCLA

    public boolean isCommandChainingCLA()

  Returns whether the current `APDU` command is the first or part of a command chain. Bit b5 of the CLA byte if set, indicates that the `APDU` is the first or part of a chain of commands.

  Note:

  - This method returns `false` if the CLA bits (b8,b7,b6) is %b001 which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2005 specification.

  See Runtime Environment Specification, Java Card Platform, Classic Edition, chapter 4.3 for encoding details.

  Returns:
    `true` if this APDU is not the last APDU of a command chain, `false` otherwise.
  Since:
    2.2.2

### isSecureMessagingCLA

    public boolean isSecureMessagingCLA()

  Returns `true` if the encoding of the current `APDU` command based on the CLA byte indicates secure messaging. The secure messaging information is in bits (b4,b3) for commands with origin channel numbers 0-3, and in bit b6 for origin channel numbers 4-19.

  Note:

  - This method returns `false` if the CLA bits (b8,b7,b6) is %b001 which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2005 specification.

  See Runtime Environment Specification, Java Card Platform, Classic Edition, section 4.3 for encoding details.

  Returns:
    `true` if the secure messaging bit(s) is(are) nonzero, `false` otherwise
  Since:
    2.2.2

### isISOInterindustryCLA

    public boolean isISOInterindustryCLA()

  Returns whether the current `APDU` command CLA byte corresponds to an interindustry command as defined in ISO 7816-4:2005 specification. Bit b8 of the CLA byte if `0`, indicates that the `APDU` is an interindustry command.

  Returns:
    `true` if this APDU CLA byte corresponds to an ISO interindustry command, `false` otherwise.
  Since:
    2.2.2

### isValidCLA

    public boolean isValidCLA()

  Returns whether the current `APDU` command CLA byte is valid. The CLA byte is invalid if the CLA bits (b8,b7,b6) is %b001, which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2005 specification.

  See Runtime Environment Specification, Java Card Platform, Classic Edition, section 4.3 for encoding details.

  Returns:
    `true` if this APDU CLA byte is valid, `false` otherwise.
  Since:
    3.0

### getIncomingLength

    public short getIncomingLength()

  Returns the incoming data length(Lc). This method can be invoked whenever inbound data processing methods can be invoked during case 1, 3 or 4 processing. It is most useful for an extended length enabled applet to avoid parsing the variable length Lc format in the APDU header.

  Returns:
    the incoming byte length indicated by the Lc field in the APDU header. Return `0` if no incoming data (Case 1)
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setIncomingAndReceive()` not called or if `setOutgoing()` or `setOutgoingNoChaining()` previously invoked.
  Since:
    2.2.2
  See Also:
    `getOffsetCdata()`

### getOffsetCdata

    public short getOffsetCdata()

  Returns the offset within the APDU buffer for incoming command data. This method can be invoked whenever inbound data processing methods can be invoked during case 1, 3 or 4 processing. It is most useful for an extended length enabled applet to avoid parsing the variable length Lc format in the APDU header.

  Returns:
    the offset within the APDU buffer for incoming command data from the previous call to `setIncomingAndReceive()` method. The value returned is either 5 (Lc is 1 byte), or 7 (when Lc is 3 bytes)
  Throws:
    `APDUException` - with the following reason codes:
    - `APDUException.ILLEGAL_USE` if `setIncomingAndReceive()` not called or if `setOutgoing()` or `setOutgoingNoChaining()` previously invoked.
  Since:
    2.2.2
  See Also:
    `getIncomingLength()`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.