ds.ov2.util
Class Registered_protocols

java.lang.Object
  ds.ov2.util.Registered_protocols

public class Registered_protocols
extends Object

Service class for the registered protocols of one applet. This class provides the common functionality for the array of protocols of an applet. The applet specific code must allocate and maintain the protocols array. Everything else (consistency checking, protocol ID setting, protocol lookup) is done here.

Every applet should have precisely one instance of this class (through this is not enforced). In the applet this instance must be registered with Protocol_applet.set_registered_protocols. Newly selected protocols will then be looked up with get_protocol of this instance. The registration with Protocol_applet.set_registered_protocols must be done manually at initialization time, before the applet is selected.

During initialization or whenever the list of protocol changes (because of delayed protocol initialization, for instance) the applet specific code calls set_protocols on the only instance of this class. The instance then stores an alias of the externally allocated protocols array for its operation and computes the necessary data to use this new protocols array.

CPP Preprocessing

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

Execution Environment:

host, card

Author:

Hendrik Tews

Version:

$Revision: 1.3 $

Last Commit:

$Date: 2009-04-03 07:28:44 $ by $Author: tews $

Field Summary

private short	max_protocol_index The first nonaccessible protocol index.
private Protocol[]	protocols Alias to the array of all supported protocols.

Constructor Summary

Registered_protocols()
Normal, empty constructor.

Registered_protocols(Protocol[] protocols)
Convenience constructor, incorporating a call to set_protocols.

Method Summary

private void	check_protocols() Consistency check for the protocol array.
short	get_max_protocol_index() Return max_protocol_index.
Protocol	get_protocol(short ins) Select protocol.
Protocol[]	get_protocols() Return the protocols array.
void	set_protocols(Protocol[] protocols) (Re-)Initialize the protocols array.

Methods inherited from class java.lang.Object

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

Field Detail

protocols

private Protocol[] protocols

Alias to the array of all supported protocols. The array itself must be allocated and maintained outside. Direct assignment to this field is impossible, because clients must use set_protocols to register a new or changed array.

See Also:

get_protocols()

max_protocol_index

private short max_protocol_index

The first nonaccessible protocol index. In the beginning this can be lesser then protocols.length if not all protocols have been initialized yet. Computed in set_protocols.

See Also:

get_max_protocol_index()

Constructor Detail

Registered_protocols

public Registered_protocols()

Normal, empty constructor.

Registered_protocols

public Registered_protocols(Protocol[] protocols)

Convenience constructor, incorporating a call to set_protocols.

Parameters:

protocols - the array of registered protocols, as for set_protocols

Method Detail

get_protocols

public Protocol[] get_protocols()

Return the protocols array. For those applets that do not store it themselves. Changing the array is permitted under the condition that the currently running protocol does not change its position in the array. After changing, set_protocols must be called before the next protocol is selected. This is necessary even if the array itself stays the same and only fields in the array are changed.

get_max_protocol_index

public short get_max_protocol_index()

Return max_protocol_index.

check_protocols

private void check_protocols()

Consistency check for the protocol array. Enforces that

• all elements below max_protocol_index are non-null
• the protocol_id is the same as the array index
• steps and all its elements are be nonnull
• in all steps for the arguments and results arrays the following must hold: Either the array is be null or all its elements are nonnull

Validity of these properties is enforced with assertions (see the ASSERT macro).

set_protocols

public void set_protocols(Protocol[] protocols)

(Re-)Initialize the protocols array. The protocols array itself must be allocated and filled outside of this class in the client. This method computes the protocol ID's, performs consitency checks and stores an alias of the array in protocols. In addition, this method determins max_protocol_index as the maximal index such that all entries less than max_protocol_index in protocols are non-null.

This method can be called several times, for instance to make delayed protocols available at a later stage.

Internally the protocols argument is not copied, only an alias is stored. Changing the protocols array is permitted under the condition that the currently running protocol does not change its position in the array and remains itself unchanged. After changing, set_protocols must be called before the next protocol is selected. This is necessary even if the array itself stays the same and only fields in the array are changed.

Parameters:

protocols - the protocols array, must be non-null but may contain null references. Only protocols before the first null reference get activated.

get_protocol

public Protocol get_protocol(short ins)

Select protocol. Return the protocol with the index ins or null if ins is greater than max_protocol_index. (The argument ins is the INS byte of the first APDU of the first step of a newly selected protocol.)