uicc.hci.framework
Interface HCIService

All Known Subinterfaces:

CardEmulationService, CLTObserverService, 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 registration of a CardEmulationListener.

An Applet instance shall only be able to register one type of listener per Service Interface 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 shall not be used.

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 registered 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 CLTObserverListener can only be registered to a CLTObserverService,
  • 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 shall not be used. It is retained for binary interoperability only and will throw and exception when invoked.

Parameters:

event - without meaning (as any invocation of the method will throw and exception)

Throws:

HCIEception - with reason code HCI_ACCESS_NOT_GRANTED.

HCIException

activateEvent

void activateEvent(byte event)
                   throws HCIException

This method is used to activate an event.

The Applet can at any time activate an event, it will receive this event only when the corresponding Listener sub-interface is registered.

• 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_ON_SEND_DATA,
    • CardEmulationListener.EVENT_FIELD_OFF.
  • for CLTObserverService:
    • CLTObserverListener. EVENT_CLT_TRANSACTION_A_DONE.
  • 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_SATISFIED if one or more conditions to activate the event are not satisfied: e.g. if the event is ReaderListener.* and the Applet requesting the activation in not in the lifecycle state ACTIVATED.
  • HCI_CURRENTLY_DISABLED if the interface to the contactless frontend (CLF) is currently disabled and the event is:
    • ReaderListener.EVENT_TARGET_DISCOVERED
    • ReaderListener.EVENT_READER_STATUS

  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_ON_SEND_DATA,
    • CardEmulationListener.EVENT_FIELD_OFF.
  • for CLTObserverService:
    • CLTObserverListener. EVENT_CLT_TRANSACTION_A_DONE.
  • 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 deactivated

  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 CLTObserverService:
    • CLTObserverListener.EVENT_CLT_TRANSACTION_A_DONE.
  • 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