Keyple C++  0.9.0
Keyple, an Open Source SDK for Ticketing
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
keyple::core::seproxy::plugin::AbstractObservableLocalReader Class Referenceabstract

#include <AbstractObservableLocalReader.h>

Inherits keyple::core::seproxy::plugin::AbstractLocalReader, and keyple::core::seproxy::plugin::ObservableReaderNotifier.

Inherited by keyple::plugin::pcsc::PcscReaderImpl [virtual], and keyple::plugin::stub::StubReaderImpl.

Public Member Functions

 AbstractObservableLocalReader (const std::string &pluginName, const std::string &readerName)
 
virtual ~AbstractObservableLocalReader ()=default
 
bool isSePresent () override
 
void startSeDetection (const ObservableReader::PollingMode pollingMode) final
 
void stopSeDetection () final
 
void setDefaultSelectionRequest (std::shared_ptr< AbstractDefaultSelectionsRequest > defaultSelectionsRequest, const ObservableReader::NotificationMode &notificationMode) final
 
void setDefaultSelectionRequest (std::shared_ptr< AbstractDefaultSelectionsRequest > defaultSelectionsRequest, const ObservableReader::NotificationMode &notificationMode, const ObservableReader::PollingMode pollingMode) final
 
virtual std::shared_ptr< ReaderEventprocessSeInserted ()
 
bool isSePresentPing ()
 
void processSeRemoved ()
 
const ObservableReader::PollingModegetPollingMode () const
 
const MonitoringStategetCurrentMonitoringState () const
 
void switchState (const MonitoringState stateId)
 
void addObserver (const std::shared_ptr< ObservableReader::ReaderObserver > observer) final
 
void removeObserver (const std::shared_ptr< ObservableReader::ReaderObserver > observer) final
 
void notifyObservers (const std::shared_ptr< ReaderEvent > event) final
 
int countObservers () const final
 
void clearObservers () final
 
void terminateSeCommunication () override
 
void finalizeSeProcessing () override
 
void onEvent (const InternalEvent event)
 
- Public Member Functions inherited from keyple::core::seproxy::plugin::AbstractLocalReader
 AbstractLocalReader (const std::string &pluginName, const std::string &readerName)
 
virtual ~AbstractLocalReader ()=default
 
virtual bool isLogicalChannelOpen () const final
 
void addSeProtocolSetting (std::shared_ptr< SeProtocol > seProtocol, const std::string &protocolRule) override
 
virtual void setSeProtocolSetting (const std::map< std::shared_ptr< SeProtocol >, std::string > &protocolSetting) override
 
virtual std::shared_ptr< SelectionStatusopenLogicalChannel (std::shared_ptr< SeSelector > seSelector)
 
std::shared_ptr< SelectionStatusopenLogicalChannelAndSelect (std::shared_ptr< SeSelector > seSelector)
 
virtual std::vector< std::shared_ptr< SeResponse > > processSeRequests (const std::vector< std::shared_ptr< SeRequest >> &seRequests, const MultiSeRequestProcessing &multiSeRequestProcessing, const ChannelControl &channelControl) override
 
virtual std::shared_ptr< SeResponseprocessSeRequest (const std::shared_ptr< SeRequest > seRequest, const ChannelControl &channelControl) override
 
- Public Member Functions inherited from keyple::core::seproxy::plugin::AbstractReader
std::vector< std::shared_ptr< SeResponse > > transmitSeRequests (const std::vector< std::shared_ptr< SeRequest >> &seRequests, const MultiSeRequestProcessing &multiSeRequestProcessing, const ChannelControl &channelControl) override
 
std::shared_ptr< SeResponsetransmitSeRequest (std::shared_ptr< SeRequest > seRequest, const ChannelControl &channelControl) override
 
const std::string & getPluginName () const
 
const std::string & getName () const override
 
- Public Member Functions inherited from keyple::core::seproxy::plugin::AbstractSeProxyComponent
 AbstractSeProxyComponent (const std::string &name)
 
virtual ~AbstractSeProxyComponent ()=default
 
const std::string & getName () const
 
void setParameters (const std::map< const std::string, const std::string > &parameters)
 
virtual void setParameter (const std::string &key, const std::string &value)=0
 
- Public Member Functions inherited from keyple::core::seproxy::message::ProxyReader
virtual ~ProxyReader ()
 
- Public Member Functions inherited from keyple::core::seproxy::SeReader
virtual ~SeReader ()
 
virtual const TransmissionModegetTransmissionMode () const =0
 
virtual bool operator== (const SeReader &o) const
 
- Public Member Functions inherited from keyple::core::seproxy::ProxyElement
virtual ~ProxyElement ()=default
 
virtual const std::map< const std::string, const std::string > & getParameters () const =0
 
virtual void setParameter (const std::string &key, const std::string &value)=0
 
virtual void setParameters (const std::map< const std::string, const std::string > &parameters)
 
- Public Member Functions inherited from keyple::core::seproxy::plugin::ObservableReaderNotifier
 ObservableReaderNotifier ()
 
virtual ~ObservableReaderNotifier ()
 
- Public Member Functions inherited from keyple::core::seproxy::event::ObservableReader
virtual ~ObservableReader ()=default
 
virtual void addObserver (const std::shared_ptr< ReaderObserver > observer)=0
 
virtual void removeObserver (const std::shared_ptr< ReaderObserver > observer)=0
 

Protected Member Functions

virtual std::shared_ptr< ObservableReaderStateServiceinitStateService ()=0
 
- Protected Member Functions inherited from keyple::core::seproxy::plugin::AbstractLocalReader
virtual bool checkSePresence ()=0
 
void closeLogicalAndPhysicalChannels ()
 
virtual const std::vector< uint8_t > & getATR ()=0
 
virtual void setForceGetDataFlag (bool forceGetDataFlag)
 
virtual void openPhysicalChannel ()=0
 
virtual void closePhysicalChannel ()=0
 
virtual bool isPhysicalChannelOpen ()=0
 
void closeLogicalChannel ()
 
virtual bool protocolFlagMatches (const std::shared_ptr< SeProtocol > protocolFlag)=0
 
std::shared_ptr< ApduResponseprocessApduRequest (std::shared_ptr< ApduRequest > apduRequest)
 
virtual std::vector< uint8_t > transmitApdu (const std::vector< uint8_t > &apduIn)=0
 
const std::map< std::shared_ptr< SeProtocol >, std::string > & getProtocolsMap () const
 
- Protected Member Functions inherited from keyple::core::seproxy::plugin::AbstractReader
 AbstractReader (const std::string &pluginName, const std::string &name)
 
virtual ~AbstractReader ()=default
 

Protected Attributes

std::shared_ptr< ObservableReaderStateServicemStateService
 
- Protected Attributes inherited from keyple::core::seproxy::plugin::AbstractReader
std::shared_ptr< DefaultSelectionsRequestmDefaultSelectionsRequest
 
ObservableReader::NotificationMode mNotificationMode
 

Additional Inherited Members

- Public Types inherited from keyple::core::seproxy::event::ObservableReader
enum  PollingMode { PollingMode::REPEATING, PollingMode::SINGLESHOT }
 
- Public Attributes inherited from keyple::core::seproxy::plugin::ObservableReaderNotifier
std::atomic< bool > mShuttingDown
 
- Static Protected Member Functions inherited from keyple::core::seproxy::plugin::AbstractLocalReader
static bool startsWith (const std::vector< uint8_t > &source, const std::vector< uint8_t > &match)
 

Detailed Description

This abstract class is used to manage the matter of observing SE events in the case of a local reader.

It provides the means to configure the plugin's behavior when a SE is detected.

The event management implements a ObservableReaderStateService state machine that is composed of four states.

  1. WAIT_FOR_START_DETECTION

    Infinitely waiting for a signal from the application to start SE detection by changing to WAIT_FOR_SE_INSERTION state. This signal is given by calling the setDefaultSelectionRequest method.

    Note: The system always starts in the WAIT_FOR_START_DETECTION state.

  2. WAIT_FOR_SE_INSERTION

    Awaiting the SE insertion. After insertion, the processSeInserted method is called.

    A number of cases arise:

    • A default selection is defined: in this case it is played and its result leads to an event notification SE_INSERTED or SE_MATCHED or no event (see setDefaultSelectionRequest)
    • There is no default selection: a SE_INSERTED event is then notified.

      In the case where an event has been notified to the application, the state machine changes to the WAIT_FOR_SE_PROCESSING state otherwise it remains in the WAIT_FOR_SE_INSERTION state.

    The notification consists in calling the "update" methods of the defined observers. In the case where several observers have been defined, it is up to the application developer to ensure that there is no long processing in these methods, by making their execution asynchronous for example.

  3. WAIT_FOR_SE_PROCESSING

    Waiting for the end of processing by the application. The end signal is triggered by a transmission made with a CLOSE_AFTER parameter.

    If the instruction given when defining the default selection request is to stop (ObservableReader.PollingMode.SINGLESHOT) then the logical and physical channels are closed immediately and the machine state changes to WAIT_FOR_START_DETECTION state.

    If the instruction given is continue (ObservableReader.PollingMode.REPEATING) then the state machine changes to WAIT_FOR_SE_REMOVAL.

  4. WAIT_FOR_SE_REMOVAL:

    Waiting for the SE to be removed. When the SE is removed, a SE_REMOVED event is notified to the application and the state machine changes to the WAIT_FOR_SE_INSERTION or WAIT_FOR_START_DETECTION state according the polling mode (ObservableReader.PollingMode).

Constructor & Destructor Documentation

◆ AbstractObservableLocalReader()

keyple::core::seproxy::plugin::AbstractObservableLocalReader::AbstractObservableLocalReader ( const std::string &  pluginName,
const std::string &  readerName 
)

Reader constructor

Force the definition of a name through the use of super method.

Parameters
pluginNamethe name of the plugin that instantiated the reader
readerNamethe name of the reader

◆ ~AbstractObservableLocalReader()

virtual keyple::core::seproxy::plugin::AbstractObservableLocalReader::~AbstractObservableLocalReader ( )
virtualdefault

Member Function Documentation

◆ addObserver()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::addObserver ( const std::shared_ptr< ObservableReader::ReaderObserver observer)
final

Add a keyple::core::seproxy::event::ObservableReader::ReaderObserver

The observer will receive all the events produced by this reader (se insertion, removal, etc.)

Parameters
observerthe observer object

◆ clearObservers()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::clearObservers ( )
finalvirtual

Remove all observers at once

Implements keyple::core::seproxy::event::ObservableReader.

◆ countObservers()

int keyple::core::seproxy::plugin::AbstractObservableLocalReader::countObservers ( ) const
finalvirtual
Returns
the number of observers

Implements keyple::core::seproxy::event::ObservableReader.

◆ finalizeSeProcessing()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::finalizeSeProcessing ( )
overridevirtual

Terminates the processing of the SE, in particular after an interruption by exception
Do nothing if the channel is already closed.
Channel closing is nominally managed by using the CLOSE_AFTER flag during the last transmission with the SE. However, there are cases where exchanges with the SE are interrupted by an exception, in which case it is necessary to explicitly close the channel using this method.

Implements keyple::core::seproxy::event::ObservableReader.

◆ getCurrentMonitoringState()

const MonitoringState & keyple::core::seproxy::plugin::AbstractObservableLocalReader::getCurrentMonitoringState ( ) const

(package-private)
Get the current monitoring state

Returns
current getMonitoringState

◆ getPollingMode()

const ObservableReader::PollingMode & keyple::core::seproxy::plugin::AbstractObservableLocalReader::getPollingMode ( ) const

(package-private)
Get polling mode

Returns
the current polling mode

◆ initStateService()

virtual std::shared_ptr<ObservableReaderStateService> keyple::core::seproxy::plugin::AbstractObservableLocalReader::initStateService ( )
protectedpure virtual

Initialize the ObservableReaderStateService with the possible states and their implementation. ObservableReaderStateService define the initial state.

Make sure to initialize the stateService in your reader constructor with stateService = initStateService()

Returns
initialized state stateService with possible states and the init state

Implemented in keyple::plugin::stub::StubReaderImpl, and keyple::plugin::pcsc::PcscReaderImpl.

◆ isSePresent()

bool keyple::core::seproxy::plugin::AbstractObservableLocalReader::isSePresent ( )
overridevirtual

Check the presence of a SE

This method is recommended for non-observable readers.

When the SE is not present the logical and physical channels status may be refreshed through a call to the processSeRemoved method.

Returns
true if the SE is present
Exceptions
KeypleReaderIOExceptionif the communication with the reader or the SE has failed

Reimplemented from keyple::core::seproxy::plugin::AbstractLocalReader.

◆ isSePresentPing()

bool keyple::core::seproxy::plugin::AbstractObservableLocalReader::isSePresentPing ( )

(package-private)
Sends a neutral APDU to the SE to check its presence. The status of the response is not verified as long as the mere fact that the SE responds is sufficient to indicate whether or not it is present.

This method has to be called regularly until the SE no longer respond.

Having this method not final allows a reader plugin to implement its own method.

Returns
true if the SE still responds, false if not

◆ notifyObservers()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::notifyObservers ( const std::shared_ptr< ReaderEvent event)
finalvirtual

Notify all registered observers with the provided keyple::core::seproxy::event::ReaderEvent

Parameters
eventthe reader event

Implements keyple::core::seproxy::plugin::ObservableReaderNotifier.

◆ onEvent()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::onEvent ( const InternalEvent  event)

thread safe method to communicate an internal event to this reader Use this method to inform the reader of external event like a tag discovered or a Se inserted

C++ vs. Java: protected in Java

Parameters
eventinternal event

◆ processSeInserted()

std::shared_ptr< ReaderEvent > keyple::core::seproxy::plugin::AbstractObservableLocalReader::processSeInserted ( )
virtual

(package-private)
This method is invoked when a SE is inserted in the case of an observable reader.

e.g. from the monitoring thread in the case of a Pcsc plugin or from the NfcAdapter callback method onTagDiscovered in the case of a Android NFC plugin.

It will return a ReaderEvent in the following cases:

  • SE_INSERTED: if no default selection request was defined
  • SE_MATCHED: if a default selection request was defined in any mode and a SE matched the selection
  • SE_INSERTED: if a default selection request was defined in ALWAYS mode but no SE matched the selection (the DefaultSelectionsResponse is however transmitted)

It returns null if a default selection is defined in MATCHED_ONLY mode but no SE matched the selection.

Returns
ReaderEvent that should be notified to observers, contains the results of the default selection if any, can be null if no event should be sent

◆ processSeRemoved()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::processSeRemoved ( )

This method is invoked when a SE is removed in the case of an observable reader.

It will also be invoked if isSePresent is called and at least one of the physical or logical channels is still open (case of a non-observable reader)

The SE will be notified removed only if it has been previously notified present (observable reader only)

◆ removeObserver()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::removeObserver ( const std::shared_ptr< ObservableReader::ReaderObserver observer)
final

Remove a keyple::core::seproxy::event::ObservableReader::ReaderObserver

The observer will do not receive any of the events produced by this reader.

Parameters
observerthe observer object

◆ setDefaultSelectionRequest() [1/2]

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::setDefaultSelectionRequest ( std::shared_ptr< AbstractDefaultSelectionsRequest defaultSelectionsRequest,
const ObservableReader::NotificationMode notificationMode 
)
finalvirtual

If defined, the prepared DefaultSelectionRequest will be processed as soon as a SE is inserted. The result of this request set will be added to the reader event notified to the application.

If it is not defined (set to null), a simple SE detection will be notified in the end.

Depending on the notification mode, the observer will be notified whenever an SE is inserted, regardless of the selection status, or only if the current SE matches the selection criteria.

Parameters
defaultSelectionsRequestthe keyple::core::seproxy::event::AbstractDefaultSelectionsRequest to be executed when a SE is inserted
notificationModethe notification mode enum (ALWAYS or MATCHED_ONLY)

Implements keyple::core::seproxy::event::ObservableReader.

◆ setDefaultSelectionRequest() [2/2]

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::setDefaultSelectionRequest ( std::shared_ptr< AbstractDefaultSelectionsRequest defaultSelectionsRequest,
const ObservableReader::NotificationMode notificationMode,
const ObservableReader::PollingMode  pollingMode 
)
finalvirtual

A combination of defining the default selection request and starting the SE detection.

Parameters
defaultSelectionsRequestthe selection request to be operated
notificationModeindicates whether a SE_INSERTED event should be notified even if the selection has failed (ALWAYS) or whether the SE insertion should be ignored in this case (MATCHED_ONLY).
pollingModeindicates the action to be followed after processing the SE: if CONTINUE, the SE detection is restarted, if STOP, the SE detection is stopped until a new call to startSeDetection is made.

Implements keyple::core::seproxy::event::ObservableReader.

◆ startSeDetection()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::startSeDetection ( const ObservableReader::PollingMode  pollingMode)
finalvirtual

Starts the SE detection. Once activated, the application can be notified of the arrival of an SE.

This method must be overloaded by readers depending on the particularity of their management of the start of SE detection.

Note: they must call the super method with the argument PollingMode.

Parameters
pollingModeindicates the action to be followed after processing the SE: if REPEATING, the SE detection is restarted, if SINGLESHOT, the SE detection is stopped until a new call to startSeDetection is made.

Implements keyple::core::seproxy::event::ObservableReader.

◆ stopSeDetection()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::stopSeDetection ( )
finalvirtual

Stops the SE detection.

This method must be overloaded by readers depending on the particularity of their management of the start of SE detection.

Implements keyple::core::seproxy::event::ObservableReader.

◆ switchState()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::switchState ( const MonitoringState  stateId)

(package-private)
Changes the state of the state machine

Parameters
stateId: new stateId

◆ terminateSeCommunication()

void keyple::core::seproxy::plugin::AbstractObservableLocalReader::terminateSeCommunication ( )
overridevirtual

package-private)
This method initiates the SE removal sequence.

The reader will remain in the WAIT_FOR_SE_REMOVAL state as long as the SE is present. It will change to the WAIT_FOR_START_DETECTION or WAIT_FOR_SE_INSERTION state depending on what was set when the detection was started.

Implements keyple::core::seproxy::plugin::AbstractLocalReader.

Member Data Documentation

◆ mStateService

std::shared_ptr<ObservableReaderStateService> keyple::core::seproxy::plugin::AbstractObservableLocalReader::mStateService
protected

Service that handles Internal Events and their impact on the current state of the reader


The documentation for this class was generated from the following files: