C API Poll Functions¶
ziAPIAllocateEventEx¶
ZIEvent* ziAPIAllocateEventEx(void)
Allocates ZIEvent structure and returns the pointer to it. Attention!!! It is the client code responsibility to deallocate the structure by calling ziAPIDeallocateEventEx!
This function allocates a ZIEvent structure and returns the pointer to it. Free the memory using ziAPIDeallocateEventEx. ziAPIDeallocateEventEx
ziAPIDeallocateEventEx¶
void ziAPIDeallocateEventEx(ZIEvent *ev)
Deallocates ZIEvent structure created with ziAPIAllocateEventEx().
This function is the compliment to ziAPIAllocateEventEx() ziAPIAllocateEventEx
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| ev | ZIEvent * | in | Pointer to ZIEvent structure to be deallocated.. |
ziAPISubscribe¶
ZIResult_enum ziAPISubscribe(ZIConnection conn, const char *path)
subscribes the nodes given by path for ziAPIPollDataEx
This function subscribes to nodes so that whenever the value of the node changes the new value can be polled using ziAPIPollDataEx. By using wildcards or by using a path that is not a leaf node but contains sub nodes, more than one leaf can be subscribed to with one function call. See Data Handling for an example ziAPIUnSubscribe, ziAPIPollDataEx, ziAPIGetValueAsPollData
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which to subscribe for |
| path | const char * | in | Path to the nodes to subscribe |
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_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.
ziAPIUnSubscribe¶
ZIResult_enum ziAPIUnSubscribe(ZIConnection conn, const char *path)
unsubscribes to the nodes given by path
This function is the complement to ziAPISubscribe. By using wildcards or by using a path that is not a leaf node but contains sub nodes, more than one node can be unsubscribed with one function call. See Data Handling for an example ziAPISubscribe, ziAPIPollDataEx, ziAPIGetValueAsPollData
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ziConnection for which to unsubscribe for |
| path | const char * | in | Path to the Nodes to unsubscribe |
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_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.
ziAPIPollDataEx¶
ZIResult_enum ziAPIPollDataEx(ZIConnection conn, ZIEvent *ev, uint32_t timeOutMilliseconds)
checks if an event is available to read
This function returns immediately if an event is pending. Otherwise it waits for an event for up to timeOutMilliseconds. All value changes that occur in nodes that have been subscribed to or in children of nodes that have been subscribed to are sent from the Data Server to the ziAPI session. For a description of how the data are available in the struct, refer to the documentation of struct ziEvent. When no event was available within timeOutMilliseconds, the ziEvent::Type field will be ZI_DATA_NONE and the ziEvent::Count field will be zero. Otherwise these fields hold the values corresponding to the event that occurred. See Data Handling for an example ziAPISubscribe, ziAPIUnSubscribe, ziAPIGetValueAsPollData, ziEvent
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection for which events should be received |
| ev | ZIEvent * | out | Pointer to a ZIEvent struct in which the received event will be written |
| timeOutMilliseconds | uint32_t | in | Time to wait for an event in milliseconds. If -1 it will wait forever, if 0 the function returns immediately. |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIGetValueAsPollData¶
ZIResult_enum ziAPIGetValueAsPollData(ZIConnection conn, const char *path)
triggers a value request, which will be given back on the poll event queue
Use this function to receive the value of one or more nodes as one or more events using ziAPIPollDataEx, even when the node is not subscribed or no value change has occurred. See Data Handling for an example ziAPISubscribe, ziAPIUnSubscribe, ziAPIPollDataEx
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection with which the value should be retrieved |
| path | const char * | in | Path to the Node holding the value. Note: Wildcards and paths referring to streamimg nodes are not permitted. |
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 or the length of the char-buffer for the nodes given by MaxLen is too small for all elements
- 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 value is attached to the node
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIAsyncSubscribe¶
ZIResult_enum ziAPIAsyncSubscribe(ZIConnection conn, const char *path, ZIAsyncTag tag)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| tag | ZIAsyncTag |
ziAPIAsyncUnSubscribe¶
ZIResult_enum ziAPIAsyncUnSubscribe(ZIConnection conn, const char *path, ZIAsyncTag tag)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| tag | ZIAsyncTag |
ziAPIAsyncGetValueAsPollData¶
ZIResult_enum ziAPIAsyncGetValueAsPollData(ZIConnection conn, const char *path, ZIAsyncTag tag)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | ||
| path | const char * | ||
| tag | ZIAsyncTag |