From a6f8684a0c0b070432906613904649c6a95ec3b8 Mon Sep 17 00:00:00 2001 From: David Rebbe Date: Mon, 25 Nov 2024 20:38:49 -0500 Subject: [PATCH] updated documentation --- api/icsneo/icsneo.cpp | 6 ++--- include/icsneo/icsneo.h | 49 ++++++++++++++++++++++++++++++++---- include/icsneo/icsneotypes.h | 23 ++++++++++++++--- 3 files changed, 67 insertions(+), 11 deletions(-) diff --git a/api/icsneo/icsneo.cpp b/api/icsneo/icsneo.cpp index f4ff478..cfbf22c 100644 --- a/api/icsneo/icsneo.cpp +++ b/api/icsneo/icsneo.cpp @@ -100,17 +100,17 @@ ICSNEO_API icsneo_error_t icsneo_open(icsneo_device_t* device) { // Go online if ((device->options & icsneo_open_options_go_online) == icsneo_open_options_go_online && !dev->goOnline()) { dev->close(); - return icsneo_error_open_gonline_failed; + return icsneo_error_go_online_failed; } // Enable message polling if ((device->options & icsneo_open_options_enable_message_polling) == icsneo_open_options_enable_message_polling && !dev->enableMessagePolling()) { dev->close(); - return icsneo_error_open_message_polling_failed; + return icsneo_error_enable_message_polling_failed; } // Sync RTC if ((device->options & icsneo_open_options_sync_rtc) == icsneo_open_options_sync_rtc && !dev->setRTC(std::chrono::system_clock::now())) { dev->close(); - return icsneo_error_open_sync_rtc_failed; + return icsneo_error_sync_rtc_failed; } return icsneo_error_success; } diff --git a/include/icsneo/icsneo.h b/include/icsneo/icsneo.h index 82aa9a9..6fff629 100644 --- a/include/icsneo/icsneo.h +++ b/include/icsneo/icsneo.h @@ -37,26 +37,40 @@ extern "C" { */ typedef struct icsneo_device_t icsneo_device_t; + +/** @brief Error codes for icsneo functions. + */ typedef enum _icsneo_error_t { + // Function was successful icsneo_error_success, + // Invalid parameters, typically because of a NULL reference. icsneo_error_invalid_parameters, + // Error opening the device. icsneo_error_open_failed, - icsneo_error_open_gonline_failed, - icsneo_error_open_message_polling_failed, - icsneo_error_open_sync_rtc_failed, + // Error going online. + icsneo_error_go_online_failed, + // Error enabling message polling. + icsneo_error_enable_message_polling_failed, + // Error syncing RTC. + icsneo_error_sync_rtc_failed, } _icsneo_error_t; +/** @brief Integer representation of _icsneo_error_t enum. + * + * This is used for easier ABI compatibility, especially between other languages. + */ typedef uint32_t icsneo_error_t; /** @brief Find all hardware attached to the system. * - * @param[out] icsneo_device_t array of devices to be filled with found devices. Last element will be NULL. + * @param[out] icsneo_device_t array of devices to be filled with found devices. + * Undefined behaviour if index is out of range of devices_count. * @param[in,out] uint32_t* devices_count Size of the devices array. Modified with the number of devices found. * @param[in] void* reserved Reserved for future use. Currently unused and must be set to NULL. * - * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_failure otherwise. + * @return icsneo_error_t icsneo_error_success if successful. */ ICSNEO_API icsneo_error_t icsneo_find(icsneo_device_t** devices, uint32_t* devices_count, void* reserved); @@ -110,8 +124,33 @@ ICSNEO_API icsneo_error_t icsneo_open(icsneo_device_t* device); */ ICSNEO_API icsneo_error_t icsneo_close(icsneo_device_t* device); +/** @brief Get the description of a device + * + * @param[in] icsneo_device_t device The device to get the description of. + * @param[out] const char* value Pointer to a buffer to copy the description into. Null terminated. + * @param[in,out] uint32_t* value_length Size of the value buffer. Modified with the length of the description. + * + * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise. + */ ICSNEO_API icsneo_error_t icsneo_device_describe(icsneo_device_t* device, const char* value, uint32_t* value_length); + +/** @brief Get the description type a device + * + * @param[in] icsneo_device_t device The device to get the description of. + * @param[out] icsneo_devicetype_t* value Pointer to an icsneo_devicetype_t to copy the type into. + * + * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise. + */ ICSNEO_API icsneo_error_t icsneo_device_type(icsneo_device_t* device, icsneo_devicetype_t* value); + +/** @brief Get the description of a device + * + * @param[in] icsneo_device_t device The device to get the description of. + * @param[out] const char* value Pointer to a buffer to copy the description into. Null terminated. + * @param[in,out] uint32_t* value_length Size of the value buffer. Modified with the length of the description. + * + * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise. + */ ICSNEO_API icsneo_error_t icsneo_device_serial(icsneo_device_t* device, const char* value, uint32_t* value_length); #ifdef __cplusplus diff --git a/include/icsneo/icsneotypes.h b/include/icsneo/icsneotypes.h index b4b30f4..2a2e77d 100644 --- a/include/icsneo/icsneotypes.h +++ b/include/icsneo/icsneotypes.h @@ -11,21 +11,34 @@ extern "C" { #include +/** @brief + * Options for opening a device. See icsneo_open() for more info. + */ typedef enum _icsneo_open_options_t { + // No options icsneo_open_options_none = 0x0, + // After opening, go online icsneo_open_options_go_online = 0x1, + // After opening, enable message polling icsneo_open_options_enable_message_polling = 0x2, + // After opening, sync RTC icsneo_open_options_sync_rtc = 0x4, + // After opening, enable auto update icsneo_open_options_enable_auto_update = 0x8, + // After opening, force update icsneo_open_options_force_update = 0x10, } _icsneo_open_options_t; +/** @brief Integer representation of _icsneo_open_options_t enum. + * + * This is used for easier ABI compatibility, especially between other languages. + */ typedef uint32_t icsneo_open_options_t; - -// This enum used to be a bitfield, but has since become an enum as we have more than 32 devices -// Adding something? Make sure you update the type string and C-compatible defines below! +/** @brief + * Intrepid hardware device types, useful for filtering out or identifying devices. +*/ typedef enum _icsneo_devicetype_t { // Unknown device type icsneo_devicetype_unknown, @@ -139,6 +152,10 @@ typedef enum _icsneo_devicetype_t { icsneo_devicetype_maxsize, } _icsneo_devicetype_t; +/** @brief Integer representation of _icsneo_devicetype_t enum. + * + * This is used for easier ABI compatibility, especially between other languages. + */ typedef uint32_t icsneo_devicetype_t; // Make sure icsneo_devicetype_t is never smaller than the actual enum