C API Set Functions¶
Blocking set functions¶
These functions return only once the device has received the set value. If the set operation fails, an error will be returned.
Note
Before version 25.04, these functions returned without waiting for the device to acknowledge the node value. This is not anymore the case.
ziAPISetValueD¶
ZIResult_enum ziAPISetValueD(ZIConnection conn, const char *path, ZIDoubleData value)
synchronously sets a double-type value to one or more nodes specified in the path
This function sets the values of the nodes specified in path to value. More than one value can be set if a wildcard is used. The function blocks until the value is set on the device.
Related Functions: ziAPIGetValueD
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set. |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set to Value. |
| value | ZIDoubleData | in | The double-type value that will be written to the node(s). |
Returns
- ZI_INFO_SUCCESS on success.
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN.
- ZI_ERROR_WRITEONLY on attempt to get a write-only node.
- ZI_ERROR_COMMAND on an incorrect answer of the server.
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_ERROR_TIMEOUT when communication timed out.
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Up until version 25.01 ziAPISetValueD returned without waiting for the device to acknowledge the node value. Since version 25.04 this is not the case anymore.
ziAPISetComplexData¶
ZIResult_enum ziAPISetComplexData(ZIConnection conn, const char *path, ZIDoubleData real, ZIDoubleData imag)
synchronously sets a double-type complex value to one or more nodes specified in the path
This function sets the values of the nodes specified in path to the complex value (real, imag). More than one value can be set if a wildcard is used. The function blocks until the value is set on the device. If the node does not support complex values only the real value will be updated.
Related Functions: ziAPIGetComplexData
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set. |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set to Value. |
| real | ZIDoubleData | in | The real value that will be written to the node(s). |
| imag | ZIDoubleData | in | The imag value that will be written to the node(s). |
Returns
- ZI_INFO_SUCCESS on success.
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN.
- ZI_ERROR_READONLY on attempt to set a read-only node.
- ZI_ERROR_COMMAND on an incorrect answer of the server.
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_ERROR_TIMEOUT when communication timed out.
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Up until version 25.01 ziAPISetComplexData returned without waiting for the device to acknowledge the node value. Since version 25.04 this is not the case anymore.
ziAPISetValueI¶
ZIResult_enum ziAPISetValueI(ZIConnection conn, const char *path, ZIIntegerData value)
synchronously sets an integer-type value to one or more nodes specified in a path
This function sets the values of the nodes specified in path to value. More than one value can be set if a wildcard is used. The function blocks until the value is set on the device.
Related Functions: ziAPIGetValueI
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| value | ZIIntegerData | in | The int-type value that will be written to the node(s) |
Returns
- ZI_INFO_SUCCESS on success.
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN.
- ZI_ERROR_READONLY on attempt to set a read-only node.
- ZI_ERROR_COMMAND on an incorrect answer of the server.
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_ERROR_TIMEOUT when communication timed out.
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Up until version 25.01 ziAPISetValueI returned without waiting for the device to acknowledge the node value. Since version 25.04 this is not the case anymore.
ziAPISetValueB¶
ZIResult_enum ziAPISetValueB(ZIConnection conn, const char *path, unsigned char *buffer, unsigned int length)
synchronously sets the binary-type value of one or more nodes specified in the path
This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. The function blocks until the value is set on the device.
Related Functions: ziAPIGetValueB
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| buffer | unsigned char * | in | Pointer to the byte array with the data |
| length | unsigned int | in | Length of the data in the buffer |
Returns
- ZI_INFO_SUCCESS on success.
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN.
- ZI_ERROR_READONLY on attempt to set a read-only node.
- ZI_ERROR_COMMAND on an incorrect answer of the server.
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values.
- ZI_ERROR_TIMEOUT when communication timed out.
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Up until version 25.01 ziAPISetValueB returned without waiting for the device to acknowledge the node value. Since version 25.04 this is not the case anymore.
ziAPISetValueString¶
ZIResult_enum ziAPISetValueString(ZIConnection conn, const char *path, const char *str)
synchronously sets a string value of one or more nodes specified in the path
This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. The function blocks until the value is set on the device.
Related Functions: ziAPIGetValueString
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| str | const char * | in | Pointer to a null terminated string (max 64k characters) |
Returns
- ZI_INFO_SUCCESS on success.
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN.
- ZI_ERROR_READONLY on attempt to set a read-only node.
- ZI_ERROR_COMMAND on an incorrect answer of the server.
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values.
- ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
- ZI_ERROR_TIMEOUT when communication timed out.
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Up until version 25.01 ziAPISetValueString returned without waiting for the device to acknowledge the node value. Since version 25.04 this is not the case anymore.
ziAPISetValueStringUnicode¶
ZIResult_enum ziAPISetValueStringUnicode(ZIConnection conn, const char *path, const wchar_t *wstr)
synchronously sets a unicode encoded string value of one or more nodes specified in the path
This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. The function blocks until the value is set on the device.
Related Functions: ziAPIGetValueStringUnicode
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| wstr | const wchar_t * | in | Pointer to a null terminated unicode string (max 64k characters) |
Returns
- ZI_INFO_SUCCESS on success.
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN.
- ZI_ERROR_READONLY on attempt to set a read-only node.
- ZI_ERROR_COMMAND on an incorrect answer of the server.
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values.
- ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
- ZI_ERROR_TIMEOUT when communication timed out.
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Up until version 25.01 ziAPISetValueStringUnicode returned without waiting for the device to acknowledge the node value. Since version 25.04 this is not the case anymore.
ziAPISetVector¶
ZIResult_enum ziAPISetVector(ZIConnection conn, const char *path, const void *vectorData, uint8_t vectorElementType, uint64_t vectorSizeElements)
vectorElementType - see ZIVectorElementType_enum
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| vectorData | const void * | ||
| vectorElementType | uint8_t | ||
| vectorSizeElements | uint64_t |
Batch set functions¶
When many values need to be set, better performance can be achieved by grouping the sets together, instead of sending the set commands one by one. This can be done using the ziAPITransactionalSet functions. These functions return immediately without blocking. The ziAPIEndTransaction function should be called at the end of a series of ziAPITransactionalSet calls. ziAPIEndTransaction waits until all the sets have completed. If any of the set failed, the error will be returned by ziAPIEndTransaction.
ziAPIBeginTransaction¶
ZIResult_enum ziAPIBeginTransaction(ZIConnection conn)
Begin a transaction.
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection |
ziAPIEndTransaction¶
ZIResult_enum ziAPIEndTransaction(ZIConnection conn)
Ends a transaction.
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection |
ziAPITransactionalSetInt¶
ZIResult_enum ziAPITransactionalSetInt(ZIConnection conn, const char *path, ZIIntegerData value)
Related Functions: ziAPISetValueI
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| value | ZIIntegerData |
ziAPITransactionalSetDouble¶
ZIResult_enum ziAPITransactionalSetDouble(ZIConnection conn, const char *path, ZIDoubleData value)
Related Functions: ziAPISetValueD
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| value | ZIDoubleData |
ziAPITransactionalSetComplex¶
ZIResult_enum ziAPITransactionalSetComplex(ZIConnection conn, const char *path, ZIDoubleData real, ZIDoubleData imag)
Related Functions: ziAPISetComplexData
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| real | ZIDoubleData | ||
| imag | ZIDoubleData |
ziAPITransactionalSetBytes¶
ZIResult_enum ziAPITransactionalSetBytes(ZIConnection conn, const char *path, unsigned char *buffer, unsigned int length)
Related Functions: ziAPISetValueB
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| buffer | unsigned char * | ||
| length | unsigned int |
ziAPITransactionalSetVector¶
ZIResult_enum ziAPITransactionalSetVector(ZIConnection conn, const char *path, const void *vectorData, uint8_t vectorElementType, uint64_t vectorSizeElements)
Related Functions: ziAPISetVector
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| vectorData | const void * | ||
| vectorElementType | uint8_t | ||
| vectorSizeElements | uint64_t |
Async set functions¶
These functions return immediately. No error is reported, even if the set operation fails.
ziAPIAsyncSetDoubleData¶
ZIResult_enum ziAPIAsyncSetDoubleData(ZIConnection conn, const char *path, ZIDoubleData value)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| value | ZIDoubleData |
ziAPIAsyncSetIntegerData¶
ZIResult_enum ziAPIAsyncSetIntegerData(ZIConnection conn, const char *path, ZIIntegerData value)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| value | ZIIntegerData |
ziAPIAsyncSetByteArray¶
ZIResult_enum ziAPIAsyncSetByteArray(ZIConnection conn, const char *path, uint8_t *buffer, uint32_t length)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| buffer | uint8_t * | ||
| length | uint32_t |
ziAPIAsyncSetString¶
ZIResult_enum ziAPIAsyncSetString(ZIConnection conn, const char *path, const char *str)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| str | const char * |
ziAPIAsyncSetStringUnicode¶
ZIResult_enum ziAPIAsyncSetStringUnicode(ZIConnection conn, const char *path, const wchar_t *wstr)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| wstr | const wchar_t * |
Legacy blocking set functions¶
These functions block until the device has acknowledged the set value. Since version 25.04, all the ziAPISetValue functions have the same behavior so the ziAPISyncSetValue functions are now superfluous and kept only for backward compatibility.
ziAPISyncSetValueI¶
ZIResult_enum ziAPISyncSetValueI(ZIConnection conn, const char *path, ZIIntegerData *value)
synchronously sets an integer-type value to one or more nodes specified in a path
This function sets the values of the nodes specified in path to value. More than one value can be set if a wildcard is used. The function sets the value synchronously. After returning you know that it is set and to which value it is set.
Related Functions: ziAPIGetValueI, ziAPISetValueI
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the node(s) for which the value(s) will be set |
| value | ZIIntegerData * | in | Pointer to a int-type containing then value to be written. when the function returns value holds the effectively written value. |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN
- ZI_ERROR_READONLY on attempt to set a read-only node
- ZI_ERROR_COMMAND on an incorrect answer of the server
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Since version 25.04 ziAPISyncSetValueI and ziAPISetValueI have the same behavior. Until version 25.01, ziAPISetValueI returned before the device had acknowledged the node value.
ziAPISyncSetValueD¶
ZIResult_enum ziAPISyncSetValueD(ZIConnection conn, const char *path, ZIDoubleData *value)
synchronously sets a double-type value to one or more nodes specified in the path
This function sets the values of the nodes specified in path to Value. More than one value can be set if a wildcard is used. The function sets the value synchronously. After returning you know that it is set and to which value it is set.
Related Functions: ziAPIGetValueD, ziAPISetValueD
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set to value |
| value | ZIDoubleData * | in | Pointer to a double-type containing the value to be written. When the function returns value holds the effectively written value. |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN
- ZI_ERROR_READONLY on attempt to set a read-only node
- ZI_ERROR_COMMAND on an incorrect answer of the server
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Since version 25.04 ziAPISyncSetValueD and ziAPISetValueD have the same behavior. Until version 25.01, ziAPISetValueD returned before the device had acknowledged the node value.
ziAPISyncSetValueB¶
ZIResult_enum ziAPISyncSetValueB(ZIConnection conn, const char *path, uint8_t *buffer, uint32_t *length, uint32_t bufferSize)
Synchronously sets the binary-type value of one or more nodes specified in the path.
This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. This function sets the value synchronously. After returning you know that it is set and to which value it is set.
Related Functions: ziAPIGetValueB, ziAPISetValueB
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| buffer | uint8_t * | in | Pointer to the byte array with the data |
| length | uint32_t * | in | Length of the data in the buffer |
| bufferSize | uint32_t | in | Length of the data in the buffer |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN
- ZI_ERROR_READONLY on attempt to set a read-only node
- ZI_ERROR_COMMAND on an incorrect answer of the server
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Since version 25.04 ziAPISyncSetValueB and ziAPISetValueB have the same behavior. Until version 25.01, ziAPISetValueB returned before the device had acknowledged the node value.
ziAPISyncSetValueString¶
ZIResult_enum ziAPISyncSetValueString(ZIConnection conn, const char *path, const char *str)
Synchronously sets a string value of one or more nodes specified in the path.
This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. This function sets the value synchronously. After returning you know that it is set.
Related Functions: ziAPIGetValueString, ziAPISetValueString
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| str | const char * | inout | Pointer to a null terminated string (max 64k characters) |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN
- ZI_ERROR_READONLY on attempt to set a read-only node
- ZI_ERROR_COMMAND on an incorrect answer of the server
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Since version 25.04 ziAPISyncSetValueString and ziAPISetValueString have the same behavior. Until version 25.01, ziAPISetValueString returned before the device had acknowledged the node value.
ziAPISyncSetValueStringUnicode¶
ZIResult_enum ziAPISyncSetValueStringUnicode(ZIConnection conn, const char *path, const wchar_t *wstr)
Synchronously sets a unicode string value of one or more nodes specified in the path.
This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. This function sets the value synchronously. After returning you know that it is set.
Related Functions: ziAPIGetValueStringUnicode, ziAPISetValueStringUnicode
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which the value(s) will be set |
| path | const char * | in | Path to the Node(s) for which the value(s) will be set |
| wstr | const wchar_t * | inout | Pointer to a null terminated unicode string (max 64k characters) |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
- ZI_ERROR_LENGTH if the Path's Length exceeds MAX_PATH_LEN
- ZI_ERROR_READONLY on attempt to set a read-only node
- ZI_ERROR_COMMAND on an incorrect answer of the server
- ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
- ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
- ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Note
Since version 25.04 ziAPISyncSetValueStringUnicode and ziAPISetValueStringUnicode have the same behavior. Until version 25.01, ziAPISetValueStringUnicode returned before the device had acknowledged the node value.