uicc.hci.framework
Interface HCIService

All Known Subinterfaces:

CardEmulationService, ConnectivityService, ReaderService

public interface HCIService

This interface is the base interface for any HCI service.

An HCI service instance shall be a permanent JCRE Entry Point Object

It provides the means for an Applet instance to get access to the resources of a specific HCI service. An Applet instance can retrieve an implementation of a specific service via the HCIDevice.

For a service object that is implementing one of the subinterfaces defined in this API the Applet can only register the corresponding Listener defined in the same package (e.g. a CardEmulationService shall only accept the regsitration of a CardEmulationListener.

An Applet instance shall only be able to register one type of listener per service at any time. Listener registration is persistent.

To receive events via the registered Listeners an Applet instance shall activate the events. All events shall be deactivated by default. Event activation is persistent.

Method Summary

void	activateEvent(byte event) This method is used to activate an event.
void	deactivateEvent(byte event) This method is used to deactivate an event from the list of activated events.
void	deregister(HCIListener listener) This method unregisters the given listener from the service.
boolean	getEventNotificationStatus(byte event) return the activation state of an event.
void	register(HCIListener listener) This method registers a Listener object to the Service instance
void	requestCallbackNotification(byte event) This method requests the HCI framework to call the listener method onCallback(byte event, HCIMessage message) to provide access to the HCIMessage object of the addressed service.

Method Detail

register

void register(HCIListener listener)
              throws HCIException

This method registers a Listener object to the Service instance

Parameters:

listener - listener to be registered with the given service

Throws:

HCIException - with reason code

• HCIException.HCI_WRONG_LISTENER_TYPE in case the listener Object registerd to the service is not implementing the corresponding interface of the HCIService instance.
  • a ReaderListener can only be registered to a ReaderService,
  • a CardEmulationListener can only be registered to a CardEmulationService,
  • a ConnectivityListener can only be registered to a ConnectivityService
• HCIException.HCI_LISTENER_ALREADY_REGISTERED in case a listener Object of the same type has already been registered.

deregister

void deregister(HCIListener listener)

This method unregisters the given listener from the service.

Calling deregister with an argument that does not identify a currently registered HCIListener has no effect.

Parameters:

listener - listener to be unregistered from the service

requestCallbackNotification

void requestCallbackNotification(byte event)
                                 throws HCIException

This method requests the HCI framework to call the listener method onCallback(byte event, HCIMessage message) to provide access to the HCIMessage object of the addressed service.

Calling requestCallbackNotification while no corresponding Listener to this Service is registered has no effect.

The request for invocation of onCallback with this event shall only be valid one time and transient. It is not required that the corresponding Listener has activated the event with the activateEvent method. A deactivation if the event with the deactivateEvent has no effect.

The notification will go to the corresponding Listener interface of this Service instance.

Any incoming HCI event may trigger the HCIListener before this request is forwarded to the HCIListener.

For use in this method, parameters are restricted to the range 0xC0 to 0xFF.

Parameters:

event - event value to be passed to the HCIListener.

Throws:

HCIEception - with reason code HCI_WRONG_EVENT_TYPE in case event is not in the allowed parameter range.

HCIException

activateEvent

void activateEvent(byte event)
                   throws HCIException

This method is used to activate an event.

• Possible values for the parameter event for the different Service objects are:

  For all *Service interfaces:
  • HCIListenr.EVENT_HCI_TRANSMISSION_FAILED
  • HCIListener.EVENT_HCI_RECEPTIONS_FAILED
  • for CardEmulationService:
  • CardEmulationListener.EVENT_GET_PARAMETER_RESPONSE,
  • CardEmulationListener.EVENT_SEND_DATA,
  • CardEmulationListener.EVENT_FIELD_OFF.
  • for ReaderService:
  • ReaderListener.EVENT_GET_PARAMETER_RESPONSE,
  • ReaderListener.EVENT_WRITE_EXCHANGE_DATA_RESPONSE,
  • ReaderListener.EVENT_TARGET_DISCOVERED.
• for ConnectivityService:
  • ConnectivityListener.EVENT_STANDBY.

Parameters:

event - event to be activated

Throws:

HCIEception - with reason code

• HCI_WRONG_EVENT_TYPE in case a wrong event was activated for this Service instance
• HCI_CONDITIONS_NOT_SATISFIEDE if one or more conditions to activate the event are not satisfied
• HCI_CURRENTLY_DISABLED if the interface to the contactless frontend (CLF) is currently disabled and the event is ReaderListener.EVENT_TARGET_DISCOVERED

HCIException

deactivateEvent

void deactivateEvent(byte event)
                     throws HCIException

This method is used to deactivate an event from the list of activated events.

• Possible values for the parameter event for the different Service objects are:

  For all *Service interfaces:
  • HCIListenr.EVENT_HCI_TRANSMISSION_FAILED
  • HCIListener.EVENT_HCI_RECEPTIONS_FAILED
  • for CardEmulationService:
  • CardEmulationListener.EVENT_GET_PARAMETER_RESPONSE,
  • CardEmulationListener.EVENT_SEND_DATA,
  • CardEmulationListener.EVENT_FIELD_OFF.
  • for ReaderService:
  • ReaderListener.EVENT_GET_PARAMETER_RESPONSE,
  • ReaderListener.EVENT_WRITE_EXCHANGE_DATA_RESPONSE,
  • ReaderListener.EVENT_TARGET_DISCOVERED.
• for ConnectivityService:
  • ConnectivityListener.EVENT_STANDBY.

Parameters:

event - event to be activated

Throws:

HCIEception - with reason code HCIException.HCI_WRONG_EVENT_TYPE in case a wrong event was deactivated for this Service instance or in case the event wasn't activated before.

HCIException

getEventNotificationStatus

boolean getEventNotificationStatus(byte event)
                                   throws HCIException

return the activation state of an event.

• Possible values for the parameter event for the different Service objects are:

  For all *Service interfaces:
  • HCIListenr.EVENT_HCI_TRANSMISSION_FAILED
  • HCIListener.EVENT_HCI_RECEPTIONS_FAILED
  • for CardEmulationService:
  • CardEmulationListener.EVENT_GET_PARAMETER_RESPONSE,
  • CardEmulationListener.EVENT_SEND_DATA,
  • CardEmulationListener.EVENT_FIELD_OFF.
  • for ReaderService:
  • ReaderListener.EVENT_GET_PARAMETER_RESPONSE,
  • ReaderListener.EVENT_WRITE_EXCHANGE_DATA_RESPONSE,
  • ReaderListener.EVENT_TARGET_DISCOVERED.
• for ConnectivityService:
  • ConnectivityListener.EVENT_STANDBY.

Parameters:

event - event to request the activation state

Returns:

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

Throws:

HCIEception - with reason code HCIException.HCI_WRONG_EVENT_TYPE in case the event was not one of the possible values.

HCIException