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. Every HCI 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.

See Also:

HCIListener

Field Summary

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_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

byte	getInstruction() Returns the instruction part of the HCP message header of the current incomming HCP message, see TS 102 622 for further information.
byte[]	getReceiveBuffer() Return a reference to the underlying HCI message receive buffer.
short	getReceiveLength() This method returns the length of the received HCI message data.
short	getReceiveOffset() This method returns the offset of the received HCI message data in the receive buffer.
byte	getType() Returns the type of the incomming HCI message
boolean	isComplete() Cheks for the completeness of the HCI message.
boolean	isHeading() Checks if the current content is the heading part of an HCI message The heading information indicates the first part of an HCI message; with the isComplete() method it is possible to check weather the complete 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_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 is the heading part of an HCI message The heading information indicates the first part of an HCI message; with the isComplete() method it is possible to check weather the complete message has already been received.

Returns:

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

isComplete

boolean isComplete()

Cheks for the completeness of the HCI message. (edito: delete)

The preparing of an outgoing message (command response or event) may/shall reset the current HCI message states according to the outgoing message.

Returns:

true if the message is complete

getType

byte getType()

Returns the type of the incomming 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:

return 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 incomming HCP message, see TS 102 622 for further information.

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:

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

getReceiveBuffer

byte[] getReceiveBuffer()

Return a reference to the underlying HCI message receive buffer. The length of this buffer is system dependent; it is guaranteed to be at least 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 given 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 HCI 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 content of the array starts at the location indicated by getReceiveOffset() and has the length indicated by getReceiveLength()
• The content of the buffer outside of the area which is used for the HCI message part 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 HCI message.

getReceiveOffset

short getReceiveOffset()

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

Returns:

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

getReceiveLength

short getReceiveLength()

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

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.