add timestamp and get_messages, untested.

api/icsneo/icsneo.cpp

@@ -14,8 +14,64 @@ typedef struct icsneo_device_t {
     icsneo_open_options_t options;
 } icsneo_device_t;
 
+typedef struct icsneo_message_t {
+    std::shared_ptr<Message> message;
+} icsneo_message_t;
+
 
 static std::deque<std::shared_ptr<icsneo_device_t>> g_devices;
+static std::deque<std::shared_ptr<icsneo_message_t>> g_messages;
+
+ICSNEO_API icsneo_error_t icsneo_error_code(icsneo_error_t error_code, const char* value, uint32_t* value_length) {
+    if (!value || !value_length) {
+        return icsneo_error_invalid_parameters;
+    }
+
+    std::string error;
+    switch (error_code) {
+        case icsneo_error_success:
+            error = "success";
+            break;
+        case icsneo_error_invalid_parameters:
+            error = "invalid parameters";
+            break;
+        case icsneo_error_open_failed:
+            error = "open failed";
+            break;
+        case icsneo_error_go_online_failed:
+            error = "go online failed";
+            break;
+        case icsneo_error_enable_message_polling_failed:
+            error = "enable message polling failed";
+            break;
+        case icsneo_error_sync_rtc_failed:
+            error = "sync RTC failed";
+            break;
+        // Don't default, let the compiler warn us if we forget to handle an error code
+    }
+    // Find the minimum length of the error string and set value_length
+    auto min_length = std::minmax(static_cast<uint32_t>(error.length()), *value_length).first;
+    *value_length = min_length;
+    // Copy the string into value
+    strncpy(const_cast<char *>(value), error.c_str(), min_length);
+
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_device_type_from_type(icsneo_devicetype_t device_type, const char* value, uint32_t* value_length) {
+    if (!value || !value_length) {
+        return icsneo_error_invalid_parameters;
+    }
+
+    auto device_type_str = DeviceType::getGenericProductName(device_type);
+    // Find the minimum length of the device type string and set value_length
+    auto min_length = std::minmax(static_cast<uint32_t>(device_type_str.length()), *value_length).first;
+    *value_length = min_length;
+    // Copy the string into value
+    strncpy(const_cast<char *>(value), device_type_str.c_str(), min_length);
+
+    return icsneo_error_success;
+}
 
 ICSNEO_API icsneo_error_t icsneo_find(icsneo_device_t** devices, uint32_t* devices_count, void* reserved) {
     if (!devices || !devices_count) {
@@ -100,17 +156,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;
 }
@@ -127,7 +183,6 @@ ICSNEO_API icsneo_error_t icsneo_close(icsneo_device_t* device) {
     return icsneo_error_success;
 }
 
-
 ICSNEO_API icsneo_error_t icsneo_device_describe(icsneo_device_t* device, const char* value, uint32_t* value_length) {
     if (!device || !device->device) {
         return icsneo_error_invalid_parameters;
@@ -147,7 +202,6 @@ ICSNEO_API icsneo_error_t icsneo_device_type(icsneo_device_t* device, icsneo_dev
         return icsneo_error_invalid_parameters;
     }
     auto dev = device->device;
-    // TODO: We should expose these types
     *value = dev->getType().getDeviceType();
     
     return icsneo_error_success;
@@ -166,3 +220,136 @@ ICSNEO_API icsneo_error_t icsneo_device_serial(icsneo_device_t* device, const ch
     
     return icsneo_error_success;
 }
+
+
+ICSNEO_API icsneo_error_t icsneo_go_online(icsneo_device_t* device, bool go_online) {
+    if (!device) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    // Go online
+    if (go_online && dev->goOnline()) {
+        return icsneo_error_success;
+    }
+    // Go offline
+    if (!go_online && dev->goOffline()) {
+        return icsneo_error_success;
+    }
+
+    return icsneo_error_go_online_failed;
+}
+
+ICSNEO_API icsneo_error_t icsneo_is_online(icsneo_device_t* device, bool* is_online) {
+    if (!device || !is_online) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    *is_online = dev->isOnline();
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_set_message_polling(icsneo_device_t* device, bool enable) {
+    if (!device) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    // Enable message polling
+    if (enable && dev->enableMessagePolling()) {
+        return icsneo_error_success;
+    } 
+    // Disable message polling
+    if (!enable && dev->disableMessagePolling()) {
+        return icsneo_error_success;
+    }
+    
+    return icsneo_error_enable_message_polling_failed;
+}
+
+ICSNEO_API icsneo_error_t icsneo_get_message_polling(icsneo_device_t* device, bool* is_enabled) {
+    if (!device || !is_enabled) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    *is_enabled = dev->isMessagePollingEnabled();
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_set_message_polling_limit(icsneo_device_t* device, uint32_t limit) {
+    if (!device) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    dev->setPollingMessageLimit(static_cast<size_t>(limit));
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_get_message_polling_limit(icsneo_device_t* device, uint32_t* limit) {
+    if (!device || !limit) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    *limit = static_cast<uint32_t>(dev->getPollingMessageLimit());
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_get_message_count(icsneo_device_t* device, uint32_t* count)  {
+    if (!device || !count) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    *count = static_cast<uint32_t>(dev->getCurrentMessageCount());
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_get_timestamp_resolution(icsneo_device_t* device, uint32_t* resolution) {
+    if (!device || !resolution) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    *resolution = static_cast<uint32_t>(dev->getTimestampResolution());
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_get_messages(icsneo_device_t* device, icsneo_message_t** messages, uint32_t* messages_count) {
+    if (!device || !messages || !messages_count) {
+        return icsneo_error_invalid_parameters;
+    }
+    auto dev = device->device;
+    // Get the messages
+    auto results = dev->getMessages();
+    auto& queried_messages = results.first;
+    auto& success = results.second;
+    if (!success) {
+        return icsneo_error_get_messages_failed;
+    }
+    // Find the minimum number of messages
+    uint32_t message_size = std::minmax(static_cast<uint32_t>(queried_messages.size()), *messages_count).first;
+    *messages_count = message_size;
+
+    // Copy the messages into our global message container
+    g_messages.clear();
+    for (auto& message : queried_messages) {
+        auto message_t = std::make_shared<icsneo_message_t>();
+        message_t->message = message;
+        g_messages.push_back(message_t);
+    }
+    
+    return icsneo_error_success;
+}
+
+ICSNEO_API icsneo_error_t icsneo_is_message_valid(icsneo_message_t* message, bool* is_valid) {
+    if (!message || !is_valid) {
+        return icsneo_error_invalid_parameters;
+    }
+    *is_valid = std::find_if(g_messages.begin(), g_messages.end(), [&](const auto& msg) {
+        return msg->message == message->message;
+    }) == g_messages.end();
+    
+    return icsneo_error_success;
+}

include/icsneo/icsneo.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <stdint.h>
+#include <stdbool.h>
 
 #include <icsneo/icsneotypes.h>
 
@@ -37,26 +38,66 @@ extern "C" {
  */
 typedef struct icsneo_device_t icsneo_device_t;
 
+
+typedef struct icsneo_message_t icsneo_message_t;
+
+
+/** @brief Error codes for icsneo functions.
+ *
+ * This enum is guaranteed to be ABI stable, any new values will be appended to the end. 
+ */
 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,
+    // Error going online.
-    icsneo_error_open_message_polling_failed,
+    icsneo_error_go_online_failed,
-    icsneo_error_open_sync_rtc_failed,
+    // Error enabling message polling.
+    icsneo_error_enable_message_polling_failed,
+    // Error syncing RTC.
+    icsneo_error_sync_rtc_failed,
+    // Error getting messages.
+    icsneo_error_get_messages_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 Get the error string for an error code.
+ * 
+ * @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_error_code(icsneo_error_t error_code, const char* value, uint32_t* value_length);
+
+/** @brief Get the device type string for a icsneo_devicetype_t.
+ * 
+ * @param[in] icsneo_devicetype_t device_type The device type 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_type_from_type(icsneo_devicetype_t device_type, const char* value, uint32_t* value_length);
 
 /** @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,10 +151,135 @@ 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 serial of a device
+ * 
+ * @param[in] icsneo_device_t device The device to get the serial of.
+ * @param[out] const char* value Pointer to a buffer to copy the serial into. Null terminated.
+ * @param[in,out] uint32_t* value_length Size of the value buffer. Modified with the length of the serial.
+ * 
+ * @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);
 
+/** @brief Set the online state of a device.
+ * 
+ * @param[in] icsneo_device_t device The device to set the online state of.
+ * @param[in] bool go_online true to go online, false to go offline.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_go_online(icsneo_device_t* device, bool go_online);
+
+/** @brief Get the online state of a device.
+ * 
+ * @param[in] icsneo_device_t device The device to set the online state of.
+ * @param[out] bool true if online, false if offline.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_is_online(icsneo_device_t* device, bool* is_online);
+
+
+/** @brief Set the message polling state of a device.
+ * 
+ * @param[in] icsneo_device_t device The device to set the message polling state of.
+ * @param[in] bool enable true to enable message polling, false to disable message polling..
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_set_message_polling(icsneo_device_t* device, bool enable);
+
+/** @brief Get the message polling state of a device.
+ * 
+ * @param[in] icsneo_device_t device The device to set the message polling state of.
+ * @param[out] bool is_enabled true if message polling is enabled, false if message polling is disabled.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_get_message_polling(icsneo_device_t* device, bool* is_enabled);
+
+/** @brief Set the message polling limit of a device.
+ * 
+ * This will truncate the message queue to the specified limit.
+ * 
+ * @param[in] icsneo_device_t device The device to enforce the message polling limit.
+ * @param[in] uint32_t limit The limit to enforce.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+*/
+ICSNEO_API icsneo_error_t icsneo_set_message_polling_limit(icsneo_device_t* device, uint32_t limit);
+
+/** @brief Get the message polling limit of a device.
+ * 
+ * @see icsneo_set_message_polling_limit
+ * 
+ * @param[in] icsneo_device_t device The device to enforce the message polling limit.
+ * @param[out] uint32_t limit The limit to get.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+*/
+ICSNEO_API icsneo_error_t icsneo_get_message_polling_limit(icsneo_device_t* device, uint32_t* limit);
+
+/** @brief Get the message count of a device
+ * 
+ * @param[in] icsneo_device_t device The device to get the message count of.
+ * @param[out] uint32_t* count Pointer to a uint32_t to copy the message count into.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_get_message_count(icsneo_device_t* device, uint32_t* count);
+
+
+/** @brief Get the timestamp resolution (nanoseconds) of a device
+ * 
+ * @param[in] icsneo_device_t device The device to get the timestamp resolution of.
+ * @param[out] uint32_t* resolution Pointer to a uint32_t to copy the timestamp resolution in nanoseconds into.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_get_timestamp_resolution(icsneo_device_t* device, uint32_t* resolution);
+
+/** @brief Get the messages of a device
+ * 
+ * When calling this function, the previous messages retrieved by this function will be invalid.
+ * 
+ * @param[in] icsneo_device_t device The device to get the messages of.
+ * @param[out] icsneo_message_t** messages Pointer to an array of icsneo_message_t to copy the messages into.
+ *  Undefined behaviour if index is out of range of messages_count.
+ * @param[in,out] uint32_t* messages_count Size of the messages array. Modified with the number of messages found.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_get_messages(icsneo_device_t* device, icsneo_message_t** messages, uint32_t* messages_count);
+
+/** @brief Check if a message is valid
+ * 
+ * @param[in] icsneo_message_t* message The message to check.
+ * @param[out] bool* is_valid Pointer to a bool to copy the validity of the message into.
+ * 
+ * @return icsneo_error_t icsneo_error_success if successful, icsneo_error_invalid_parameters otherwise.
+ */
+ICSNEO_API icsneo_error_t icsneo_is_message_valid(icsneo_message_t* message, bool* is_valid);
+
 #ifdef __cplusplus
 }
 #endif

include/icsneo/icsneotypes.h

@@ -11,21 +11,34 @@ extern "C" {
 
 #include <stdint.h>
 
+/** @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;
 
 
-
+/** @brief
-// This enum used to be a bitfield, but has since become an enum as we have more than 32 devices
+ * Intrepid hardware device types, useful for filtering out or identifying devices.
-// Adding something? Make sure you update the type string and C-compatible defines below!
+*/
 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