ds.ov2.util
Class Protocol_step

java.lang.Object
  ds.ov2.util.Protocol_step

public class Protocol_step
extends Object

Runtime instance of one step of a protocol of the OV-chip protocol layer. Every such Protocol consists of several steps that must be executed exactly in a specific order. Every protocol step transfers some data to the applet, executes some method there and transfers some data back. Instances of this class only describe the protocol steps. The machinery to execute the steps is contained in Host_protocol and Card_protocol.

The step instances are created and maintained in the *_description classes, which are generated by the IDL compiler. The description instances and the protocols and steps therein are shared between the host and the card. For the protocol layer to work it is important that the shared instances of protcols and steps are identical up to one exception. The exception is the method field, which links the code to be executed on the card. This field and its constructor argument are guarded by JAVACARD_APPLET and APPLET_TESTFRAME and are therefore only present on the card and in the applet test frame.

The arguments and results here are the declared arguments and results. On the cards they are used as actual arguments and result. This means that incoming data on the card is directly copied into the arguments here. The methods on the card have to store their results in the result objects here, whose contents is then copied back to the host.

On the host usually separate arrays of APDU_Serializable are used as arguments and results. It is therefore possible to perform some data type conversion (by for instance supplying an APDU_BigInteger where an Bignat is expected). On the host the declared argument and results in instances of this class function only as a type and size reference, see the compatibility check.

Instances of this class cache the total length of the declared results in the field result_size. When the size of the results is changed (for instance in a test frame) this field must be explicitely updated by calling set_result_size() here or Protocol.set_result_sizes() on the protocol that contains this step.

CPP Preprocessing

This class uses the following cpp defines: PACKAGE, PUBLIC, ASSERT, JAVACARD_APPLET, APPLET_TESTFRAME

Execution Environment:

host, card

Author:

Hendrik Tews

Version:

$Revision: 1.13 $

Last Commit:

$Date: 2009-04-09 10:42:17 $ by $Author: tews $

Field Summary

APDU_Serializable[]	arguments The declared arguments.
Void_method	method The code to run on the card when the arguments have been received.
private short	result_size Total length of the declared results in bytes.
APDU_Serializable[]	results The declared results.
byte	step_identifier The number of this step.

Constructor Summary

Protocol_step(byte step_identifier, APDU_Serializable[] arguments, Void_method method, APDU_Serializable[] results)
Create a new protocol step with the supplied arguments.

Method Summary

short	get_result_size() Return the total length of the results.
void	set_result_size() Update the result_size cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

step_identifier

public final byte step_identifier

The number of this step. The first step in a protocol must have number 0, the second number 1, and so on. Normally the IDL compiler generates the code for creating the protocol steps and the generated code will contain the right step numbers.

arguments

public APDU_Serializable[] arguments

The declared arguments.

method

public final Void_method method

The code to run on the card when the arguments have been received.

Only available when JAVACARD_APPLET or APPLET_TESTFRAME is defined.

results

public APDU_Serializable[] results

The declared results.

result_size

private short result_size

Total length of the declared results in bytes. This value is cached here to reduce to overhead of the LE field checking on the card (in Card_protocol.process_send). This field is initialized in the constructor. When the size of the results changes afterwards (for instance in a test frame) this field must be explicitely updated by calling set_result_size() here or Protocol.set_result_sizes() on the protocol that contains this step.

Constructor Detail

Protocol_step

public Protocol_step(byte step_identifier,
                     APDU_Serializable[] arguments,
                     Void_method method,
                     APDU_Serializable[] results)

Create a new protocol step with the supplied arguments. The total length of the results will be cached in result_size.

The method argument is only available on the card and in the APPLET_TESTFRAME. On the host this constructor has only 3 arguments.

Parameters:

step_identifier - the number of this step

arguments - the declared arguments

method - the code to execute on the card; this argument is not present on the host.

results - the declared results

Method Detail

set_result_size

public void set_result_size()

Update the result_size cache.

get_result_size

public short get_result_size()

Return the total length of the results.

Returns:

lenght of the results in bytes