APDU (Java Card API and Subsets)
Java Card v2.2.2
javacard.framework
Class APDU
javacard.framework.APDU
public final class APDUextends
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 for the Java Card Platform, section 6.2.1 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 for the Java Card Platform, section 6.2.2 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
// process bytes in buffer[5] to buffer[readCount+4];
bytesLeft -= readC
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.
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:,
static&byte
&&&&&&&&&&Transport protocol Media - Contactless Type A
static&byte
&&&&&&&&&&Transport protocol Media - Contactless Type B
static&byte
&&&&&&&&&&Transport protocol Media - Contacted Asynchronous Half Duplex
static&byte
&&&&&&&&&&Media nibble mask in protocol byte
static&byte
&&&&&&&&&&Transport protocol Media - USB
static&byte
&&&&&&&&&&ISO 7816 transport protocol type T=0.
static&byte
&&&&&&&&&&ISO 7816 transport protocol type T=1.
static&byte
&&&&&&&&&&Type nibble mask in protocol byte
static&byte
&&&&&&&&&&This error state of a APDU object occurs when an APDUException
with reason code APDUException.IO_ERROR has been
static&byte
&&&&&&&&&&This error state of a APDU object occurs when an APDUException
with reason code APDUException.NO_T0_GETRESPONSE has been
static&byte
&&&&&&&&&&This error state of a APDU object occurs when an APDUException
with reason code APDUException.NO_T0_REISSUE has been
static&byte
&&&&&&&&&&This error state of a APDU object occurs when an APDUException
with reason code APDUException.T1_IFD_ABORT has been
static&byte
&&&&&&&&&&This is the state of a APDU object when all the
incoming data been received.
static&byte
&&&&&&&&&&This is the state of a APDU object when all outbound data
has been transferred.
static&byte
&&&&&&&&&&This is the state of a new APDU object when only the command
header is valid.
static&byte
&&&&&&&&&&This is the state of a new APDU object when data transfer
mode is outbound but length is not yet known.
static&byte
&&&&&&&&&&This is the state of a APDU object when data transfer
mode is outbound and outbound length is known.
static&byte
&&&&&&&&&&This is the state of a APDU object when incoming data
has partially been received.
static&byte
&&&&&&&&&&This is the state of a APDU object when some outbound
data has been transferred but not all.
&&&&&&&&&&Returns the APDU buffer byte array.
static&byte
&&&&&&&&&&Returns the logical channel number associated with the current APDU command
based on the CLA byte.
&&&&&&&&&&This method is called during the Applet.process(APDU) method
to obtain a reference to the current APDU object.
static&byte[]
&&&&&&&&&&This method is called during the Applet.process(APDU) method
to obtain a reference to the current
APDU buffer.
&&&&&&&&&&This method returns the current processing state of the
APDU object.
static&short
&&&&&&&&&&Returns the configured incoming block size.
&&&&&&&&&&Returns the incoming data length(Lc).
&&&&&&&&&&Returns the Node Address byte (NAD) in T=1 protocol, and 0
in T=0 protocol.
&&&&&&&&&&Returns the offset within the APDU buffer for incoming command data.
static&short
&&&&&&&&&&Returns the configured outgoing block size.
static&byte
&&&&&&&&&&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.
&&&&&&&&&&Returns whether the current APDU command is the first or
part of a command chain.
&&&&&&&&&&Returns whether the current APDU command CLA byte corresponds
to an interindustry command as defined in ISO 5 specification.
&&&&&&&&&&Returns true if the encoding of the current APDU
command based on the
CLA byte indicates secure messaging.
(short&bOff)
&&&&&&&&&&Gets as many data bytes as will fit without APDU buffer overflow,
at the specified offset bOff.
(short&bOff,
short&len)
&&&&&&&&&&Sends len more bytes from APDU buffer at specified offset bOff.
(byte[]&outData,
short&bOff,
short&len)
&&&&&&&&&&Sends len more bytes from outData byte array starting at specified offset
&&&&&&&&&&This is the primary receive method.
&&&&&&&&&&This method is used to set the data transfer direction to
outbound and to obtain the expected length of response (Le).
(short&bOff,
short&len)
&&&&&&&&&&This is the "convenience" send method.
(short&len)
&&&&&&&&&&Sets the actual length of response data.
&&&&&&&&&&This method is used to set the data transfer direction to
outbound without using BLOCK CHAINING (See ISO ) and to obtain the expected length of response (Le).
static&void
&&&&&&&&&&Requests additional processing time from CAD.
STATE_INITIAL
public static final byte STATE_INITIAL
This is the state of a new APDU object when only the command
header is valid.
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.
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.
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.
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.
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.
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.
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
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
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
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
PROTOCOL_MEDIA_MASK
public static final byte PROTOCOL_MEDIA_MASK
Media nibble mask in protocol byte
PROTOCOL_TYPE_MASK
public static final byte PROTOCOL_TYPE_MASK
Type nibble mask in protocol byte
PROTOCOL_T0
public static final byte PROTOCOL_T0
ISO 7816 transport protocol type T=0.
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.
PROTOCOL_MEDIA_DEFAULT
public static final byte PROTOCOL_MEDIA_DEFAULT
Transport protocol Media - Contacted Asynchronous Half Duplex
PROTOCOL_MEDIA_CONTACTLESS_TYPE_A
public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A
Transport protocol Media - Contactless Type A
PROTOCOL_MEDIA_CONTACTLESS_TYPE_B
public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_B
Transport protocol Media - Contactless Type B
PROTOCOL_MEDIA_USB
public static final byte PROTOCOL_MEDIA_USB
Transport protocol Media - USB
public byte[] getBuffer()
Returns the APDU buffer byte array.
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 for the Java Card Platform, section 6.2.2 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.
On receiveBytes() the bOff param
should account for this potential blocksize.
Returns:incoming block size settingSee Also:
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 BLOCK CHAINING is not allowed.
On setOutgoingLength() the len param
should account for this potential blocksize.
Returns:outgoing block size settingSee Also:
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.
Returns:the protocol media and type in progress
Valid nibble codes are listed in PROTOCOL_* constants above. See .
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()
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.
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) 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
- with the following reason codes:
APDUException.ILLEGAL_USE if this method, or setOutgoingNoChaining() method already invoked.
APDUException.IO_ERROR on I/O error.
setOutgoingNoChaining
public short setOutgoingNoChaining()
This method is used to set the data transfer direction to
outbound without using BLOCK CHAINING (See ISO ) 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 ISO
defined block chaining.
See Runtime Environment
Specification for the Java Card Platform, section 9.4 for details.
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) 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 T=0 protocol, the outbound transfer must be performed
without using (ISO7816.SW_BYTES_REMAINING_00+count) response status chaining.
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
- with the following reason codes:
APDUException.ILLEGAL_USE if this method, or setOutgoing() method already invoked.
APDUException.IO_ERROR on I/O error
setOutgoingLength
public void setOutgoingLength(short&len)
Sets the actual length of response data. If a length of 0 is specified, no data will be output.
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
- 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:
receiveBytes
public short receiveBytes(short&bOff)
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.
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
- 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.
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.
setIncomingAndReceive
public short setIncomingAndReceive()
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.
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.
- 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:,
public void sendBytes(short&bOff,
short&len)
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
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.
If setOutgoingNoChaining() was invoked, output block chaining must not be used.
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 bufferlen - the length of the data in bytes to send
- 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:,
sendBytesLong
public void sendBytesLong(byte[]&outData,
short&bOff,
short&len)
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
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.
If setOutgoingNoChaining() was invoked, output block chaining must not be used.
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 arraybOff - the offset into OutData arraylen - the byte length of the data to send
- if the outData array is not accessible in the caller's context
- 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:,
setOutgoingAndSend
public void setOutgoingAndSend(short&bOff,
short&len)
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.
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 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 bufferlen - the bytelength of the data to send
- 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 .
Returns:the current processing state of the APDUSee Also:
getCurrentAPDU
public static
getCurrentAPDU()
This method is called during the Applet.process(APDU) method
to obtain a reference to the current APDU object.
This method can only be called in the context of the currently
selected applet.
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.
Returns:the current APDU object being processed
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()
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.
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.
Returns:the APDU buffer of the APDU object being processed
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.
See Runtime Environment
Specification for the Java Card Platform, section
4.3 for encoding details.
Returns:logical channel number, if present, within the CLA byte, 0 otherwise
waitExtension
public static void waitExtension()
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.
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.
- with the following reason codes:
APDUException.ILLEGAL_USE if setOutgoingNoChaining() previously invoked.
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.
See Runtime Environment Specification for the Java Card Platform, section 4.3 for encoding details.
Returns:true if this APDU is not the last APDU of a command chain,
false otherwise.Since:
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.
See Runtime Environment Specification for the Java Card Platform, section 4.3 for encoding details.
Returns:true if the secure messaging bit(s) is(are) nonzero,
false otherwiseSince:
isISOInterindustryCLA
public boolean isISOInterindustryCLA()
Returns whether the current APDU command CLA byte corresponds
to an interindustry command as defined in ISO 5 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
interindustry command, false otherwise.Since:
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)
- with the following reason codes:
APDUException.ILLEGAL_USE if setIncomingAndReceive() not called or
if setOutgoing() or setOutgoingNoChaining() previously invoked.Since:
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)
- with the following reason codes:
APDUException.ILLEGAL_USE if setIncomingAndReceive() not called or
if setOutgoing() or setOutgoingNoChaining() previously invoked.Since:
Java Card v2.2.2
Copyright &#169;
Sun Microsystems, Inc. 4150 Network Circle,Santa Clara, CA, 95054, U.S.A.
All Rights Reserved.