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 HCP message. Every HCP message that is not longer then 270 bytes has to be presented to the Applet as a complete message. In this case the contactless framework is responsible to manage the defragmentation. The contactless framework shall support outgoing HCIMessages of at least 256 bytes.

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 it provides methods to check if a message is complete (see isHeading() and isComplete()) in order to support streaming of long messages.

Instances of this object shall be temporary JCRE entry point objects.

When the applet is invoked by an event not related to an incoming HCI message (e.g. after requestCallbackNotification method), HCIMessage) content is undefined.

See Also:

HCIListener

Field Summary

Fields

Modifier and Type	Field and Description
static byte	RESP_ANY_E_CMD_NOT_SUPPORTED the command is not supported by the gate
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_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 Indicates the HCI message type "command"
static byte	TYPE_EVENT Indicates the HCI message type "event"
static byte	TYPE_RESPONSE Indicates the HCI message type "response"

Method Summary

Modifier and Type	Method and Description
byte	getInstruction() Returns the instruction part of the HCP message header of the current incoming HCP message, see TS 102 622 for further information.
byte[]	getReceiveBuffer() Return a reference to the underlying receive buffer.
short	getReceiveLength() This method returns the length of the data part of the received HCP message.
short	getReceiveOffset() This method returns the offset of the data part of the received HCP message in the receive buffer.
byte	getType() Returns the type of the incoming HCI message In the case of a fragmented incoming message this method shall return the HCI message type coded in the first part of the HCI message.
boolean	isComplete() Checks for the completeness of the HCP message, i.e. the last received HCP packet had the chaining bit CB set to 1.
boolean	isHeading() Checks if the current content contains the heading part of an HCP message The heading information indicates the first part of an HCP message; with the isComplete() method it is possible to check whether the complete HCP message has already been received.

Field Detail

TYPE_COMMAND

static final byte TYPE_COMMAND

Indicates the HCI message type "command"

See Also:

Constant Field Values

TYPE_EVENT

static final byte TYPE_EVENT

Indicates the HCI message type "event"

See Also:

Constant Field Values

TYPE_RESPONSE

static final byte TYPE_RESPONSE

Indicates the HCI message type "response"

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_NOK

static final byte RESP_ANY_E_NOK

command was rejected and/or not completed

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

Method Detail

isHeading

boolean isHeading()

Checks if the current content contains the heading part of an HCP message The heading information indicates the first part of an HCP message; with the isComplete() method it is possible to check whether the complete HCP message has already been received.

Returns:

true if the current message is the heading part of the message

isComplete

boolean isComplete()

Checks for the completeness of the HCP message, i.e. the last received HCP packet had the chaining bit CB set to 1.

Returns:

true if the message is complete

getType

byte getType()

Returns the type of the incoming HCI message

In the case of a fragmented incoming message this method shall return the HCI message type coded in the first part of the HCI message.

Returns:

the HCI message type, it shall be one of constant values TYPE_* defined in this interface

getInstruction

byte getInstruction()

Returns the instruction part of the HCP message header of the current incoming HCP message, see TS 102 622 for further information. The RESP_ANY_* constants defined in this interface may be used to check the response which is contained in the instruction part.

In the case of a fragmented incoming message this method shall return the HCI message instruction coded in the first part of the HCI message.

Returns:

the instruction in the HCP message header, b8,b7 of the return value are set to zero.

getReceiveBuffer

byte[] getReceiveBuffer()

Return a reference to the underlying receive buffer. The length of this buffer is system dependent; it is guaranteed to be at least 270 bytes.

When the listener is invoked with an incoming message the usable data are contained in the buffer returned by this method.

• The framework shall copy data into the receive buffer up to the end of the buffer. When the HCP message 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 contactless framework.
• The current fragment of the data part of the HCP message starts at the location indicated by getReceiveOffset() and has the length indicated by getReceiveLength()
• The content of the buffer outside of the part which is used for the current fragment of the data part of the HCP message is undefined.

Note:

• References to the receive buffer byte array may be stored in local variables or method parameters.
• References to the receive buffer byte array cannot be stored in class variables or instance variables or array components.

Returns:

the buffer holding the current fragment of the received HCP message.

getReceiveOffset

short getReceiveOffset()

This method returns the offset of the data part of the received HCP message in the receive buffer.

Returns:

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

getReceiveLength

short getReceiveLength()

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

Returns:

the size of the message data available in the receive buffer. If the Message object delivered to the Listener interface resulted from a previous call to the requestCallbackNotification method the return value shall be zero.