basicservice

• java.lang.Object
  

All Implemented Interfaces: Service

Direct Known Subclasses: RMIService

public class BasicServiceextends Object implements Service

This class should be used as the base class for implementing services. It provides a default implementation for the methods defined in the Service interface, and defines a set of helper methods that manage the APDU buffer to enable co-operation among different Services. The BasicService class uses the state of APDU processing to enforce the validity of the various helper operations. It expects and maintains the following Common Service Format (CSF) of data in the APDU Buffer corresponding to the various APDU processing states (See APDU): Init State format of APDU Buffer. This format corresponds to the APDU processing state - STATE_INITIAL : 012345 < - offset +————————————————————+ | CLA | INS | P1 | P2 | P3 | … Implementation dependent …| +————————————————————+

Input Ready format of APDU Buffer. This format corresponds to the APDU processing state - STATE_FULL_INCOMING. 012345 < - offset +————————————————————+ | CLA | INS | P1 | P2 | Lc | Incoming Data( Lc bytes )| +————————————————————+

Output Ready format of APDU Buffer. This format corresponds to the APDU processing status - STATE_OUTGOING .. STATE_FULL_OUTGOING 012345 < - offset +————————————————————+ | CLA | INS | SW1 | SW2 | La | Outgoing Data( La bytes )| +————————————————————+

When the APDU buffer is in the Init and Input Ready formats, the helper methods allow input access methods but flag errors if output access is attempted. Conversely, when the APDU buffer is in the Output format, input access methods result in exceptions.

The Common Service Format (CSF) of the APDU Buffer is only defined for APDUs using the short length (normal semantics) of the ISO7816 protocol. When an implementation supports extended length APDU format (see ExtendedLength ) and an APDU with more than 255 input or output data bytes is being processed, the behavior of BasicService class is undefined.

If the header areas maintained by the BasicService helper methods are modified directly in the APDU buffer and the format of the APDU buffer described above is not maintained, unexpected behavior might result.

In addition, both La=0 and La=256 are represented in the CSF format as La=0. The distinction is implementation dependent. The getOutputLength method must be used to avoid ambiguity.

Many of the helper methods also throw exceptions if the APDU object is in an error state ( processing status code<0 ).

Version:

1.0

See Also:APDU ,javacardx.apdu.ExtendedLength

public BasicService()

Creates new BasicService.

public boolean processDataIn(APDU  apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:processDataInin interface Service

Parameters:apdu - the APDU object containing the command being processed

Returns:false

public boolean processCommand(APDU  apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:processCommandin interface Service

Parameters:apdu - the APDU object containing the command being processed

Returns:false

public boolean processDataOut(APDU  apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:processDataOutin interface Service

Parameters:apdu - the APDU object containing the command being processed

Returns:false

public short receiveInData(APDU  apdu) throws ServiceException

Receives the input data for the command in the APDU object if the input has not already been received. The entire input data must fit in the APDU buffer starting at offset 5. When invoked, the APDU object must either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format

Parameters:apdu - the APDU object containing the apdu being processed

Returns:the length of input data received and present in the APDU Buffer

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING or,

• ServiceException.COMMAND_DATA_TOO_LONG if the input data does not fit in the APDU buffer starting at offset 5.

public void setProcessed(APDU  apdu) throws ServiceException

Sets the processing state of the command in the APDU object toprocessed. This is done by setting the APDU object in outgoing mode by invoking the APDU.setOutgoing method. If the APDU is already in outgoing mode, this method does nothing (allowing the method to be called several times).

Parameters:apdu - the APDU object containing the command being processed

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:javacard.framework.APDU.getCurrentState()

public boolean isProcessed(APDU  apdu)

Checks if the command in the APDU object has already beenprocessed. This is done by checking whether or not the APDU object has been set in outgoing mode via a previous invocation of the APDU.setOutgoing method. Note:

• This method returns true if the APDU object is not accessible (APDU object in STATE_ERROR_.. ).

Parameters:apdu - the APDU object containing the command being processed

Returns:true if the command has been processed, false otherwise

public void setOutputLength(APDU  apdu, short length) throws ServiceException

Sets the output length of the outgoing response for the command in the APDU object. This method can be called regardless of the current state of the APDU processing.

Parameters:apdu - the APDU object containing the command being processed

length - the number of bytes in the response to the command

Throws: ServiceException- with the following reason code:

• ServiceException.ILLEGAL_PARAM if the length parameter is greater than 256 or if the outgoing response will not fit within the APDU Buffer.

public short getOutputLength(APDU  apdu) throws ServiceException

Returns the output length for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.

Parameters:apdu - the APDU object containing the command being processed

Returns:a value in the range: 0 to 256(inclusive), that represents the number of bytes to be returned for this command

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:javacard.framework.APDU.getCurrentState()

public void setStatusWord(APDU  apdu, short sw)

Sets the response status word for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

Parameters:apdu - the APDU object containing the command being processed

sw - the status word response for this command

public short getStatusWord(APDU  apdu) throws ServiceException

Returns the response status word for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.

Parameters:apdu - the APDU object containing the command being processed

Returns:the status word response for this command

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:javacard.framework.APDU.getCurrentState()

public boolean fail(APDU  apdu, short sw) throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed. Sets the output length to 0 and the status word of the response to the specified value.

Parameters:apdu - the APDU object containing the command being processed

sw - the status word response for this command

Returns:true

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:javacard.framework.APDU.getCurrentState()

public boolean succeed(APDU  apdu) throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded. Sets the status word of the response to 0x9000. The output length of the response must be set separately.

Parameters:apdu - the APDU object containing the command being processed.

Returns:true

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:javacard.framework.APDU.getCurrentState()

public boolean succeedWithStatusWord(APDU  apdu, short sw) throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded. Sets the the status word of the response to the specified value. The output length of the response must be set separately.

Parameters:apdu - the APDU object containing the command being processed

sw - the status word to be returned for this command

Returns:true

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:javacard.framework.APDU.getCurrentState()

public byte getCLA(APDU  apdu)

Returns the class byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the currentcommand.

Parameters:apdu - the APDU object containing the command being processed

Returns:the value of the CLA byte

public byte getINS(APDU  apdu)

Returns the instruction byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the currentcommand.

Parameters:apdu - the APDU object containing the command being processed

Returns:the value of the INS byte

public byte getP1(APDU  apdu) throws ServiceException

Returns the first parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.

Parameters:apdu - the APDU object containing the command being processed

Returns:the value of the P1 byte

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

public byte getP2(APDU  apdu) throws ServiceException

Returns the second parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.

Parameters:apdu - the APDU object containing the command being processed

Returns:the value of the P2 byte

Throws: ServiceException- with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

public boolean selectingApplet()

This method is used to determine if the command in the APDU objectis the applet SELECT FILE command which selected the currently selected applet.

Returns:true if applet SELECT FILE command is being processed