diff --git a/libnfc/nfc.c b/libnfc/nfc.c index 0eeb325..5029365 100644 --- a/libnfc/nfc.c +++ b/libnfc/nfc.c @@ -23,6 +23,40 @@ * @file nfc.c * @brief NFC library implementation */ +/** + * @defgroup lib Library initialization/deinitialization + * This page details how to initialize and deinitialize libnfc. Initialization + * must be performed before using any libnfc functionality, and similarly you + * must not call any libnfc functions after deinitialization. + */ +/** + * @defgroup dev NFC Device/Hardware manipulation + * + */ +/** + * @defgroup initiator NFC initiator + * act as "reader" + */ +/** + * @defgroup target NFC target + * act as tag (i.e. MIFARE Classic) or NFC target device. + */ +/** + * @defgroup error Error reporting + * + */ +/** + * @defgroup data Special data accessors + * + */ +/** + * @defgroup properties Properties accessors + * + */ +/** + * @defgroup misc Miscellaneous + * + */ /* vim:set ts=2 sw=2 et: */ @@ -64,7 +98,7 @@ const struct nfc_driver *nfc_drivers[] = { NULL }; -/** +/** \ingroup lib * @brief Initialize libnfc. * This function must be called before calling any other libnfc function * @param context Optional output location for context pointer @@ -75,7 +109,7 @@ nfc_init(nfc_context *context) log_init (); } -/** +/** \ingroup lib * @brief Deinitialize libnfc. * Should be called after closing all open devices and before your application terminates. *@param context The context to deinitialize @@ -86,7 +120,7 @@ nfc_exit(nfc_context *context) log_fini (); } -/** +/** \ingroup dev * @brief Get the defaut NFC device * @param connstring \a nfc_connstring pointer where the default connection string will be stored * @return \e true on success @@ -119,7 +153,7 @@ nfc_get_default_device (nfc_connstring *connstring) return true; } -/** +/** \ingroup dev * @brief Open a NFC device * @param context The context to operate on, or NULL for the default context. * @param connstring The device connection string if specific device is wanted, \c NULL otherwise @@ -180,7 +214,7 @@ nfc_open (nfc_context *context, const nfc_connstring connstring) return NULL; } -/** +/** \ingroup dev * @brief Close from a NFC device * @param pnd \a nfc_device struct pointer that represent currently used device * @@ -198,7 +232,7 @@ nfc_close (nfc_device *pnd) } } -/** +/** \ingroup dev * @brief Probe for discoverable supported devices (ie. only available for some drivers) * @return Returns the number of devices found. * @param context The context to operate on, or NULL for the default context. @@ -228,7 +262,7 @@ nfc_list_devices (nfc_context *context, nfc_connstring connstrings[] , size_t sz return szDeviceFound; } -/** +/** \ingroup properties * @brief Set a device's integer-property value * @return Returns 0 on success, otherwise returns libnfc's error code (negative value) * @param pnd \a nfc_device struct pointer that represent currently used device @@ -246,7 +280,7 @@ nfc_device_set_property_int (nfc_device *pnd, const nfc_property property, const } -/** +/** \ingroup properties * @brief Set a device's boolean-property value * @return Returns 0 on success, otherwise returns libnfc's error code (negative value) * @param pnd \a nfc_device struct pointer that represent currently used device @@ -264,7 +298,7 @@ nfc_device_set_property_bool (nfc_device *pnd, const nfc_property property, cons HAL (device_set_property_bool, pnd, property, bEnable); } -/** +/** \ingroup initiator * @brief Initialize NFC device as initiator (reader) * @return Returns 0 on success, otherwise returns libnfc's error code (negative value) * @param pnd \a nfc_device struct pointer that represent currently used device @@ -327,7 +361,7 @@ nfc_initiator_init (nfc_device *pnd) HAL (initiator_init, pnd); } -/** +/** \ingroup initiator * @brief Select a passive or emulated tag * @return Returns selected passive target count on success, otherwise returns libnfc's error code (negative value) * @@ -370,7 +404,7 @@ nfc_initiator_select_passive_target (nfc_device *pnd, HAL (initiator_select_passive_target, pnd, nm, abtInit, szInit, pnt); } -/** +/** \ingroup initiator * @brief List passive or emulated tags * @return Returns the number of targets found on success, otherwise returns libnfc's error code (negative value) * @@ -433,7 +467,7 @@ nfc_initiator_list_passive_targets (nfc_device *pnd, return szTargetFound; } -/** +/** \ingroup initiator * @brief Polling for NFC targets * @return Returns polled targets count, otherwise returns libnfc's error code (negative value). * @@ -456,7 +490,7 @@ nfc_initiator_poll_target (nfc_device *pnd, } -/** +/** \ingroup initiator * @brief Select a target and request active or passive mode for D.E.P. (Data Exchange Protocol) * @return Returns selected D.E.P targets count on success, otherwise returns libnfc's error code (negative value). * @@ -480,7 +514,7 @@ nfc_initiator_select_dep_target (nfc_device *pnd, HAL (initiator_select_dep_target, pnd, ndm, nbr, pndiInitiator, pnt, timeout); } -/** +/** \ingroup initiator * @brief Poll a target and request active or passive mode for D.E.P. (Data Exchange Protocol) * @return Returns selected D.E.P targets count on success, otherwise returns libnfc's error code (negative value). * @@ -521,7 +555,7 @@ nfc_initiator_poll_dep_target (struct nfc_device *pnd, return 0; } -/** +/** \ingroup initiator * @brief Deselect a selected passive or emulated tag * @return Returns 0 on success, otherwise returns libnfc's error code (negative value). * @param pnd \a nfc_device struct pointer that represents currently used device @@ -539,7 +573,7 @@ nfc_initiator_deselect_target (nfc_device *pnd) HAL (initiator_deselect_target, pnd); } -/** +/** \ingroup initiator * @brief Send data to target then retrieve data from target * @return Returns received bytes count on success, otherwise returns libnfc's error code * @@ -572,7 +606,7 @@ nfc_initiator_transceive_bytes (nfc_device *pnd, const uint8_t *pbtTx, const siz HAL (initiator_transceive_bytes, pnd, pbtTx, szTx, pbtRx, pszRx, timeout) } -/** +/** \ingroup initiator * @brief Transceive raw bit-frames to a target * @return Returns received bits count on success, otherwise returns libnfc's error code * @@ -614,7 +648,7 @@ nfc_initiator_transceive_bits (nfc_device *pnd, const uint8_t *pbtTx, const size HAL (initiator_transceive_bits, pnd, pbtTx, szTxBits, pbtTxPar, pbtRx, pbtRxPar); } -/** +/** \ingroup initiator * @brief Send data to target then retrieve data from target * @return Returns received bytes count on success, otherwise returns libnfc's error code. * @@ -640,7 +674,7 @@ nfc_initiator_transceive_bytes_timed (nfc_device *pnd, const uint8_t *pbtTx, con HAL (initiator_transceive_bytes_timed, pnd, pbtTx, szTx, pbtRx, cycles) } -/** +/** \ingroup initiator * @brief Transceive raw bit-frames to a target * @return Returns received bits count on success, otherwise returns libnfc's error code * @@ -668,7 +702,7 @@ nfc_initiator_transceive_bits_timed (nfc_device *pnd, const uint8_t *pbtTx, cons HAL (initiator_transceive_bits_timed, pnd, pbtTx, szTxBits, pbtTxPar, pbtRx, pbtRxPar, cycles); } -/** +/** \ingroup target * @brief Initialize NFC device as an emulated tag * @return Returns received bytes count on success, otherwise returns libnfc's error code * @@ -729,7 +763,7 @@ nfc_target_init (nfc_device *pnd, nfc_target *pnt, uint8_t *pbtRx, const size_t HAL (target_init, pnd, pnt, pbtRx, szRx, timeout); } -/** +/** \ingroup dev * @brief Turn NFC device in idle mode * @return Returns 0 on success, otherwise returns libnfc's error code. * @@ -745,7 +779,7 @@ nfc_idle (nfc_device *pnd) HAL (idle, pnd); } -/** +/** \ingroup dev * @brief Abort current running command * @return Returns 0 on success, otherwise returns libnfc's error code. * @@ -762,7 +796,7 @@ nfc_abort_command (nfc_device *pnd) HAL (abort_command, pnd); } -/** +/** \ingroup target * @brief Send bytes and APDU frames * @return Returns sent bytes count on success, otherwise returns libnfc's error code * @@ -783,7 +817,7 @@ nfc_target_send_bytes (nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, HAL (target_send_bytes, pnd, pbtTx, szTx, timeout); } -/** +/** \ingroup target * @brief Receive bytes and APDU frames * @return Returns received bytes count on success, otherwise returns libnfc's error code * @@ -803,7 +837,7 @@ nfc_target_receive_bytes (nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, in HAL (target_receive_bytes, pnd, pbtRx, szRx, timeout); } -/** +/** \ingroup target * @brief Send raw bit-frames * @return Returns sent bits count on success, otherwise returns libnfc's error code. * @@ -820,7 +854,7 @@ nfc_target_send_bits (nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBi HAL (target_send_bits, pnd, pbtTx, szTxBits, pbtTxPar); } -/** +/** \ingroup target * @brief Receive bit-frames * @return Returns received bits count on success, otherwise returns libnfc's error code * @@ -861,7 +895,7 @@ static struct sErrorMessage { { NFC_ECHIP, "Device's Internal Chip Error" }, }; -/** +/** \ingroup error * @brief Return the last error string * @return Returns a string * @@ -882,7 +916,7 @@ nfc_strerror (const nfc_device *pnd) return pcRes; } -/** +/** \ingroup error * @brief Renders the last error in pcStrErrBuf for a maximum size of szBufLen chars * @return Returns 0 upon success * @@ -894,7 +928,7 @@ nfc_strerror_r (const nfc_device *pnd, char *pcStrErrBuf, size_t szBufLen) return (snprintf (pcStrErrBuf, szBufLen, "%s", nfc_strerror (pnd)) < 0) ? -1 : 0; } -/** +/** \ingroup error * @brief Display the last error occured on a nfc_device * * @param pnd \a nfc_device struct pointer that represent currently used device @@ -906,7 +940,7 @@ nfc_perror (const nfc_device *pnd, const char *pcString) fprintf (stderr, "%s: %s\n", pcString, nfc_strerror (pnd)); } -/** +/** \ingroup error * @brief Returns last error occured on a nfc_device * @return Returns an integer that represents to libnfc's error code. * @@ -920,7 +954,7 @@ nfc_device_get_last_error (const nfc_device *pnd) /* Special data accessors */ -/** +/** \ingroup data * @brief Returns the device name * @return Returns a string with the device name * @@ -932,7 +966,7 @@ nfc_device_get_name (nfc_device *pnd) return pnd->name; } -/** +/** \ingroup data * @brief Returns the device connection string * @return Returns a string with the device connstring * @@ -946,7 +980,7 @@ nfc_device_get_connstring (nfc_device *pnd) /* Misc. functions */ -/** +/** \ingroup misc * @brief Returns the library version * @return Returns a string with the library version *