Add doc to NFCController

pull/7822/head
Donatien Garnier 2018-08-07 16:25:17 +01:00
parent 2fb635a28d
commit 37263c359a
1 changed files with 79 additions and 3 deletions
features/nfc/nfc

View File

@ -29,32 +29,104 @@ namespace nfc {
class NFCRemoteTarget;
class NFCControllerDriver;
/**
* @addtogroup nfc
* @{
*/
/**
* This class represents a NFC Controller.
*
* A controller can be in one of three different states:
* * Idle/sleep state
* * Discovery state: The controller tries to discover a remote endpoint (initiator or target)
* * Connected state: The controller exchanges data with an endpoint (initiator or target)
*
* A NFCController instance needs to be initialized with a NFCControllerDriver instance which abstracts the specific controller being used.
* A delegate needs to be set by the user to receive discovery events.
*/
class NFCController {
public:
/**
* The NFCController delegate. Users of the NFCController class need to implement this delegate's methods to receive events.
*/
struct Delegate {
/**
* A enumeration of causes for the discovery process terminating.
*/
enum nfc_discovery_terminated_reason_t {
nfc_discovery_terminated_completed = 0,
nfc_discovery_terminated_canceled,
nfc_discovery_terminated_rf_error
nfc_discovery_terminated_completed = 0, ///< Process completed, at least one endpoint was discovered
nfc_discovery_terminated_canceled, ///< Process was canceled by the user
nfc_discovery_terminated_rf_error ///< An unexpected error was encountered during an exchange on the air interface
};
/**
* The discovery process terminated.
* @param[in] reason the cause for the termination
*/
virtual void on_discovery_terminated(nfc_discovery_terminated_reason_t reason) {}
/**
* A remote initiator was discovered (the local controller is in target mode).
* @param[in] the NFCRemoteInitiator instance
*/
virtual void on_nfc_initiator_discovered(const NFCRemoteInitiator& nfc_initiator) {}
/**
* A remote target was discovered (the local controller is in initiator mode).
* @param[in] the NFCRemoteTarget instance
*/
virtual void on_nfc_target_discovered(const NFCRemoteTarget& nfc_target) {}
};
/**
* Construct a NFCController instance.
*
* @param[in] driver a pointer to a NFCControllerDriver instance
* @param[in] queue a pointer to the events queue to use
*/
NFCController(NFCControllerDriver* driver, events::EventQueue* queue);
/**
* Set the delegate that will receive events generated by this controller.
*
* @oaram[in] delegate the delegate instance to use
*/
void set_delegate(Delegate* delegate);
/**
* Get the list of RF protocols supported by this controller.
*
* @return a bitmask of RF protocols supported by the controller
*/
nfc_rf_protocols_bitmask_t get_supported_rf_protocols() const;
/**
* Set the list of RF protocols to look for during discovery.
*
* @param[in] rf_protocols the relevant bitmask
* @return NFC_OK on success, or
* NFC_ERR_UNSUPPORTED if a protocol is not supported by the controller,
* NFC_ERR_BUSY if the discovery process is already running
*/
nfc_err_t configure_rf_protocols(nfc_rf_protocols_bitmask_t rf_protocols);
/**
* Start the discovery process using the protocols configured previously.
*
* If remote endpoints are connected when this is called, they will be disconnected.
*
* @return NFC_OK on success, or
* NFC_ERR_BUSY if the discovery process is already running
*/
nfc_err_t start_discovery();
/**
* Cancel/stop a running discovery process.
*
* @return NFC_OK
*/
nfc_err_t cancel_discovery();
private:
@ -62,6 +134,10 @@ namespace nfc {
Delegate* _delegate;
};
/**
* @}
*/
} // namespace nfc
} // namespace mbed