uicc.hci.framework
Interface HCIService

All Known Subinterfaces:

CardEmulationService, ConnectivityService, ReaderService

public interface HCIService

This interface is the base interface for any HCI service.

A service is a JCRE Entry Point Object which allows to register and to unregister listeners in order to get access to their services.

Method Summary

void	activateEvent(byte event) This method is used to configure which events will trigger this service.
void	deactivateEvent(byte event) This method is used remove an event from the list of events which cause notification of this service.
boolean	getEventNotificationStatus(byte event) return the activation state of an event.
void	register(HCIListener listener) Registers the Listener Object to the service.
void	requestCallBackNotification(short event) This method requests the HCI framework to call the listener method onCallBack(short event, HCIMessage message) with the event parameter to provide access to the HCIMessage object of the addressed service.
void	unregister(HCIListener listener) This method unregisters the given listener from the service.

Method Detail

register

void register(HCIListener listener)
              throws HCIException

Registers the Listener Object to the service.

• The listener must correspond to the instance of the HCIService: A ReaderListener can only be registered with a ReaderService, a CardEmulationListener can only be registered with a CardEmulationService and a ConnectivityListener can only be registered with a ConnectivityService, else it will be refused.
• When a listener is registered all specific events of that listener are by default in the state unregistered. The application must activate any event in order to be notified on the event condition.
• An application shall only be able to register one listener per service at any time.

Parameters:

listener - listener to be registered with the given service (editor's note: add exceptions)

Throws:

HCIException

unregister

void unregister(HCIListener listener)

This method unregisters the given listener from the service.

Parameters:

listener - listener to be unregistered from the given service

requestCallBackNotification

void requestCallBackNotification(short event)
                                 throws HCIException

This method requests the HCI framework to call the listener method onCallBack(short event, HCIMessage message) with the event parameter to provide access to the HCIMessage object of the addressed service.

This request is volatile. In case of tear down the application request is lost.

Due to the event driven nature of the HCI framework any incoming HCI event may trigger the HCIListener before this request is forwarded to the HCIListener.

The HCI framework shall buffer exactly one event per Service. If this entry point is called several times before the event can be forwarded to the listener only the last event will be delivered. The value of the parameter must not collide with any event constant which is defined in the HCILister interface(s). Therefore the range of short values < 0 shall be reserved for the use with this method.

Parameters:

event - event value to be passed to the HCIListener. The value of the parameter must not collide with any event constant which is defined in the HCILister interface(s). Therefore the range of short values < 0 shall be reserved for the use with this method.

Throws:

HCIException

See Also:

(editor's note: add exception)

activateEvent

void activateEvent(byte event)
                   throws HCIException

This method is used to configure which events will trigger this service.

• Possible values for the parameter event are...
• For CardEmulationService: CardEmulationListener.EVT_SEND_DATA, CardEmulationListener.EVT_FIELD_ON, CardEmulationListener.EVT_CARD_DEACTIVATED, CardEmulationListener.EVT_CARD_ACTIVATED, CardEmulationListener.EVT_FIELD_OFF.
• For ReaderService: ReaderListener.EVT_TARGET_DISCOVERED.
• For ConnectivityService: ConnectivityListener.EVT_STANDBY.

Parameters:

event - event to be activated (editor's note: add exceptions)

Throws:

HCIException

deactivateEvent

void deactivateEvent(byte event)

This method is used remove an event from the list of events which cause notification of this service.

• Possible values for the parameter event are...
• For CardEmulationService: CardEmulationListener.EVT_SEND_DATA, CardEmulationListener.EVT_FIELD_ON, CardEmulationListener.EVT_CARD_DEACTIVATED, CardEmulationListener.EVT_CARD_ACTIVATED, CardEmulationListener.EVT_FIELD_OFF.
• For ReaderService: ReaderListener.EVT_TARGET_DISCOVERED.
• For ConnectivityService: ConnectivityListener.EVT_STAND_BY.

Parameters:

event - event to be activated (editor's note: add exceptions)

getEventNotificationStatus

boolean getEventNotificationStatus(byte event)

return the activation state of an event.

Parameters:

event - event to inquire activation state

Returns:

true if the event is activated for this listener, else false