C API (icsneoc)¶
Reference¶
Typedefs¶
-
typedef void *
devicehandle_t
¶
-
typedef int32_t
neodevice_handle_t
¶
-
typedef uint32_t
devicetype_t
¶
Functions¶
Functions
-
void
icsneo_findAllDevices
(neodevice_t *devices, size_t *count)¶ Find Intrepid hardware connected via USB and Ethernet.
For each found device, a
neodevice_t structure will be written into the memory you provide.- Parameters
devices
: Pointer to memory where devices should be written. If NULL, the current number of detected devices is written to count.count
: Pointer to a size_t, which should initially contain the number of devices the buffer can hold, and will afterwards contain the number of devices found.
The neodevice_t can later be passed by reference into the API to perform actions relating to the device. The neodevice_t contains a handle to the internal memory for the icsneo::Device object. The memory for the internal icsneo::Device object is managed by the API.
Any neodevice_t objects which have not been opened will become invalid when icsneo_findAllDevices() is called again. To invoke this behavior without finding devices again, call icsneo_freeUnconnectedDevices().
If the size provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case.
-
void
icsneo_freeUnconnectedDevices
()¶ Invalidate neodevice_t objects which have not been opened.
See icsneo_findAllDevices() for information regarding the neodevice_t validity contract.
-
bool
icsneo_serialNumToString
(uint32_t num, char *str, size_t *count)¶ Convert a serial number in numerical format to its string representation.
On older devices, the serial number is one like 138635, the numerical representation is the same as the string representation.
- Return
- True if str contains the string representation of the given serial number.
- Parameters
num
: A numerical serial number.str
: A pointer to a buffer where the string representation will be written. NULL can be passed, which will write a character count tocount
.count
: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size count + 1 to account for the NULL terminator), and after the call holds the number of characters written.
On newer devices, the serial number is one like RS2259, and this function can convert the numerical value back into the string seen on the back of the device.
A query for length (
str == NULL
) will return false. icsneo_getLastError() should be checked to verify that the neodevice_t provided was valid.The client application should provide a buffer of size 7, as serial numbers are always 6 characters or fewer.
If the size provided is not large enough, the output will be NOT be truncated. Nothing will be written to the output. Instead, an icsneo::APIEvent::BufferInsufficient will be available in icsneo_getLastError(). False will be returned, and
count
will now contain the number of bytes necessary to store the full string.
-
uint32_t
icsneo_serialStringToNum
(const char *str)¶ Convert a serial number in string format to its numerical representation.
On older devices, the serial number is one like 138635, and this string will simply be returned as a number.
- Return
- The numerical representation of the serial number, or 0 if the conversion was unsuccessful.
- Parameters
str
: A NULL terminated string containing the string representation of an Intrepid serial number.
On newer devices, the serial number is one like RS2259, and this function can convert that string to a number.
-
bool
icsneo_isValidNeoDevice
(const neodevice_t *device)¶ Verify that a neodevice_t is valid.
This check is automatically performed at the beginning of any API function that operates on a device. If there is a failure, an icsneo::APIEvent::InvalidNeoDevice will be available in
icsneo_getLastError().- Return
- True if the neodevice_t is valid.
- Parameters
device
: A pointer to the neodevice_t structure to operate on.
See icsneo_findAllDevices() for information regarding the neodevice_t validity contract.
-
bool
icsneo_openDevice
(const neodevice_t *device)¶ Connect to the specified hardware.
The device
MUST be opened before any other functions which operate on the device will be valid.- Return
- True if the connection could be opened.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to open.
See icsneo_goOnline() for information about enabling network communication once the device is open.
If the open did not succeed, icsneo_getLastError() should provide more information about why.
If the device was already open, an icsneo::APIEvent::DeviceCurrentlyOpen will be available in icsneo_getLastError().
-
bool
icsneo_closeDevice
(const neodevice_t *device)¶ Close an open connection to the specified hardware.
After this function succeeds, the
neodevice_t will be invalid. To connect again, you must call icsneo_findAllDevices() or similar to re-find the device.- Return
- True if the connection could be closed.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to close.
-
bool
icsneo_isOpen
(const neodevice_t *device)¶ Verify network connection for the specified hardware.
This function does not modify the working state of the device at all.
- Return
- True if the device is connected.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
See icsneo_openDevice() for an explanation about the concept of being “open”.
-
bool
icsneo_goOnline
(const neodevice_t *device)¶ Enable network communication for the specified hardware.
The device is not “online” when it is first opened. It is not possible to receive or transmit while the device is “offline”. Network controllers are disabled. (i.e. In the case of CAN, the hardware will not send ACKs on the client application’s behalf)
- Return
- True if communication could be enabled.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
This allows filtering or handlers to be set up before allowing traffic to flow.
This also allows device settings to be set (i.e. baudrates) before enabling the controllers, which prevents momentarily causing loss of communication if the baud rates are not correct.
-
bool
icsneo_goOffline
(const neodevice_t *device)¶ Disable network communication for the specified hardware.
See
icsneo_goOnline() for an explanation about the concept of being “online”.- Return
- True if communication could be disabled.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
-
bool
icsneo_isOnline
(const neodevice_t *device)¶ Verify network communication for the specified hardware.
This function does not modify the working state of the device at all.
- Return
- True if communication is enabled.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
See icsneo_goOnline() for an explanation about the concept of being “online”.
-
bool
icsneo_enableMessagePolling
(const neodevice_t *device)¶ Enable buffering of messages for the specified hardware.
By default, traffic the device receives will not reach the client application. The client application must register traffic handlers, enable message polling, or both. This function addresses message polling.
- Return
- True if polling could be enabled.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
With polling enabled, all traffic that the device receives will be stored in a buffer managed by the API. The client application should then call icsneo_getMessages() periodically to take ownership of the messages in that buffer.
The API managed buffer will only grow to a specified size, 20k messages by default. See icsneo_getPollingMessageLimit() and icsneo_setPollingMessageLimit() for more information.
In high traffic situations, the default 20k message limit can be reached very quickly. The client application will have to call icsneo_getMessages() very often to avoid losing messages, or change the limit.
If the message limit is exceeded before a call to icsneo_getMessages() takes ownership of the messages, the oldest message will be dropped (LOST) and an icsneo::APIEvent::PollingMessageOverflow will be flagged for the device.
This function will succeed even if the device is not open.
-
bool
icsneo_disableMessagePolling
(const neodevice_t *device)¶ Disable buffering of messages for the specified hardware.
See
icsneo_enableMessagePolling() for more information about the message polling system.- Return
- True if polling could be disabled.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
Any messages left in the API managed buffer will be lost upon disabling polling.
-
bool
icsneo_isMessagePollingEnabled
(const neodevice_t *device)¶ Verify message polling status for the specified hardware.
This function does not modify the working state of the device at all.
- Return
- True if polling is enabled.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
See icsneo_enableMessagePolling() for an explanation about how polling works.
-
bool
icsneo_getMessages
(const neodevice_t *device, neomessage_t *messages, size_t *items, uint64_t timeout)¶ Read out messages which have been recieved.
Messages are available using this function if
icsneo_goOnline() and icsneo_enableMessagePolling() have been called. See those functions for more information.- Return
- True if the messages were read out successfully (even if there were no messages to read) or if the count was read successfully.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.messages
: A pointer to a buffer which neomessage_t structures will be written to. NULL can be passed, which will write the current message count to size.items
: A pointer to a size_t which, prior to the call, holds the maximum number of messages to be written, and after the call holds the number of messages written.timeout
: The number of milliseconds to wait for a message to arrive. A value of 0 indicates a non-blocking call. Querying for the current message count is always asynchronous and ignores this value.
Messages are read out of the API managed buffer in order of oldest to newest. As they are read out, they are removed from the API managed buffer.
If size is too small to contain all messages, as many messages as will fit will be read out. Subsequent calls to icsneo_getMessages() can retrieve any messages which were not read out.
The memory for the data pointer within the neomessage_t is managed by the API. Do not attempt to free the data pointer. The memory will become invalid the next time icsneo_getMessages() is called for this device.
size_t messageCount; bool result = icsneo_getMessages(device, NULL, &messageCount, 0); // Reading the message count // Handle errors here neomessage_t* messages = malloc(messageCount * sizeof(neomessage_t)); // It is also possible and encouraged to use a static buffer result = icsneo_getMessages(device, messages, &messageCount, 0); // Non-blocking // Handle errors here for(size_t i = 0; i < messageCount; i++) { switch(messages[i].type) { case ICSNEO_NETWORK_TYPE_CAN: { // All messages of type CAN can be accessed using neomessage_can_t neomessage_can_t* canMessage = (neomessage_can_t*)&messages[i]; printf("ArbID: 0x%x\n", canMessage->arbid); printf("DLC: %u\n", canMessage->length); printf("Data: "); for(size_t i = 0; i < canMessage->length; i++) { printf("%02x ", canMessage->data[i]); } printf("\nTimestamp: %lu\n", canMessage->timestamp); } } } free(messages);
- Warning
- Do not call icsneo_close() while another thread is waiting on icsneo_getMessages(). Always allow the other thread to timeout first!
-
int
icsneo_getPollingMessageLimit
(const neodevice_t *device)¶ Get the maximum number of messages which will be held in the API managed buffer for the specified hardware.
See
icsneo_enableMessagePolling() for more information about the message polling system.- Return
- Number of messages, or -1 if device is invalid.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
-
bool
icsneo_setPollingMessageLimit
(const neodevice_t *device, size_t newLimit)¶ Set the maximum number of messages which will be held in the API managed buffer for the specified hardware.
See
icsneo_enableMessagePolling() for more information about the message polling system.- Return
- True if the limit was set successfully.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.newLimit
: The new limit to be enforced.
Setting the maximum lower than the current number of stored messages will cause the oldest messages to be dropped (LOST) and an icsneo::APIEvent::PollingMessageOverflow to be flagged for the device.
-
int
icsneo_addMessageCallback
(const neodevice_t *device, void (*callback)(neomessage_t), void *, )¶ Adds a message callback to the specified device to be called when a new message is received.
- Return
- The id of the callback added, or -1 if the operation failed.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.callback
: A function pointer with void return type and a single neomessage_t parameter.filter
: Unused for now. Exists as a placeholder here for future backwards-compatibility.
-
bool
icsneo_removeMessageCallback
(const neodevice_t *device, int id)¶ Removes a message callback from the specified device.
- Return
- True if the callback was successfully removed.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.id
: The id of the callback to remove.
-
neonetid_t
icsneo_getNetworkByNumber
(const neodevice_t *device, neonettype_t type, unsigned int number)¶ Get the network ID for the nth network of a specified type on this device.
This function is designed so that networks can be enumerated without knowledge of the specific device. For instance, on a ValueCAN 4-2, the second CAN network is ICSNEO_NETID_HSCAN2, while on a neoVI FIRE the second CAN network is ICSNEO_NETID_MSCAN.
- Return
- The netid if the call succeeds, ICSNEO_NETID_INVALID otherwise
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.type
: An ICSNEO_NETWORK_TYPE_* constant denoting the network typenumber
: The number of this network starting from 1
-
bool
icsneo_getProductName
(const neodevice_t *device, char *str, size_t *maxLength)¶ Get the friendly product name for a specified device.
In the case of a neoVI FIRE 2, this function will write a string “neoVI FIRE 2” with a NULL terminator into str.
- Return
- True if str was written to
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.str
: A pointer to a buffer where the string will be written. NULL can be passed, which will write a character count to maxLength.maxLength
: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size maxLength + 1 to account for the NULL terminator), and after the call holds the number of characters written.
The constant ICSNEO_DEVICETYPE_LONGEST_NAME is defined for the client application to create static buffers of the correct length.
See also icsneo_describeDevice().
A query for length (
str == NULL
) will return false. icsneo_getLastError() should be checked to verify that the neodevice_t provided was valid.If the size provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case. True will still be returned.
-
bool
icsneo_getProductNameForType
(devicetype_t type, char *str, size_t *maxLength)¶ Get the friendly product name for a specified devicetype.
In the case of a neoVI FIRE 2, this function will write a string “neoVI FIRE 2” with a NULL terminator into str.
- Return
- True if str was written to
- Parameters
type
: A neodevice_t structure specifying the device to operate on.str
: A pointer to a buffer where the string will be written. NULL can be passed, which will write a character count to maxLength.maxLength
: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size maxLength + 1 to account for the NULL terminator), and after the call holds the number of characters written.
Note that icsneo_getProductName should always be preferred where available, as the product name may change based on device-specific factors, such as the serial number.
The constant ICSNEO_DEVICETYPE_LONGEST_NAME is defined for the client application to create static buffers of the correct length.
See also icsneo_describeDevice().
A query for length (
str == NULL
) will return false. icsneo_getLastError() should be checked to verify that the neodevice_t provided was valid.If the size provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case. True will still be returned.
-
bool
icsneo_settingsRefresh
(const neodevice_t *device)¶ Trigger a refresh of the settings structure for a specified device.
- Return
- True if the refresh succeeded.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
-
bool
icsneo_settingsApply
(const neodevice_t *device)¶ Commit the settings structure for a specified device to non-volatile storage.
When modifications are made to the device settings, this function (or
icsneo_settingsApplyTemporary()) must be called to send the changes to the device and make them active.- Return
- True if the settings were applied.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
This function sets the settings such that they will survive device power cycles.
If the function fails, the settings will be refreshed so that the structure in the API matches the one held by the device.
-
bool
icsneo_settingsApplyTemporary
(const neodevice_t *device)¶ Apply the settings structure for a specified device temporarily.
See
icsneo_settingsApply() for further information about applying settings.- Return
- True if the settings were applied.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
This function sets the settings such that they will revert to the values saved in non-volatile storage when the device loses power.
-
bool
icsneo_settingsApplyDefaults
(const neodevice_t *device)¶ Apply the default settings structure for a specified device.
See
icsneo_settingsApply() for further information about applying settings.- Return
- True if the default settings were applied.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
This function sets the default settings such that they will survive device power cycles.
-
bool
icsneo_settingsApplyDefaultsTemporary
(const neodevice_t *device)¶ Apply the default settings structure for a specified device temporarily.
See
icsneo_settingsApply() for further information about applying settings. See icsneo_settingsApplyDefaults() for further information about applying default settings.- Return
- True if the default settings were applied.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.
This function sets the default settings such that they will revert to the values saved in non-volatile storage when the device loses power.
-
int
icsneo_settingsReadStructure
(const neodevice_t *device, void *structure, size_t structureSize)¶ Apply the default settings structure for a specified device temporarily.
See
icsneo_settingsApply() for further information about applying settings. See icsneo_settingsApplyDefaults() for further information about applying default settings.- Return
- Number of bytes written to structure, or -1 if the operation failed.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.structure
: A pointer to a device settings structure for the current device.structureSize
: The size of the current device settings structure in bytes.
This function sets the default settings such that they will revert to the values saved in non-volatile storage when the device loses power.
If possible, use functions specific to the operation you want to acomplish (such as icsneo_setBaudrate()) instead of modifying the structure directly. This allows the client application to work with other hardware.
-
bool
icsneo_settingsApplyStructure
(const neodevice_t *device, const void *structure, size_t structureSize)¶ Apply a provided settings structure for a specified device.
This function immediately applies the provided settings. See
icsneo_settingsApplyTemporary() for further information about applying settings.- Return
- True if the settings were applied.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.structure
: A pointer to a device settings structure for the current device.structureSize
: The size of the current device settings structure in bytes.
If possible, use functions specific to the operation you want to acomplish (such as icsneo_setBaudrate()) instead of modifying the structure directly. This allows the client application to work with other hardware.
-
bool
icsneo_settingsApplyStructureTemporary
(const neodevice_t *device, const void *structure, size_t structureSize)¶ Apply a provided settings structure for a specified device without saving to non-volatile EEPROM.
This function immediately applies the provided settings. See
icsneo_settingsApply() for further information about applying settings.- Return
- True if the settings were applied.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.structure
: A pointer to a device settings structure for the current device.structureSize
: The size of the current device settings structure in bytes.
This function sets the default settings such that they will revert to the values saved in non-volatile storage when the device loses power.
If possible, use functions specific to the operation you want to acomplish (such as icsneo_setBaudrate()) instead of modifying the structure directly. This allows the client application to work with other hardware.
-
int64_t
icsneo_getBaudrate
(const neodevice_t *device, neonetid_t netid)¶ Get the network baudrate for a specified device.
In the case of CAN, this function gets the standard CAN baudrate. See
icsneo_getFDBaudrate() to get the baudrate for (the baudrate-switched portion of) CAN FD.- Return
- The value in baud with no multipliers. (i.e. 500k becomes 500000) A negative value is returned if an error occurs.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network for which the baudrate should be retrieved.
-
bool
icsneo_setBaudrate
(const neodevice_t *device, neonetid_t netid, int64_t newBaudrate)¶ Set the network baudrate for a specified device.
In the case of CAN, this function sets the standard CAN baudrate. See
icsneo_setFDBaudrate() to set the baudrate for (the baudrate-switched portion of) CAN FD.- Return
- True if the baudrate could be set.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network to which the new baudrate should apply.newBaudrate
: The requested baudrate, with no multipliers. (i.e. 500K CAN should be represented as 500000)
Call icsneo_settingsApply() or similar to make the changes active on the device.
-
int64_t
icsneo_getFDBaudrate
(const neodevice_t *device, neonetid_t netid)¶ Get the CAN FD baudrate for a specified device.
See
icsneo_getBaudrate() to get the baudrate for the non baudrate-switched portion of CAN FD, classical CAN 2.0, and other network types.- Return
- The value in baud with no multipliers. (i.e. 500k becomes 500000) A negative value is returned if an error occurs.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network for which the baudrate should be retrieved.
-
bool
icsneo_setFDBaudrate
(const neodevice_t *device, neonetid_t netid, int64_t newBaudrate)¶ Set the CAN FD baudrate for a specified device.
See
icsneo_setBaudrate() to set the baudrate for the non baudrate-switched portion of CAN FD, classical CAN 2.0, and other network types.- Return
- True if the baudrate could be set.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network to which the new baudrate should apply.newBaudrate
: The requested baudrate, with no multipliers. (i.e. 2Mbaud CAN FD should be represented as 2000000)
Call icsneo_settingsApply() or similar to make the changes active on the device.
-
bool
icsneo_transmit
(const neodevice_t *device, const neomessage_t *message)¶ Transmit a single message.
To transmit a message, you must set the
data
,length
, andnetid
attributes of the neomessage_t.- Return
- True if the message was verified transmittable and enqueued for transmit.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to transmit on.message
: A pointer to the neomessage_t structure defining the message.
The
data
attribute must be set to a pointer to a buffer of at leastlength
which holds the payload bytes. This buffer only needs to be valid for the duration of this call, and can safely be deallocated or reused after the return.You may also have to set network dependent variables. For CAN, you must set the
arbid
attribute defined in neomessage_can_t.Other attributes of the neomessage_t such as
timestamp
,type
andreserved
which are not used should be set to 0. Unused status bits should also be set to 0.Any types defined
neomessage_*_t
are designed to be binary compatible with neomessage_t.For instance, for CAN, it is recommended to use neomessage_can_t as it exposes the
arbid
field.neomessage_can_t mySendMessage = {}; // Zero all before use uint8_t myData[3] = { 0xAA, 0xBB, 0xCC }; // Either heap or stack allocated is okay mySendMessage.netid = ICSNEO_NETID_HSCAN; mySendMessage.arbid = 0x1c5001c5; mySendMessage.length = 3; mySendMessage.data = myData; mySendMessage.status.canfdFDF = true; // CAN FD mySendMessage.status.extendedFrame = true; // Extended (29-bit) arbitration IDs mySendMessage.status.canfdBRS = true; // CAN FD Baudrate Switch bool result = icsneo_transmit(device, (neomessage_t*)&mySendMessage); myData[1] = 0x55; // The message and buffer can be safely reused for the next message result = icsneo_transmit(device, (neomessage_t*)&mySendMessage);
-
bool
icsneo_transmitMessages
(const neodevice_t *device, const neomessage_t *messages, size_t count)¶ Transmit a multiple messages.
See
icsneo_transmit() for information regarding transmitting messages.- Return
- True if the messages were verified transmittable and enqueued for transmit.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to transmit on.messages
: A pointer to the neomessage_t structures defining the messages.count
: The number of messages to transmit.
On a per-network basis, messages will be transmitted in the order that they were enqueued.
In this case, messages will be enqueued in order of increasing index.
-
void
icsneo_setWriteBlocks
(const neodevice_t *device, bool blocks)¶ Set the behavior of whether writing is a blocking action or not.
By default, writing is a blocking action.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to transmit on.blocks
: Whether or not writing is a blocking action.
-
bool
icsneo_describeDevice
(const neodevice_t *device, char *str, size_t *maxLength)¶ Get the friendly description for a specified device.
In the case of a neoVI FIRE 2 with serial number CY2285, this function will write a string “neoVI FIRE 2 CY2285” with a NULL terminator into str.
- Return
- True if str was written to
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.str
: A pointer to a buffer where the string will be written. NULL can be passed, which will write a character count to maxLength.maxLength
: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size maxLength + 1 to account for the NULL terminator), and after the call holds the number of characters written.
The constant ICSNEO_DEVICETYPE_LONGEST_DESCRIPTION is defined for the client application to create static buffers of the correct length.
See also icsneo_getProductName().
A query for length (
str == NULL
) will return false. icsneo_getLastError() should be checked to verify that the neodevice_t provided was valid.If the size provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case. True will still be returned.
-
neoversion_t
icsneo_getVersion
(void)¶ Get the version of libicsneo in use.
- Return
- A neoversion_t structure containing the version.
-
int
icsneo_addEventCallback
(void (*callback)(neoevent_t), void *, )¶ Adds an event callback to be called when a new event is added.
Do not attempt to add or remove callbacks inside of a callback, as the stored callbacks are locked during calls.
- Return
- The id of the callback added. Does not error.
- Parameters
callback
: A function pointer with void return type and a single neoevent_t parameter.filter
: Unused for now. Exists as a placeholder here for future backwards-compatibility.
-
bool
icsneo_removeEventCallback
(int id)¶ Removes an event callback.
- Return
- True if the callback was successfully removed.
- Parameters
id
: The id of the callback to remove.
-
bool
icsneo_getEvents
(neoevent_t *events, size_t *size)¶ Read out events which have occurred in API operation.
Events contain INFO and WARNINGS, and may potentially contain one TooManyEvents WARNING at the end. No ERRORS are found in Events, see
icsneo_getLastError() instead.- Return
- True if the events were read out successfully (even if there were no events to report).
- Parameters
events
: A pointer to a buffer which neoevent_t structures will be written to. NULL can be passed, which will write the current event count to size.size
: A pointer to a size_t which, prior to the call, holds the maximum number of events to be written, and after the call holds the number of events written.
Events can be caused by API usage, such as providing too small of a buffer or disconnecting from a device.
Events can also occur asynchronously to the client application threads, in the case of a device communication event or similar.
Events are read out of the API managed buffer in order of oldest to newest. As they are read out, they are removed from the API managed buffer.
If size is too small to contain all events, as many events as will fit will be read out. Subsequent calls to icsneo_getEvents() can retrieve any events which were not read out.
-
bool
icsneo_getDeviceEvents
(const neodevice_t *device, neoevent_t *events, size_t *size)¶ Read out events which have occurred in API operation for a specific device.
See
icsneo_getEvents() for more information about the event system.- Return
- True if the events were read out successfully (even if there were no events to report).
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to read out events for. NULL can be passed, which indicates that ONLY events not associated with a device are desired (API events).events
: A pointer to a buffer which neoevent_t structures will be written to. NULL can be passed, which will write the current event count to size.size
: A pointer to a size_t which, prior to the call, holds the maximum number of events to be written, and after the call holds the number of events written.
-
bool
icsneo_getLastError
(neoevent_t *error)¶ Read out the last error which occurred in API operation on this thread.
All errors are stored on a per-thread basis, meaning that calling
icsneo_getLastError() will return the last error that occured on the calling thread. Any errors can only be retrieved through this function, and NOT icsneo_getEvents() or similar! Only INFO and WARNING level events are accessible through those. Only the last error is stored, so the intention is for this function to be called immediately following another failed API call.- Return
- True if an error was read out.
- Parameters
error
: A pointer to a buffer which a neoevent_t structure will be written to.
The API error system is thread-safe. Only an API error which occurred on the current thread will be returned.
See icsneo_getEvents() for more information about the event system.
This operation removes the returned error from the buffer, so subsequent calls to error functions will not include the error.
-
void
icsneo_discardAllEvents
(void)¶ Discard all events which have occurred in API operation. Does NOT discard any errors.
-
void
icsneo_discardDeviceEvents
(const neodevice_t *device)¶ Discard all events which have occurred in API operation.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to discard events for. NULL can be passed, which indicates that ONLY events not associated with a device are desired (API events). Does NOT discard any errors (device or otherwise).
-
void
icsneo_setEventLimit
(size_t newLimit)¶ Set the number of events which will be held in the API managed buffer before icsneo::APIEvent::TooManyEvents.
If the event limit is reached, an icsneo::APIEvent::TooManyEvents will be flagged.
- Parameters
newLimit
: The new limit. Must be >10. 1 event slot is always reserved for a potential icsneo::APIEvent::TooManyEvents, so (newLimit - 1) other events can be stored.
If the
newLimit
is smaller than the current event count, events will be removed in order of decreasing age. This will also flag an icsneo::APIEvent::TooManyEvents.
-
size_t
icsneo_getEventLimit
(void)¶ Get the number of events which can be held in the API managed buffer.
- Return
- The current limit.
-
bool
icsneo_getSupportedDevices
(devicetype_t *devices, size_t *count)¶ Get the devices supported by the current version of the API.
See
icsneo_getProductNameForType() to get textual descriptions of each device.- Return
- True if devices was written to
- Parameters
devices
: A pointer to a buffer of devicetype_t structures which will be written to. NULL can be passed, which will write the current supported device count to count.count
: A pointer to a size_t which, prior to the call, holds the maximum number of devicetype_t structures to be written, and after the call holds the number of devicetype_t structures written.
A query for length (
devices == NULL
) will return false.If the count provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case. True will still be returned.
-
bool
icsneo_getTimestampResolution
(const neodevice_t *device, uint16_t *resolution)¶ Get the timestamp resolution for the given device.
- Return
- True if the resolution was written
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to read out the timestamp for.resolution
: A pointer to a uint16_t where the resolution will be stored. This value is in nanoseconds.
-
bool
icsneo_getDigitalIO
(const neodevice_t *device, neoio_t type, uint32_t number, bool *value)¶ Get the value of a digital IO for the given device.
These values are often not populated if the device is not “online”.
- Return
- True if the value is read successfully
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.type
: The IO typenumber
: The index within the IO type, starting from 1value
: A pointer to the uint8_t which will store the value of the IO port, if successful
-
bool
icsneo_setDigitalIO
(const neodevice_t *device, neoio_t type, uint32_t number, bool value)¶ Get the value of a digital IO for the given device.
Note that this function is not synchronous with the device confirming the change.
- Return
- True if the parameters and connection state are correct to submit the request to the device
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.type
: The IO typenumber
: The index within the IO type, starting from 1value
: The value which will be written to the IO
-
bool
icsneo_isTerminationSupportedFor
(const neodevice_t *device, neonetid_t netid)¶ Check whether software switchable termination is supported for a given network on this device.
This does not check whether another network in the termination group has termination enabled, check canTerminationBeEnabledFor for that.
- Return
- True if software switchable termination is supported
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network ID to check
-
bool
icsneo_canTerminationBeEnabledFor
(const neodevice_t *device, neonetid_t netid)¶ Check whether software switchable termination can currently be enabled for a given network.
If another network in the group is already enabled, or if termination is not supported on this network, false is returned and an error will have been reported in
icsneo_getLastError().- Return
- True if software switchable termination can currently be enabled
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network ID to check
-
bool
icsneo_isTerminationEnabledFor
(const neodevice_t *device, neonetid_t netid)¶ Check whether software switchable termination is currently enabled for a given network in the currently active device settings.
Note that if the termination status is set, but not yet applied to the device, the current device status will be reflected here rather than the pending status.
- Return
- True if software switchable termination is currently enabled
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network ID to check
False will be returned and an error will be set in icsneo_getLastError if the setting is unreadable.
-
bool
icsneo_setTerminationFor
(const neodevice_t *device, neonetid_t netid, bool enabled)¶ Enable or disable software switchable termination for a given network.
All other networks in the termination group must be disabled prior to the call, but the change does not need to be applied to the device before enqueing the enable.
- Return
- True if if the call was successful, otherwise an error will have been reported in icsneo_getLastError().
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.netid
: The network ID to affectenabled
: Whether to enable or disable switchable termination
-
int
icsneo_getDeviceStatus
(const neodevice_t *device, void *status, size_t *size)¶ Return the device status structures for a specified device.
This function populates the device status structures and sub members.
- Return
- True if the device status was successfully read.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to operate on.status
: A pointer to a device status structure for the current device.size
: The size of the current device status structure in bytes.
-
bool
icsneo_getRTC
(const neodevice_t *device, uint64_t *output)¶ Get the real-time clock for the given device.
- Return
- True if the RTC was successfully retrieved.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to read the RTC from.output
: A pointer to a uint64_t where the RTC will be stored. This value is in seconds.
-
bool
icsneo_setRTC
(const neodevice_t *device, uint64_t input)¶ Set the real-time clock for the given device.
- Return
- True if the RTC was successfully set.
- Parameters
device
: A pointer to the neodevice_t structure specifying the device to write the RTC to.input
: A uint64_t object holding the RTC value. This value is in seconds.