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 application 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 application 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).
byte[]	getReceiveBuffer() return the underlying receive message buffer.
short	getReceiveLength() This method returns the length of the received message data.
short	getReceiveOffset() This method returns the offset to the received message data in the receive buffer.
byte	getType() return the message type (b8-b7 of the message header) editor's note: check if this method is still needed.
boolean	isComplete() return true if the message is complete.
boolean	isHeading() return true if the current message part is the heading part of the message e.g the first part of an incoming message (and possibly the last if message is complete).

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()

return true if the current message part is the heading part of the message e.g the first part of an incoming message (and possibly the last if message is complete).

Note that preparing 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()

return true if the message is complete. editor's note: clarify the meaning of the following sentence: This method may be used for incoming messages in order to anticipate a call to the

Please note that preparing 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()

return the message type (b8-b7 of the message header) editor's note: check if this method is still needed.

• TYPE_COMMAND
• TYPE_EVENT
• TYPE_RESPONSE

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.

getInstruction

byte getInstruction()

editor's note: check if needed and reword or delete accordingly). returns the message instruction (b6-b1 of the message header). depending on the message type the instruction specifies a commands, an event or a response code between 0x00 and 0x3F.

Please note that 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.

Please note that preparing an outgoing message (command response or event) will reset the current HCI message states according to the outgoing message.

Returns:

return the message instruction

getReceiveBuffer

byte[] getReceiveBuffer()

return the underlying receive message buffer.

When the listener is triggered with an incoming message the usable data may be found at getReceiveOffset() offset up to getReceiveLength() length. Notes:

• The framework will write the received HCI message to the offset given by getReceiveOffset()
• The framework will copy data in the receive buffer up to its length. When this length is exceeded the HCIMessage will be set as not complete. (in other words when the message is incomplete the receive buffer must be full)
• The application may use the whole receive buffer for its internal purposes, even before the offset returned by getReceiveOffset() and after the length given by getReceiveLength(). For example it may use it as working buffer when preparing an output message.
• The framework implementation shall guarantee a buffer size to receive a message of 270 bytes of data. (so the getReceiveOffset() offset include).
• 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 application) if the buffer is used for manipulation of sensitive data it shall be cleared by the application before returning to the JCRE.

Returns:

return the message receive buffer.

getReceiveOffset

short getReceiveOffset()

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

Returns:

the receive message data offset.

getReceiveLength

short getReceiveLength()

This method returns the length of the received message data. If the message is not complete then the returned value is the actual fragment length.

This methods may be used to detect how many bytes are available for processing in the receive buffer.

Note: The data will be considered as consumed when the Applet returns from the callback method even when the data were not accessed.

Returns:

the message data length available in the receive buffer.

See Also:

isComplete()