add modules in documentation.
This commit is contained in:
Audrey Diacre
parent
0f20377541
commit
17c4a09c8f
1 changed files with 67 additions and 33 deletions
100
libnfc/nfc.c
100
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
|
||||
*
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue