diff --git a/api/icsneoc/icsneoc.cpp b/api/icsneoc/icsneoc.cpp index 0633005..63cdd0f 100644 --- a/api/icsneoc/icsneoc.cpp +++ b/api/icsneoc/icsneoc.cpp @@ -243,7 +243,8 @@ bool icsneo_setPollingMessageLimit(const neodevice_t* device, size_t newLimit) { return true; } -int icsneo_addMessageCallback(const neodevice_t* device, void (*callback)(neomessage_t)) { +int icsneo_addMessageCallback(const neodevice_t* device, void (*callback)(neomessage_t), void* filter) { + (void)filter; // unused for now if(!icsneo_isValidNeoDevice(device)) return -1; diff --git a/docs/Usage.rst b/docs/Usage.rst index 9a7dd00..e2df898 100644 --- a/docs/Usage.rst +++ b/docs/Usage.rst @@ -66,6 +66,7 @@ Message Callbacks and Polling In order to handle messages, users may register message callbacks, which are automatically called whenever a matching message is received. Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr ) >`` and optional message filter used for matching. Registering a callback returns an ``int`` representing the id of the callback, which should be stored by the user and later used to remove the callback when desired. +Note that this functionality is only available in C and C++. The default method of handling messages is to enable message polling, which is built upon message callbacks. Enabling message polling will register a callback that stores each received message in a buffer for later retrieval. diff --git a/include/icsneo/icsneoc.h b/include/icsneo/icsneoc.h index 946a6a9..82419a6 100644 --- a/include/icsneo/icsneoc.h +++ b/include/icsneo/icsneoc.h @@ -284,8 +284,21 @@ extern size_t DLLExport icsneo_getPollingMessageLimit(const neodevice_t* device) */ extern bool DLLExport icsneo_setPollingMessageLimit(const neodevice_t* device, size_t newLimit); -extern int DLLExport icsneo_addMessageCallback(const neodevice_t* device, void (*callback)(neomessage_t)); +/** + * \brief Adds a message callback to the specified device. + * \param[in] device A pointer to the neodevice_t structure specifying the device to operate on. + * \param[in] callback A function pointer with void return type and a single neomessage_t parameter + * \param[in] filter Unused for now. Exists as a placeholder here for future backwards-compatibility. + * \returns the id of the callback added, or -1 if the operation failed. + */ +extern int DLLExport icsneo_addMessageCallback(const neodevice_t* device, void (*callback)(neomessage_t), void* filter); +/** + * \brief Removes a message callback from the specified device. + * \param[in] device A pointer to the neodevice_t structure specifying the device to operate on. + * \param[in] id The id of the callback to remove + * \returns True if the callback was successfully removed. + */ extern bool DLLExport icsneo_removeMessageCallback(const neodevice_t* device, int id); /** @@ -743,7 +756,7 @@ fn_icsneo_getPollingMessageLimit icsneo_getPollingMessageLimit; typedef bool(*fn_icsneo_setPollingMessageLimit)(const neodevice_t* device, size_t newLimit); fn_icsneo_setPollingMessageLimit icsneo_setPollingMessageLimit; -typedef int(*fn_icsneo_addMessageCallback)(const neodevice_t* device, void (*callback)(neomessage_t)); +typedef int(*fn_icsneo_addMessageCallback)(const neodevice_t* device, void (*callback)(neomessage_t), void* filter); fn_icsneo_addMessageCallback icsneo_addMessageCallback; typedef bool(*fn_icsneo_removeMessageCallback)(const neodevice_t* device, int id);