net.rim.device.api.smartcard
Class CommandAPDU

java.lang.Object
  extended by net.rim.device.api.smartcard.CommandAPDU

public class CommandAPDU
extends Object

Represents a command Application Protocol Data Unit (APDU). ISO 7816-4 defines Command APDUs. The CommandAPDU object is designed as mutable to minimize garbage collection.

  +--------------------------------------------------+
  | CLA | INS | P1 | P2 | Lc Field | Data | Le Field |
  +--------------------------------------------------+

  The command header is composed of CLA, INS, P1, P2.
  LcField = Length of data contained in the Data field
  LeField = Length of data expected in the response
  The body is composed of combinations of Lc Field, Data and Le Field as described below in the 4 cases.

  There are 4 structures of command APDUs as illustrated in ISO/IEC 7816-4:

  Case 1:
  +----------------+
  | Command Header |
  +----------------+

  Case 2:
  +---------------------------+
  | Command Header | Le Field |
  +---------------------------+

  Case 3:
  +----------------------------------------+
  | Command Header | Lc Field | Data Field |
  +----------------------------------------+

  Case 4:
  +---------------------------------------------------+
  | Command Header | Lc Field | Data Field | Le Field |
  +---------------------------------------------------+

  Typical usage scenario:
      CommandAPDU cmd = new CommandAPDU( CLASS, INS, P1, P2 );
      ResponseAPDU response = new ResponseAPDU();
      byte cmdToSend[] = {  (byte)0x00, (byte)0xa0, (byte)0x00, (byte)0x00,
                            (byte)0x02, (byte)0x3f, (byte)0x00};
      cmd.setLcData( dataToSend );
      reader.sendAPDU(cmd, response);
 

See Also:
SmartCardReaderSession, SmartCardSession, ResponseAPDU
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

Field Summary
Category: Signed static int CASE_1
           
Category: Signed static int CASE_2
          Represents the case 2 command APDU structure.
Category: Signed static int CASE_3
          Represents the case 3 command APDU structure.
Category: Signed static int CASE_4
          Represents the case 4 command APDU structure.
 
Constructor Summary
Category: Signed CommandAPDU(byte CLA, byte INS, byte P1, byte P2)
          Constructs a case 1 CommandAPDU object.
Category: Signed CommandAPDU(byte CLA, byte INS, byte P1, byte P2, byte[] LcData)
          Constructs a case 3 CommandAPDU object.
Category: Signed CommandAPDU(byte CLA, byte INS, byte P1, byte P2, byte[] LcData, int Le)
          Constructs a case 4 CommandAPDU object.
Category: Signed CommandAPDU(byte CLA, byte INS, byte P1, byte P2, int Le)
          Constructs a case 2 CommandAPDU object.
 
Method Summary
Category: Signed  void appendLcData(byte[] moreLcData)
          Append data to the command data.
Category: Signed  void appendLcData(byte[] moreLcData, int offset, int length)
          Append data to the command data.
Category: Signed  byte[] getAPDU()
          Get the full APDU command, including the Command header and body if one exists.
Category: Signed  byte getCLA()
          Returns the class type of the instruction.
Category: Signed  int getCase()
          Get the case of the APDU.
Category: Signed  byte getINS()
          Returns the instruction.
Category: Signed  int getLc()
          Get the command data length.
Category: Signed  byte[] getLcData()
          Get the command data.
Category: Signed  int getLe()
          Get the maximum number of bytes expected in the data field of the ResponseAPDU.
Category: Signed  byte getP1()
          Get the first instruction parameter.
Category: Signed  byte getP2()
          Get the second instruction parameter.
Category: Signed  boolean isExtended()
          Determine if the APDU command set so far is of type short or extended.
Category: Signed  void set(byte CLA, byte INS, byte P1, byte P2)
          Reinitializes a CommandAPDU object to a case 1 structure.
Category: Signed  void set(byte CLA, byte INS, byte P1, byte P2, byte[] LcData)
          Reinitializes a CommandAPDU
Category: Signed  void set(byte CLA, byte INS, byte P1, byte P2, byte[] LcData, int Le)
          Reinitializes a CommandAPDU object to a case 4 structure.
Category: Signed  void set(byte CLA, byte INS, byte P1, byte P2, int Le)
          Reinitializes a CommandAPDU object to a case 2 structure.
Category: Signed  void setLcData(byte[] LcData)
          Set the command data.
Category: Signed  void setLcData(byte[] LcData, int offset, int length)
          Set the command data.
Category: Signed  void setLe(int Le)
          Set the maximum number of bytes expected in the data field of the ResponseAPDU object.
Category: Signed  String toString()
          Returns a String representation of the object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 



Field Detail

CASE_1

public static final int CASE_1
See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

CASE_2

public static final int CASE_2
Represents the case 2 command APDU structure.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

CASE_3

public static final int CASE_3
Represents the case 3 command APDU structure.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

CASE_4

public static final int CASE_4
Represents the case 4 command APDU structure.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0


Constructor Detail

CommandAPDU

public CommandAPDU(byte CLA,
                   byte INS,
                   byte P1,
                   byte P2)
Constructs a case 1 CommandAPDU object.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

CommandAPDU

public CommandAPDU(byte CLA,
                   byte INS,
                   byte P1,
                   byte P2,
                   int Le)
Constructs a case 2 CommandAPDU object.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
Le - The maximum number of bytes expected in the data field of the ResponseAPDU. Note that to create an APDU of form Case 2E, from the ISO/IEC 7816-4 spec, with Le = 0, then Le = 65536 should be entered into the constructor.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

CommandAPDU

public CommandAPDU(byte CLA,
                   byte INS,
                   byte P1,
                   byte P2,
                   byte[] LcData)
Constructs a case 3 CommandAPDU object.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
LcData - The command data.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

CommandAPDU

public CommandAPDU(byte CLA,
                   byte INS,
                   byte P1,
                   byte P2,
                   byte[] LcData,
                   int Le)
Constructs a case 4 CommandAPDU object.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
LcData - The command data.
Le - The maximum number of bytes expected in the data field of the ResponseAPDU.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0


Method Detail

set

public void set(byte CLA,
                byte INS,
                byte P1,
                byte P2)
Reinitializes a CommandAPDU object to a case 1 structure.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

set

public void set(byte CLA,
                byte INS,
                byte P1,
                byte P2,
                int Le)
Reinitializes a CommandAPDU object to a case 2 structure.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
Le - The maximum number of bytes expected in the data field of the ResponseAPDU.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

set

public void set(byte CLA,
                byte INS,
                byte P1,
                byte P2,
                byte[] LcData)
Reinitializes a CommandAPDU

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
LcData - The command data.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

set

public void set(byte CLA,
                byte INS,
                byte P1,
                byte P2,
                byte[] LcData,
                int Le)
Reinitializes a CommandAPDU object to a case 4 structure.

Parameters:
CLA - The class of the instruction.
INS - The instruction.
P1 - Parameter One.
P2 - Parameter Two.
LcData - The command data.
Le - The maximum number of bytes expected in the data field of the ResponseAPDU.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getCLA

public byte getCLA()
Returns the class type of the instruction.

Returns:
The class type of the instruction.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getINS

public byte getINS()
Returns the instruction.

Returns:
The instruction code.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getP1

public byte getP1()
Get the first instruction parameter.

Returns:
Instruction Parameter One.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getP2

public byte getP2()
Get the second instruction parameter.

Returns:
Instruction Parameter Two.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

setLcData

public void setLcData(byte[] LcData)
Set the command data.

Note that this automatically sets the command data length, and determines if the command is sent is short or extended mode.

Parameters:
LcData - The command data.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

setLcData

public void setLcData(byte[] LcData,
                      int offset,
                      int length)
Set the command data.

Note that this automatically sets the command data length, and determines if the command is sent is short or extended mode.

Parameters:
LcData - The command data.
offset - Offset into the LcData array to start using.
length - Number of bytes of the LcData to use starting from the offset.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

appendLcData

public void appendLcData(byte[] moreLcData)
Append data to the command data.

Note that this automatically sets the command data length, and determines if the command is sent is short or extended mode.

Parameters:
moreLcData - The data to append.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

appendLcData

public void appendLcData(byte[] moreLcData,
                         int offset,
                         int length)
Append data to the command data.

Note that this automatically sets the command data length, and determines if the command is sent is short or extended mode.

Parameters:
moreLcData - The data to append.
offset - The offset into the LcData array to start using.
length - The number of bytes of the LcData to use starting from the offset.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getLcData

public byte[] getLcData()
Get the command data.

Returns:
A reference to the command data.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getLc

public int getLc()
Get the command data length.

Note that the command data length is set automatically by setting the command data.

Returns:
The command data length, or -1 if there is no command data ( case 1 and case 2 ).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

setLe

public void setLe(int Le)
Set the maximum number of bytes expected in the data field of the ResponseAPDU object.

Parameters:
Le - The maximum number of bytes expected in the data field of the ResponseAPDU.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getLe

public int getLe()
Get the maximum number of bytes expected in the data field of the ResponseAPDU.

Returns:
An integer representing the number of bytes in the data field, or -1 if there is no data ( case 1 and case 3 ).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getCase

public int getCase()
Get the case of the APDU.

This can be one of CASE_1, CASE_2, CASE_3, CASE_4 or CASE_UNKNOWN.

Returns:
An integer representing the case of the APDU.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

isExtended

public boolean isExtended()
Determine if the APDU command set so far is of type short or extended.

Returns:
True if the command APDU is extended ( two byte lengths ), false if the command APDU is short ( one byte length ). Returns false if the command is a case 1 structure, where there is no length data.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getAPDU

public byte[] getAPDU()
Get the full APDU command, including the Command header and body if one exists.

Returns:
The full command APDU.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

toString

public String toString()
Returns a String representation of the object.

The String includes the the full command APDU in hex byte pairs

Overrides:
toString in class Object
Returns:
A String represention of the object.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.