From 3d393e58a9e6c203156816aa1a5834f628346f86 Mon Sep 17 00:00:00 2001 From: Audrey Diacre Date: Tue, 31 Jan 2012 09:49:43 +0000 Subject: [PATCH] add some Doxygen documentation. --- examples/doc/quick_start_example1.c | 5 ++ examples/nfc-poll.c | 2 +- include/nfc/nfc-emulation.h | 14 +++++- include/nfc/nfc.h | 73 +++++++++++++++++++++++----- libnfc/additional-pages.dox | 14 +++++- libnfc/chips/pn53x.c | 1 + libnfc/chips/pn53x.h | 25 +++++++++- libnfc/iso14443-subr.c | 15 +++++- libnfc/mirror-subr.c | 2 +- libnfc/mirror-subr.h | 2 +- libnfc/nfc-emulation.c | 2 +- libnfc/nfc.c | 75 +++++++++++++++-------------- 12 files changed, 174 insertions(+), 56 deletions(-) diff --git a/examples/doc/quick_start_example1.c b/examples/doc/quick_start_example1.c index 9c405aa..bc5663f 100644 --- a/examples/doc/quick_start_example1.c +++ b/examples/doc/quick_start_example1.c @@ -1,3 +1,8 @@ +/** + * @file quick_start_example1.c + * @brief Quick start example that presents how to use libnfc + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif // HAVE_CONFIG_H diff --git a/examples/nfc-poll.c b/examples/nfc-poll.c index e1873a4..aa64ec1 100644 --- a/examples/nfc-poll.c +++ b/examples/nfc-poll.c @@ -29,7 +29,7 @@ */ /** - * @file nfc-poll + * @file nfc-poll.c * @brief Polling example */ diff --git a/include/nfc/nfc-emulation.h b/include/nfc/nfc-emulation.h index 46dd604..da4f565 100644 --- a/include/nfc/nfc-emulation.h +++ b/include/nfc/nfc-emulation.h @@ -17,6 +17,11 @@ * along with this program. If not, see */ +/** + * @file nfc-emulation.h + * @brief Provide a small API to ease emulation in libnfc + */ + #ifndef __NFC_EMULATION_H__ #define __NFC_EMULATION_H__ @@ -30,13 +35,20 @@ extern "C" { struct nfc_emulator; struct nfc_emulation_state_machine; - +/** + * @struct nfc_emulator + * @brief NFC emulator structure + */ struct nfc_emulator { nfc_target *target; struct nfc_emulation_state_machine *state_machine; void *user_data; }; +/** + * @struct nfc_emulation_state_machine + * @brief NFC emulation state machine structure + */ struct nfc_emulation_state_machine { int (*io)(struct nfc_emulator *emulator, const uint8_t *data_in, const size_t data_in_len, uint8_t *data_out, const size_t data_out_len); void *data; diff --git a/include/nfc/nfc.h b/include/nfc/nfc.h index 8c2b1b7..5ca6639 100644 --- a/include/nfc/nfc.h +++ b/include/nfc/nfc.h @@ -115,18 +115,67 @@ extern "C" { NFC_EXPORT const char *nfc_version (void); /* Error codes */ -#define NFC_SUCCESS 0 // No error -#define NFC_EIO -1 // Input / output error, device will not be usable anymore -#define NFC_EINVARG -2 // Invalid argument(s) -#define NFC_EDEVNOTSUPP -3 // Operation not supported by device -#define NFC_ENOTSUCHDEV -4 // No such device -#define NFC_EOVFLOW -5 // Buffer overflow -#define NFC_ETIMEOUT -6 // Operation timed out -#define NFC_EOPABORTED -7 // Operation aborted (by user) -#define NFC_ENOTIMPL -8 // Not (yet) implemented -#define NFC_ETGRELEASED -10 // Target released -#define NFC_ERFTRANS -20 // Error while RF transmission -#define NFC_ECHIP -90 // Device's internal chip error +/** @ingroup error + * @hideinitializer + * Success (no error) + */ +#define NFC_SUCCESS 0 +/** @ingroup error + * @hideinitializer + * Input / output error, device will not be usable anymore + */ +#define NFC_EIO -1 +/** @ingroup error + * @hideinitializer + * Invalid argument(s) + */ +#define NFC_EINVARG -2 +/** @ingroup error + * @hideinitializer + * Operation not supported by device + */ +#define NFC_EDEVNOTSUPP -3 +/** @ingroup error + * @hideinitializer + * No such device + */ +#define NFC_ENOTSUCHDEV -4 +/** @ingroup error + * @hideinitializer + * Buffer overflow + */ +#define NFC_EOVFLOW -5 +/** @ingroup error + * @hideinitializer + * Operation timed out + */ +#define NFC_ETIMEOUT -6 +/** @ingroup error + * @hideinitializer + * Operation aborted (by user) + */ +#define NFC_EOPABORTED -7 +/** @ingroup error + * @hideinitializer + * Not (yet) implemented + */ +#define NFC_ENOTIMPL -8 +/** @ingroup error + * @hideinitializer + * Target released + */ +#define NFC_ETGRELEASED -10 +/** @ingroup error + * @hideinitializer + * Error while RF transmission + */ +#define NFC_ERFTRANS -20 +/** @ingroup error + * @hideinitializer + * Device's internal chip error + */ +#define NFC_ECHIP -90 + # ifdef __cplusplus } diff --git a/libnfc/additional-pages.dox b/libnfc/additional-pages.dox index 7cad79e..658f352 100644 --- a/libnfc/additional-pages.dox +++ b/libnfc/additional-pages.dox @@ -3,12 +3,24 @@ * * @section intro_sec Introduction * This is the developer manual for \b libnfc. + * libnfc is an open source library that allows you to communicate with NFC devices. For more info, see the + * libusb homepage. * * @section quick_start_sec Quick start - * If you are looking for libnfc's public API, you should start with nfc.h + * If you are looking for libnfc's public API, you should start with the Modules page which links to the different categories of libnfc's functionality. * Some commented examples that present how to use \b libnfc can be found here: * @subpage examples_page * + * Others example programs can be found in the libnfc source distribution under the "examples" subdirectory. + * + * You can also find utils in the libnfc source distribution under the "utils" subdirectory. + * + * \section errorhandling Error handling + * + * libusb functions typically return 0 or more on success or a negative error code + * on failure. These negative error codes relate to LIBNFC_ERROR constants + * which are listed on the \ref error "Error reporting" documentation page. + * * @section upgrading_sec Upgrading from previous version * If you are upgrading from a previous \b libnfc version, please take care about changes, specially API changes. * All important changes should be listed in @subpage changelog_page. diff --git a/libnfc/chips/pn53x.c b/libnfc/chips/pn53x.c index bdd774f..39fb96e 100644 --- a/libnfc/chips/pn53x.c +++ b/libnfc/chips/pn53x.c @@ -20,6 +20,7 @@ */ /** + * @internal * @file pn53x.c * @brief PN531, PN532 and PN533 common functions */ diff --git a/libnfc/chips/pn53x.h b/libnfc/chips/pn53x.h index 998506a..c88e931 100644 --- a/libnfc/chips/pn53x.h +++ b/libnfc/chips/pn53x.h @@ -114,18 +114,31 @@ # define RFCI_ANALOG_TYPE_B 0x0C // 3 # define RFCI_ANALOG_TYPE_14443_4 0x0D // 9 +/** + * @enum pn53x_power_mode + * @brief PN53x power mode enumeration + */ typedef enum { NORMAL, // In that case, there is no power saved but the PN53x reacts as fast as possible on the host controller interface. POWERDOWN, // Only on PN532, need to be wake up to process commands with a long preamble LOWVBAT // Only on PN532, need to be wake up to process commands with a long preamble and SAMConfiguration command } pn53x_power_mode; +/** + * @enum pn53x_operating_mode + * @brief PN53x operatin mode enumeration + */ typedef enum { IDLE, INITIATOR, TARGET, } pn53x_operating_mode; +/** + * @internal + * @struct pn53x_io + * @brief PN53x I/O structure + */ struct pn53x_io { int (*send)(struct nfc_device *pnd, const uint8_t *pbtData, const size_t szData, int timeout); int (*receive)(struct nfc_device *pnd, uint8_t *pbtData, const size_t szDataLen, int timeout); @@ -135,6 +148,12 @@ struct pn53x_io { #define PN53X_CACHE_REGISTER_MIN_ADDRESS PN53X_REG_CIU_Mode #define PN53X_CACHE_REGISTER_MAX_ADDRESS PN53X_REG_CIU_Coll #define PN53X_CACHE_REGISTER_SIZE ((PN53X_CACHE_REGISTER_MAX_ADDRESS - PN53X_CACHE_REGISTER_MIN_ADDRESS) + 1) + +/** + * @internal + * @struct pn53x_data + * @brief PN53x data structure + */ struct pn53x_data { /** Chip type (PN531, PN532 or PN533)*/ pn53x_type type; @@ -174,7 +193,7 @@ struct pn53x_data { /** * @enum pn53x_modulation - * @brief NFC modulation + * @brief NFC modulation enumeration */ typedef enum { /** Undefined modulation */ @@ -238,6 +257,10 @@ typedef enum { PTT_DEP_ACTIVE_424 = 0x82, } pn53x_target_type; +/** + * @enum pn532_sam_mode + * @brief PN53x SAM mode enumeration + */ typedef enum { PSM_NORMAL = 0x01, PSM_VIRTUAL_CARD = 0x02, diff --git a/libnfc/iso14443-subr.c b/libnfc/iso14443-subr.c index ec0e002..4d0a0a9 100644 --- a/libnfc/iso14443-subr.c +++ b/libnfc/iso14443-subr.c @@ -19,7 +19,7 @@ /** * @file iso14443-subr.c - * @brief + * @brief Defines some function extracted for ISO/IEC 14443 */ #ifdef HAVE_CONFIG_H @@ -31,6 +31,11 @@ #include + +/** + * @brief CRC + * + */ void iso14443a_crc (uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc) { @@ -48,12 +53,20 @@ iso14443a_crc (uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc) *pbtCrc = (uint8_t) ((wCrc >> 8) & 0xFF); } +/** + * @brief Append CRC + * + */ void iso14443a_crc_append (uint8_t *pbtData, size_t szLen) { iso14443a_crc (pbtData, szLen, pbtData + szLen); } +/** + * @brief Locate historical bytes + * @see ISO/IEC 14443-4 (5.2.7 Historical bytes) + */ uint8_t * iso14443a_locate_historical_bytes (uint8_t *pbtAts, size_t szAts, size_t *pszTk) { diff --git a/libnfc/mirror-subr.c b/libnfc/mirror-subr.c index 361038f..c457af5 100644 --- a/libnfc/mirror-subr.c +++ b/libnfc/mirror-subr.c @@ -19,7 +19,7 @@ /** * @file mirror-subr.c - * @brief + * @brief Mirror bytes */ #ifdef HAVE_CONFIG_H diff --git a/libnfc/mirror-subr.h b/libnfc/mirror-subr.h index 081bc88..e0ee172 100644 --- a/libnfc/mirror-subr.h +++ b/libnfc/mirror-subr.h @@ -18,7 +18,7 @@ * * * @file mirror-subr.h - * @brief + * @brief Mirror bytes */ #ifndef _LIBNFC_MIRROR_SUBR_H_ diff --git a/libnfc/nfc-emulation.c b/libnfc/nfc-emulation.c index d952fc5..662e71c 100644 --- a/libnfc/nfc-emulation.c +++ b/libnfc/nfc-emulation.c @@ -18,7 +18,7 @@ */ /** - * @file nfc-emulate.c + * @file nfc-emulation.c * @brief Provide a small API to ease emulation in libnfc */ diff --git a/libnfc/nfc.c b/libnfc/nfc.c index 5029365..363b043 100644 --- a/libnfc/nfc.c +++ b/libnfc/nfc.c @@ -31,7 +31,10 @@ */ /** * @defgroup dev NFC Device/Hardware manipulation - * + * The functionality documented below is designed to help with the following + * operations: + * - Enumerating the NFC devices currently attached to the system + * - Opening and closing the chosen device */ /** * @defgroup initiator NFC initiator @@ -98,7 +101,7 @@ const struct nfc_driver *nfc_drivers[] = { NULL }; -/** \ingroup lib +/** @ingroup lib * @brief Initialize libnfc. * This function must be called before calling any other libnfc function * @param context Optional output location for context pointer @@ -109,7 +112,7 @@ nfc_init(nfc_context *context) log_init (); } -/** \ingroup lib +/** @ingroup lib * @brief Deinitialize libnfc. * Should be called after closing all open devices and before your application terminates. *@param context The context to deinitialize @@ -120,7 +123,7 @@ nfc_exit(nfc_context *context) log_fini (); } -/** \ingroup dev +/** @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 @@ -153,7 +156,7 @@ nfc_get_default_device (nfc_connstring *connstring) return true; } -/** \ingroup dev +/** @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 @@ -214,7 +217,7 @@ nfc_open (nfc_context *context, const nfc_connstring connstring) return NULL; } -/** \ingroup dev +/** @ingroup dev * @brief Close from a NFC device * @param pnd \a nfc_device struct pointer that represent currently used device * @@ -232,11 +235,11 @@ nfc_close (nfc_device *pnd) } } -/** \ingroup dev +/** @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. - * @param connstrings The device connection string if specific device is wanted, \c NULL otherwise + * @param connstrings array of \a nfc_connstring. * @param szDevices size of the \a connstrings array. * */ @@ -262,7 +265,7 @@ nfc_list_devices (nfc_context *context, nfc_connstring connstrings[] , size_t sz return szDeviceFound; } -/** \ingroup properties +/** @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 @@ -280,7 +283,7 @@ nfc_device_set_property_int (nfc_device *pnd, const nfc_property property, const } -/** \ingroup properties +/** @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 @@ -298,7 +301,7 @@ nfc_device_set_property_bool (nfc_device *pnd, const nfc_property property, cons HAL (device_set_property_bool, pnd, property, bEnable); } -/** \ingroup initiator +/** @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 @@ -361,7 +364,7 @@ nfc_initiator_init (nfc_device *pnd) HAL (initiator_init, pnd); } -/** \ingroup initiator +/** @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) * @@ -404,7 +407,7 @@ nfc_initiator_select_passive_target (nfc_device *pnd, HAL (initiator_select_passive_target, pnd, nm, abtInit, szInit, pnt); } -/** \ingroup initiator +/** @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) * @@ -467,12 +470,12 @@ nfc_initiator_list_passive_targets (nfc_device *pnd, return szTargetFound; } -/** \ingroup initiator +/** @ingroup initiator * @brief Polling for NFC targets * @return Returns polled targets count, otherwise returns libnfc's error code (negative value). * * @param pnd \a nfc_device struct pointer that represent currently used device - * @param pnmModulations desired modulation + * @param pnmModulations desired modulations * @param szModulations size of \a pnmModulations * @param uiPollNr specifies the number of polling (0x01 – 0xFE: 1 up to 254 polling, 0xFF: Endless polling) * @note one polling is a polling for each desired target type @@ -490,7 +493,7 @@ nfc_initiator_poll_target (nfc_device *pnd, } -/** \ingroup initiator +/** @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). * @@ -514,7 +517,7 @@ nfc_initiator_select_dep_target (nfc_device *pnd, HAL (initiator_select_dep_target, pnd, ndm, nbr, pndiInitiator, pnt, timeout); } -/** \ingroup initiator +/** @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). * @@ -555,7 +558,7 @@ nfc_initiator_poll_dep_target (struct nfc_device *pnd, return 0; } -/** \ingroup initiator +/** @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 @@ -573,7 +576,7 @@ nfc_initiator_deselect_target (nfc_device *pnd) HAL (initiator_deselect_target, pnd); } -/** \ingroup initiator +/** @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 * @@ -606,7 +609,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 +/** @ingroup initiator * @brief Transceive raw bit-frames to a target * @return Returns received bits count on success, otherwise returns libnfc's error code * @@ -648,7 +651,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 +/** @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. * @@ -674,7 +677,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 +/** @ingroup initiator * @brief Transceive raw bit-frames to a target * @return Returns received bits count on success, otherwise returns libnfc's error code * @@ -702,7 +705,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 +/** @ingroup target * @brief Initialize NFC device as an emulated tag * @return Returns received bytes count on success, otherwise returns libnfc's error code * @@ -763,7 +766,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 +/** @ingroup dev * @brief Turn NFC device in idle mode * @return Returns 0 on success, otherwise returns libnfc's error code. * @@ -779,7 +782,7 @@ nfc_idle (nfc_device *pnd) HAL (idle, pnd); } -/** \ingroup dev +/** @ingroup dev * @brief Abort current running command * @return Returns 0 on success, otherwise returns libnfc's error code. * @@ -796,7 +799,7 @@ nfc_abort_command (nfc_device *pnd) HAL (abort_command, pnd); } -/** \ingroup target +/** @ingroup target * @brief Send bytes and APDU frames * @return Returns sent bytes count on success, otherwise returns libnfc's error code * @@ -817,7 +820,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 +/** @ingroup target * @brief Receive bytes and APDU frames * @return Returns received bytes count on success, otherwise returns libnfc's error code * @@ -837,7 +840,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 +/** @ingroup target * @brief Send raw bit-frames * @return Returns sent bits count on success, otherwise returns libnfc's error code. * @@ -854,7 +857,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 +/** @ingroup target * @brief Receive bit-frames * @return Returns received bits count on success, otherwise returns libnfc's error code * @@ -895,7 +898,7 @@ static struct sErrorMessage { { NFC_ECHIP, "Device's Internal Chip Error" }, }; -/** \ingroup error +/** @ingroup error * @brief Return the last error string * @return Returns a string * @@ -916,7 +919,7 @@ nfc_strerror (const nfc_device *pnd) return pcRes; } -/** \ingroup error +/** @ingroup error * @brief Renders the last error in pcStrErrBuf for a maximum size of szBufLen chars * @return Returns 0 upon success * @@ -928,7 +931,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 +/** @ingroup error * @brief Display the last error occured on a nfc_device * * @param pnd \a nfc_device struct pointer that represent currently used device @@ -940,7 +943,7 @@ nfc_perror (const nfc_device *pnd, const char *pcString) fprintf (stderr, "%s: %s\n", pcString, nfc_strerror (pnd)); } -/** \ingroup error +/** @ingroup error * @brief Returns last error occured on a nfc_device * @return Returns an integer that represents to libnfc's error code. * @@ -954,7 +957,7 @@ nfc_device_get_last_error (const nfc_device *pnd) /* Special data accessors */ -/** \ingroup data +/** @ingroup data * @brief Returns the device name * @return Returns a string with the device name * @@ -966,7 +969,7 @@ nfc_device_get_name (nfc_device *pnd) return pnd->name; } -/** \ingroup data +/** @ingroup data * @brief Returns the device connection string * @return Returns a string with the device connstring * @@ -980,7 +983,7 @@ nfc_device_get_connstring (nfc_device *pnd) /* Misc. functions */ -/** \ingroup misc +/** @ingroup misc * @brief Returns the library version * @return Returns a string with the library version *