[FL-3666] NFC API improvements (#3214)

* drivers: expose st25r3916 driver API * nfc poller: add start with custom callback * mf classic: rework sync API with poller custom start * mf ultralight: rework sync API with poller custom start * iso14443_3a poller: remove unused col res state * nfc: rework nfc poller custom start * mf ultralight: rename sync API * mf classic: rename sync API * iso14443-3a: rename sync API * nfc: remove async prefix in internal functions * nfc: expose internal API * nfc: fix sync api include and docs * targets: fix f18 build * nfc: rework NfcGenericEventEx type * nfc poller: add documentation * iso14443-3a poller: add documentation * felica poller: add documentation * iso14443_3b poller: add documentation * so14443_4a poller: add documentation * iso14443_4b poller: add documentation * iso15693 poller: add documentation * slix poller: add documentation * mf desfire poller: add documentation * mf ultralight poller: fix API and add documentation * mf classic poller: add documentation Co-authored-by: あく <alleteam@gmail.com>
2023-11-15 17:32:45 +09:00
parent d0b9a3a4ae
commit c00776ca22
62 changed files with 1708 additions and 719 deletions
@@ -8,22 +8,66 @@
 extern "C" {
 #endif

+/**
+ * @brief Iso14443_4bPoller opaque type definition.
+ */
 typedef struct Iso14443_4bPoller Iso14443_4bPoller;

+/**
+ * @brief Enumeration of possible Iso14443_4b poller event types.
+ */
 typedef enum {
-    Iso14443_4bPollerEventTypeError,
-    Iso14443_4bPollerEventTypeReady,
+    Iso14443_4bPollerEventTypeError, /**< The card was activated by the poller. */
+    Iso14443_4bPollerEventTypeReady, /**< An error occured during activation procedure. */
 } Iso14443_4bPollerEventType;

-typedef struct {
-    Iso14443_4bError error;
+/**
+ * @brief Iso14443_4b poller event data.
+ */
+typedef union {
+    Iso14443_4bError error; /**< Error code indicating card activation fail reason. */
 } Iso14443_4bPollerEventData;

+/**
+ * @brief Iso14443_4b poller event structure.
+ *
+ * Upon emission of an event, an instance of this struct will be passed to the callback.
+ */
 typedef struct {
-    Iso14443_4bPollerEventType type;
-    Iso14443_4bPollerEventData* data;
+    Iso14443_4bPollerEventType type; /**< Type of emmitted event. */
+    Iso14443_4bPollerEventData* data; /**< Pointer to event specific data. */
 } Iso14443_4bPollerEvent;

+/**
+ * @brief Transmit and receive Iso14443_4b blocks in poller mode.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * The rx_buffer will be filled with any data received as a response to data
+ * sent from tx_buffer. The fwt parameter is calculated during activation procedure.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[in] tx_buffer pointer to the buffer containing the data to be transmitted.
+ * @param[out] rx_buffer pointer to the buffer to be filled with received data.
+ * @return Iso14443_4bErrorNone on success, an error code on failure.
+ */
+Iso14443_4bError iso14443_4b_poller_send_block(
+    Iso14443_4bPoller* instance,
+    const BitBuffer* tx_buffer,
+    BitBuffer* rx_buffer);
+
+/**
+ * @brief Send HALT command to the card.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * Halts card and changes internal Iso14443_4aPoller state to Idle.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @return Iso14443_4bErrorNone on success, an error code on failure.
+ */
+Iso14443_4bError iso14443_4b_poller_halt(Iso14443_4bPoller* instance);
+
 #ifdef __cplusplus
 }
 #endif
@@ -42,13 +42,6 @@ struct Iso14443_4bPoller {

 const Iso14443_4bData* iso14443_4b_poller_get_data(Iso14443_4bPoller* instance);

-Iso14443_4bError iso14443_4b_poller_halt(Iso14443_4bPoller* instance);
-
-Iso14443_4bError iso14443_4b_poller_send_block(
-    Iso14443_4bPoller* instance,
-    const BitBuffer* tx_buffer,
-    BitBuffer* rx_buffer);
-
 #ifdef __cplusplus
 }
 #endif