uicc.hci.framework
Interface HCIMessage

All Known Subinterfaces:

CardEmulationMessage, ConnectivityMessage, ReaderMessage

public interface HCIMessage

An instance of HCIMessage is used to get access to the content of a received HCI message.

Sub interfaces will typically have additional methods for sending HCI service specific HCI messages.

Instances of HCIMessage hide the fragmentation of messages on the HCI layer (see TS 102 622). However, as receive and send buffers with limited capacity will be used (size depends on the Applet itself) it provides methods to check if a message is complete (see isHeading() and isComplete()) in order to support streaming of long messages. (editors note: move statements about buffer sizes from getReceiveBuffer()to the previous paragraph.) (editor's note: check what the following sentence means:) in order to chain multiple trigger session the Applet will need to use applicative callback for consume or produce the message.

Notes:

(editor's note: The following statement should be placed in the core specification TS 102 705 and it should be reworded using standard terms (synchronous, asynchronous, ...), sha todo)
• The HCI JavaCard API is event based: A call to methods of HCIMessage may not send or receive the data immediately during the execution of the VM. It may store the relevant information and wait the exit from the JCRE in order to execute the message processing as soon as possible (or prepare more data to be read). This avoids to have the VM suspended waiting for IO operation and to manage complex re-entrence. This also permits to wait to return from an ISO context (after SW emission) and avoids other IO concurrency issues. (editor's note: end of part to be moved and reworded)
• Instances of this object shall be temporary JCRE entry point objects.
• The HCI framework provides a shared volatile array in order to limit application memory needs. see getReceiveBuffer()

See Also:

HCIListener

Field Summary

static byte	INS_ANY_CLOSE_PIPE The command to close a pipe
static byte	INS_ANY_GET_PARAMETER The command to get a parameter from a registry
static byte	INS_ANY_OPEN_PIPE The command to open a pipe
static byte	INS_ANY_SET_PARAMETER The command to set a parameter in a registry
static byte	RESP_ADM_E_NO_PIPES_AVAILABLE no more dynamic pipes can be created
static byte	RESP_ANY_E_CMD_NOT_SUPPORTED the command is not supported by the gate
static byte	RESP_ANY_E_CMD_PAR_UNKNOWN the format of the command parameters is wrong
static byte	RESP_ANY_E_INHIBITED command is inhibited due to failure of lower layer identity check
static byte	RESP_ANY_E_NOK command was rejected and/or not completed
static byte	RESP_ANY_E_NOT_CONNECTED the destination host is not connected
static byte	RESP_ANY_E_PIPE_ACCESS_DENIED Permission denied to create a pipe due to a WHITELIST violation
static byte	RESP_ANY_E_PIPE_NOT_OPENED the pipe is not open
static byte	RESP_ANY_E_REG_ACCESS_DENIED permission denied to write/read a value to/from a registry
static byte	RESP_ANY_E_REG_PAR_UNKNOWN the registry parameter identifier is either unknown to the registry or an optional registry parameter is not implemented
static byte	RESP_ANY_OK command completed successfully (with optional parameters)
static byte	TYPE_COMMAND a command
static byte	TYPE_EVENT an event
static byte	TYPE_RESPONSE a response

Method Summary

byte	getInstruction() editor's note: check if needed and reword or delete accordingly). Returns the message instruction (b6-b1 of the message header) from the current incomming HCI message, see TS 102 622 for further information.
byte[]	getReceiveBuffer() Return a refernce to the underlying HCI message receive buffer.
short	getReceiveLength() This method gives the length of the received message data. Editor: is this length that is received or that is copied into the buffer? If the message is not complete then the returned value is the actual message fragment length.
short	getReceiveOffset() This method gives the offset to the received message data in the receive buffer.
byte	getType() Checks the type of the incomming HCI message editor's note: check if this method is still needed. Does this statement provide any value
boolean	isComplete() Cheks for the completnes of the HCI message.
boolean	isHeading() Checks if this is the heading part of an HCI message The heading information indicates the first part of an HCI message with isComplete() it is possible to check weather the complete message has already been received.

Field Detail

TYPE_COMMAND

static final byte TYPE_COMMAND

a command

See Also:

Constant Field Values

TYPE_EVENT

static final byte TYPE_EVENT

an event

See Also:

Constant Field Values

TYPE_RESPONSE

static final byte TYPE_RESPONSE

a response

See Also:

Constant Field Values

INS_ANY_SET_PARAMETER

static final byte INS_ANY_SET_PARAMETER

The command to set a parameter in a registry

See Also:

Constant Field Values

INS_ANY_GET_PARAMETER

static final byte INS_ANY_GET_PARAMETER

The command to get a parameter from a registry

See Also:

Constant Field Values

INS_ANY_OPEN_PIPE

static final byte INS_ANY_OPEN_PIPE

The command to open a pipe

See Also:

Constant Field Values

INS_ANY_CLOSE_PIPE

static final byte INS_ANY_CLOSE_PIPE

The command to close a pipe

See Also:

Constant Field Values

RESP_ANY_OK

static final byte RESP_ANY_OK

command completed successfully (with optional parameters)

See Also:

Constant Field Values

RESP_ANY_E_NOT_CONNECTED

static final byte RESP_ANY_E_NOT_CONNECTED

the destination host is not connected

See Also:

Constant Field Values

RESP_ANY_E_CMD_PAR_UNKNOWN

static final byte RESP_ANY_E_CMD_PAR_UNKNOWN

the format of the command parameters is wrong

See Also:

Constant Field Values

RESP_ANY_E_NOK

static final byte RESP_ANY_E_NOK

command was rejected and/or not completed

See Also:

Constant Field Values

RESP_ADM_E_NO_PIPES_AVAILABLE

static final byte RESP_ADM_E_NO_PIPES_AVAILABLE

no more dynamic pipes can be created

See Also:

Constant Field Values

RESP_ANY_E_REG_PAR_UNKNOWN

static final byte RESP_ANY_E_REG_PAR_UNKNOWN

the registry parameter identifier is either unknown to the registry or an optional registry parameter is not implemented

See Also:

Constant Field Values

RESP_ANY_E_PIPE_NOT_OPENED

static final byte RESP_ANY_E_PIPE_NOT_OPENED

the pipe is not open

See Also:

Constant Field Values

RESP_ANY_E_CMD_NOT_SUPPORTED

static final byte RESP_ANY_E_CMD_NOT_SUPPORTED

the command is not supported by the gate

See Also:

Constant Field Values

RESP_ANY_E_INHIBITED

static final byte RESP_ANY_E_INHIBITED

command is inhibited due to failure of lower layer identity check

See Also:

Constant Field Values

RESP_ANY_E_REG_ACCESS_DENIED

static final byte RESP_ANY_E_REG_ACCESS_DENIED

permission denied to write/read a value to/from a registry

See Also:

Constant Field Values

RESP_ANY_E_PIPE_ACCESS_DENIED

static final byte RESP_ANY_E_PIPE_ACCESS_DENIED

Permission denied to create a pipe due to a WHITELIST violation

See Also:

Constant Field Values

Method Detail

isHeading

boolean isHeading()

Checks if this is the heading part of an HCI message The heading information indicates the first part of an HCI message with isComplete() it is possible to check weather the complete message has already been received.

The preparing of an outgoing message (command response or event) will reset the current HCI message states according the outgoing message.

Returns:

true if the current message is the heading part of the message e.g the first part of an incoming message.

isComplete

boolean isComplete()

Cheks for the completnes of the HCI message.

The preparing of an outgoing message (command response or event) will reset the current HCI message states according the outgoing message.

Returns:

true if the message is complete

getType

byte getType()

Checks the type of the incomming HCI message editor's note: check if this method is still needed. Does this statement provide any value

Please note that in the case of a fragmented incoming message the type is keep in memory even if the data processed is no more in the first heading packet.

Returns:

return the message type, must be one of constant values TYPE_* defined in this interface

getInstruction

byte getInstruction()

editor's note: check if needed and reword or delete accordingly). Returns the message instruction (b6-b1 of the message header) from the current incomming HCI message, see TS 102 622 for further information. Does this statement provide any value

In the case of a fragmented incoming message the instruction is kept in memory even if the data processed is no more in the first heading packet.

The preparing of an outgoing message (command response or event) will reset the current HCI message states and set them according the outgoing message.

Returns:

return the message instruction, must be one of constant values INS_* defined in this interface

getReceiveBuffer

byte[] getReceiveBuffer()

Return a refernce to the underlying HCI message receive buffer. The length of this buffer is system dependend. The framework implementation shall guarantee a buffer size to receive a message of min. 270 bytes.

When the listener is triggered with an incoming message the usable data shall be found in the buffer returned by this method, starting at the offset gven by the method getReceiveOffset(). The length of the received message or message fragment can be retrieved from getReceiveLength().

• The framework shall copy data into the receive buffer up to the end of the buffer. When the HCIMessage is longer then the available buffer length the HCIMessage shall be set as not complete.
• The application may use the whole receive buffer for its internal purposes. If the buffer is used for manipulation of sensitive data it shall be cleared by the Applet before returning to the JCRE. Editor: This has to be clarified we switch between invocation and triggering we need have to agree on a consistent wording
• The content of this array is not guaranteed between several invocations
• The content of the buffer is not cleared between triggering session (even before triggering an other Applet) if the buffer is used for manipulation of sensitive data it shall be cleared by the Applet before returning to the JCRE.

Returns:

the buffer holding the current HCI message.

getReceiveOffset

short getReceiveOffset()

This method gives the offset to the received message data in the receive buffer.

Returns:

the offset into the buffer, retrieved via getReceiveBuffer().

getReceiveLength

short getReceiveLength()

This method gives the length of the received message data. Editor: is this length that is received or that is copied into the buffer? If the message is not complete then the returned value is the actual message fragment length.

Returns:

the message data length available in the receive buffer.