sven
/
libicsneo
mirror of https://github.com/intrepidcs/libicsneo.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Added placeholder void* filter parameter to icsneo_addMessageCallback and added more documentation for message callback functions

checksum-failure-logging
EricLiu2000 2019-07-30 14:02:34 -04:00
parent 655a483aee
commit 8516a9c8bd
3 changed files with 18 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
api/icsneoc/icsneoc.cpp
View File

@ -243,7 +243,8 @@ bool icsneo_setPollingMessageLimit(const neodevice_t* device, size_t newLimit) {
return true; 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)) if(!icsneo_isValidNeoDevice(device))
return -1; return -1;

1
docs/Usage.rst
View File

@ -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. 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<Message> ) >`` and optional message filter used for matching. Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr<Message> ) >`` 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. 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. 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. Enabling message polling will register a callback that stores each received message in a buffer for later retrieval.

17
include/icsneo/icsneoc.h
View File

@ -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 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); 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); typedef bool(*fn_icsneo_setPollingMessageLimit)(const neodevice_t* device, size_t newLimit);
fn_icsneo_setPollingMessageLimit icsneo_setPollingMessageLimit; 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; fn_icsneo_addMessageCallback icsneo_addMessageCallback;
typedef bool(*fn_icsneo_removeMessageCallback)(const neodevice_t* device, int id); typedef bool(*fn_icsneo_removeMessageCallback)(const neodevice_t* device, int id);