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
*