HCIService (ETSI TS 102 705 10.2.0 Annex A: HCI API for Java Card(TM))

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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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 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 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:
    
    HCIException - with reason code HCI_ACCESS_NOT_GRANTED.
  - 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 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:
    HCIException - 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
  - 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 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:
    
    HCIException - 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.
  - 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:
    
    HCIException - with reason code HCIException.HCI_WRONG_EVENT_TYPE in case the event was not one of the possible values.

Interface HCIService

Method Summary

Method Detail

register

deregister

requestCallbackNotification

activateEvent

deactivateEvent

getEventNotificationStatus