C API Poll Functions¶

Group Based Poll¶

The polling in the C-API is based on so called subscription groups. Each group can be subscribed to one or multiple nodes. After subscribing a group can be polled for events. Groups can be created dynamically, but there is a default group (ZI_DEFAULT_SUBSCRIPTION_GROUP) that always exist and allows simplified access. Note that the HF2, MF and UHF device families only support the default group and it is not possible to create custom groups.

ziAPICreateSubscriptionGroup¶

ZIResult_enum ziAPICreateSubscriptionGroup(ZIConnection conn, ZISubscriptionGroupId *groupId)

creates a new subscription group

This function spawns a new subscription group. A subscription group allows grouping of subscriptions and waiting for data from multiple subscriptions at once. Every group is independent of the others and can be polled independently from the others.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ziConnection for which the group will be created
groupId	ZISubscriptionGroupId *	out	Pointer to the ZISubscriptionGroupId that will be created

Returns

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_INVALID_ARGUMENT if the connection does not support subscription groups
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPISubscribeWithGroup¶

ZIResult_enum ziAPISubscribeWithGroup(ZIConnection conn, ZISubscriptionGroupId groupId, const char *path)

subscribes the nodes given by path to the specified group for :ziAPIPollDataWithGroup:

This function adds a node subscription to the specified group so that whenever the value of the node changes the new value can be polled using ziAPIPollDataWithGroup. 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. When using device from the HF2, MF or UHF device family, the groupId must be set to ZI_DEFAULT_SUBSCRIPTION_GROUP.Note that subscription groups are independent of each other. This means that the same path can be added to different groups. Both groups receive data for the given node.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ZIConnection for which events should be received
groupId	ZISubscriptionGroupId	in	Id of the group to be polled.
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_INVALID_ARGUMENT if the group does not exist.
ZI_ERROR_NOT_SUPPORTED if the path belongs to a HF2, MF or UHF device and a group different from the ZI_DEFAULT_SUBSCRIPTION_GROUP is used
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.

ziAPIPollDataWithGroup¶

ZIResult_enum ziAPIPollDataWithGroup(ZIConnection conn, ZISubscriptionGroupId groupId, ZIEvent **event, uint32_t timeoutMilliseconds)

checks if an event is available for read for the specified group.

This function returns immediately if an event for the specified group is pending. Otherwise it waits for an event for up to timeOutMilliseconds. All value changes that occur in nodes that have been subscribed to in the specified group 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.The event is allocated by the function and must be deallocated by the user using ziAPIDeallocateEventEx.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ziConnection for which events should be received
groupId	ZISubscriptionGroupId	in	Id of the group to which the path will be subscribed
event	ZIEvent **	out	Pointer to a ZIEvent pointer which will point to the received event
timeoutMilliseconds	uint32_t	in	Time to wait for an event in milliseconds. If -1 it will wait forever,

Returns

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_INVALID_ARGUMENT if the group does not exist.
ZI_ERROR_NOT_SUPPORTED if the connection belongs to an HF2, MF or UHF device and a group different from the ZI_DEFAULT_SUBSCRIPTION_GROUP is used
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.

ziAPIDeallocateEventEx¶

void ziAPIDeallocateEventEx(ZIEvent *ev)

Deallocates ZIEvent structure.

This function frees the underlying memory of a ZIEvent structure that was allocated by the LabOne API.

Related Functions: ziAPIPollDataWithGroup, ziAPIAllocateEventEx

Parameters

Name	Type	Direction	Description
ev	ZIEvent *	in	Pointer to ZIEvent structure to be deallocated..

ziAPIDeleteSubscriptionGroup¶

ZIResult_enum ziAPIDeleteSubscriptionGroup(ZIConnection conn, ZISubscriptionGroupId groupId)

delete a specific group and all its subscriptions

This function is the complement to ziAPISubscribeWithGroup. It deletes the group and all its subscriptions. It is not possible to unsubscribe a single path from a group.Note that the ZI_DEFAULT_SUBSCRIPTION_GROUP is a special group that cannot be deleted.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ziConnection for which the group will be created
groupId	ZISubscriptionGroupId	in	Id of the group to which the path will be subscribed

Returns

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_INVALID_ARGUMENT if the connection does not support subscription groups or the group does not exist
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

Default Group Poll¶

The following functions historically only work with in the default group and do not work with custom subscription groups

ziAPISubscribe¶

ZIResult_enum ziAPISubscribe(ZIConnection conn, const char *path)

subscribes the nodes given by path for ziAPIPollDataWithGroup

This function subscribes to nodes so that whenever the value of the node changes the new value can be polled using ziAPIPollDataWithGroup. 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.ziAPISubscribe is equivalent to ziAPISubscribeWithGroup with group set to ZI_DEFAULT_SUBSCRIPTION_GROUP. See Data Handling for an example

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

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.

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 ziAPIPollDataWithGroup, even when the node is not subscribed or no value change has occurred. The received value is added to the ZI_DEFAULT_SUBSCRIPTION_GROUP only. See Data Handling for an example

Related Functions: ziAPISubscribeWithGroup, ziAPIPollDataWithGroup

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

Deprecated Poll¶

The following functions are deprecated and should not be used in new code. They are provided for backwards compatibility only.

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.

Related Functions: ziAPIDeallocateEventEx

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.

Related Functions: ziAPISubscribe, ziAPIUnSubscribe, ziAPIGetValueAsPollData, ziEvent, ziAPIPollDataWithGroup

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.