C API Modules Functions¶

ziAPIModCreate¶

ZIResult_enum ziAPIModCreate(ZIConnection conn, ZIModuleHandle *handle, const char *moduleId)

Create a ZIModuleHandle that can be used for asynchronous measurement tasks.

This function initializes a ziCore module and provides a pointer (handle) with which to access and work with it. Note that this function does not start the module's thread. Before the thread can be started (with ziAPIModExecute):

the device serial (e.g., "dev1000") to be used with module must be specified via ziAPIModSetByteArray.
the desired data (node paths) to record during the measurement must be specified via ziAPIModSubscribe. The module's thread is stopped with ziAPIModClear.

ziAPIModExecute, ziAPIModClear

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection which should be used to initialize the module.
handle	ZIModuleHandle *	out	Pointer to the initialized ZIModuleHandle, which from then on can be used to reference the module.
moduleId	const char *	in	The name specifying the type the module to create (only the following ziCore Modules are currently supported in ziAPI): "sweep" to initialize an instance of the Sweeper Module. "record" to initialize an instance of the Software Trigger (Recorder) Module. "zoomFFT" to initialize an instance of the Spectrum Module. "deviceSettings" to initialize an instance to save/load device settings. "pidAdvisor" to initialize an instance of the PID Advisor Module. "awgModule" to initialize an instance of the AWG Compiler Module. "impedanceModule" to initialize an instance of the Impedance Compensation Module. "scopeModule" to initialize an instance of the Scope Module to assembly scope shots. "multiDeviceSyncModule" to initialize an instance of the Device Synchronization Module. "dataAcquisitionModule" to initialize an instance of the Data Acquisition Module. "precompensationAdvisor" to initialize an instance of the Precompensation Advisor Module. "quantumAnalyzerModule" to initialize an instance of the Quantum Analyzer Module.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_WARNING_NOTFOUND if the provided moduleId was invalid.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSetDoubleData¶

ZIResult_enum ziAPIModSetDoubleData(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIDoubleData value)

Sets a module parameter to the specified double type.

This function is used to configure (set) module parameters which have double types. ziAPIModSetIntegerData, ziAPIModSetByteArray, ziAPIModSetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to set data on.
path	const char *	in	Path of the module parameter to set.
value	ZIDoubleData	in	The double data to write to the path.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSetIntegerData¶

ZIResult_enum ziAPIModSetIntegerData(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIIntegerData value)

Sets a module parameter to the specified integer type.

This function is used to configure (set) module parameters which have integer types. ziAPIModSetDoubleData, ziAPIModSetByteArray, ziAPIModSetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to set data on.
path	const char *	in	Path of the module parameter to set.
value	ZIIntegerData	in	The integer data to write to the path.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSetByteArray¶

ZIResult_enum ziAPIModSetByteArray(ZIConnection conn, ZIModuleHandle handle, const char *path, uint8_t *buffer, uint32_t length)

Sets a module parameter to the specified byte array.

This function is used to configure (set) module parameters which have byte array types. ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to set data on.
path	const char *	in	Path of the module parameter to set.
buffer	uint8_t *	in	Pointer to the byte array with the data.
length	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_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSetString¶

ZIResult_enum ziAPIModSetString(ZIConnection conn, ZIModuleHandle handle, const char *path, const char *str)

Sets a module parameter to the specified null-terminated string.

This function is used to configure (set) module parameters which have string types. ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetByteArray

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to set data on.
path	const char *	in	Path of the module parameter to 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_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSetStringUnicode¶

ZIResult_enum ziAPIModSetStringUnicode(ZIConnection conn, ZIModuleHandle handle, const char *path, const wchar_t *wstr)

Sets a module parameter to the specified null-terminated unicode string.

This function is used to configure (set) module parameters which have string types. ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetByteArray

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to set data on.
path	const char *	in	Path of the module parameter to 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_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSetVector¶

ZIResult_enum ziAPIModSetVector(ZIConnection conn, ZIModuleHandle handle, const char *path, const void *vectorData, ZIVectorElementType_enum elementType, unsigned int numElements)

Sets a module parameter to the specified vector.

This function is used to configure (set) module parameters which have vector types. ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetByteArray

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to set data on.
path	const char *	in	Path of the module parameter to set.
vectorData	const void *	in	Pointer to the vector data.
elementType	ZIVectorElementType_enum	in	Type of elements stored in the vector.
numElements	unsigned int	in	Number of elements of the vector.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModGetInteger¶

ZIResult_enum ziAPIModGetInteger(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIIntegerData *value)

Gets the integer-type value of the specified module parameter path.

This function is used to retrieve module parameter values of type integer. ziAPIModGetDouble, ziApiModGetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to ZIConnection with which the value should be retrieved.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to get the value from.
path	const char *	in	The path of the module parameter to get data from.
value	ZIIntegerData *	out	Pointer to an 64bit integer in which the value should be written

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 Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModGetDouble¶

ZIResult_enum ziAPIModGetDouble(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIDoubleData *value)

Gets the double-type value of the specified module parameter path.

This function is used to retrieve module parameter values of type floating point double. ziAPIModGetInteger, ziApiModGetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to ZIConnection with which the value should be retrieved
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to get the value from.
path	const char *	in	The path of the module parameter to get data from.
value	ZIDoubleData *	out	Pointer to an floating point double in which the value should be written

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 Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModGetString¶

ZIResult_enum ziAPIModGetString(ZIConnection conn, ZIModuleHandle handle, const char *path, char *buffer, unsigned int *length, unsigned int bufferSize)

gets the null-terminated string value of the specified module parameter path

This function is used to retrieve module parameter values of type string. ziAPIModGetInteger, ziApiModGetDouble

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ziConnection with which the value should be retrieved
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to get the value from.
path	const char *	in	The path of the module parameter to get data from.
buffer	char *	out	Pointer to a buffer to store the retrieved null-terminated string
length	unsigned int *	out	Pointer to an unsigned int which after the call, contains the length of the retrieved data (including the null terminator). If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.
bufferSize	unsigned int	in	The length of the passed 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_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModGetStringUnicode¶

ZIResult_enum ziAPIModGetStringUnicode(ZIConnection conn, ZIModuleHandle handle, const char *path, wchar_t *wbuffer, unsigned int *length, unsigned int bufferSize)

Gets the null-terminated string value of the specified module parameter path.

This function is used to retrieve module parameter values of type string. ziAPIModGetInteger, ziApiModGetDouble, ziAPIModGetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ziConnection with which the value should be retrieved
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to get the value from.
path	const char *	in	The path of the module parameter to get data from.
wbuffer	wchar_t *	out	Pointer to a buffer to store the retrieved null-terminated string
length	unsigned int *	out	Pointer to an unsigned int which after the call, contains the length of the retrieved data (including the null terminator). If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.
bufferSize	unsigned int	in	The length of the passed 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_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModGetVector¶

ZIResult_enum ziAPIModGetVector(ZIConnection conn, ZIModuleHandle handle, const char *path, void *buffer, unsigned int *bufferSize, ZIVectorElementType_enum *elementType, unsigned int *numElements)

Gets the vector stored at the specified module parameter path.

This function is used to retrieve module parameter values of type vector. ziAPIModGetInteger, ziApiModGetDouble, ziAPIModGetString

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	Pointer to the ziConnection with which the value should be retrieved.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to get the value from.
path	const char *	in	The path of the module parameter to get data from.
buffer	void *	out	Pointer to a buffer to store the retrieved vector buffer.
bufferSize	unsigned int *	inout	Pointer to an unsigned int indicating the length of the buffer. If the length of the passed buffer is insufficient to store the vector, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.
elementType	ZIVectorElementType_enum *	out	Pointer to store the type of vector elements.
numElements	unsigned int *	out	Pointer to an unsigned int to store the number of elements of the vector. If the length of the passed buffer is insufficient, a zero will be returned.

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 vector's length exceeds the buffer size
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModListNodes¶

ZIResult_enum ziAPIModListNodes(ZIConnection conn, ZIModuleHandle handle, const char *path, char *nodes, uint32_t bufferSize, uint32_t flags)

Returns all child parameter node paths found under the specified parent module parameter path.

This function returns a list of parameter names found at the specified path. The path may contain wildcards. The list is returned in a null-terminated char-buffer, each element delimited by a newline. If the maximum length of the buffer (bufferSize) is not sufficient for all elements, nothing will be returned and the return value will be ZI_ERROR_LENGTH.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle from which the parameter names should be retrieved.
path	const char *	in	Path for which all children will be returned. The path may contain wildcard characters.
nodes	char *	out	Upon call filled with newline-delimited list of the names of all the children found. The string is zero-terminated.
bufferSize	uint32_t	in	The length of the buffer specified as the nodes output parameter.
flags	uint32_t	in	A combination of flags (applied bitwise) as defined in ZIListNodes_enum.

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 bufferSize 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 Data Server.
ZI_WARNING_NOTFOUND If the given path could not be resolved.
ZI_ERROR_TIMEOUT When communication timed out.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModListNodesJSON¶

ZIResult_enum ziAPIModListNodesJSON(ZIConnection conn, ZIModuleHandle handle, const char *path, char *nodes, uint32_t bufferSize, uint32_t flags)

Returns all child parameter node paths found under the specified parent module parameter path.

This function returns a list of node names found at the specified path, formatted as JSON. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents. The list is returned in a null-terminated char-buffer. If the maximum length of the buffer (bufferSize) is not sufficient for all elements, nothing will be returned and the return value will be ZI_ERROR_LENGTH.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle from which the parameter names should be retrieved.
path	const char *	in	Path for which all children will be returned. The path may contain wildcard characters.
nodes	char *	out	Upon call filled with JSON-formatted list of the names of all the children found. The string is zero-terminated.
bufferSize	uint32_t	in	The length of the buffer used for the nodes output parameter.
flags	uint32_t	in	A combination of flags (applied bitwise) as defined in ZIListNodes_enum.

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 bufferSize 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 Data Server.
ZI_WARNING_NOTFOUND If the given path could not be resolved.
ZI_ERROR_TIMEOUT When communication timed out.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSubscribe¶

ZIResult_enum ziAPIModSubscribe(ZIConnection conn, ZIModuleHandle handle, const char *path)

Subscribes to the nodes specified by path, these nodes will be recorded during module execution.

This function subscribes to nodes so that whenever the value of the node changes while the module is executing the new value will be accumulated and then read using ziAPIModRead. 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. ziAPIModUnSubscribe, ziAPIModRead

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module in which the nodes should be subscribed to.
path	const char *	in	Path specifying the nodes to subscribe to, may contain wildcards.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or a general error occurred, enable ziAPI's log for detailed information, see ziAPISetDebugLevel.
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.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModUnSubscribe¶

ZIResult_enum ziAPIModUnSubscribe(ZIConnection conn, ZIModuleHandle handle, const char *path)

Unsubscribes to the nodes specified by path.

This function is the complement to ziAPIModSubscribe. 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. ziAPIModSubscribe, ziAPIModRead

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifyin the module in which the nodes should be unsubscribed from.
path	const char *	in	Path specifying the nodes to unsubscribe from, may contain wildcards.

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.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModExecute¶

ZIResult_enum ziAPIModExecute(ZIConnection conn, ZIModuleHandle handle)

Starts the module's thread and its associated measurement task.

Once the module's parameters has been configured as required via, e.g. ziAPIModSetDoubleData, this function starts the module's thread. This starts the module's main measurement task which will run asynchronously. The thread will run until either the module has completed its task or until ziAPIModFinish is called. Subscription or unsubscription is not possible while the module is executing. The status of the module can be obtained with either ziAPIModFinished or ziAPIModProgress. ziAPIModCreate, ziAPIModProgress, ziAPIModFinish

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModTrigger¶

ZIResult_enum ziAPIModTrigger(ZIConnection conn, ZIModuleHandle handle)

Manually issue a trigger forcing data recording (SW Trigger Module only).

This function is used with the Software Trigger Module in order to manually issue a trigger in order to force recording of data. A burst of subscribed data will be recorded as configured via the SW Trigger's parameters as would a regular trigger event.

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModProgress¶

ZIResult_enum ziAPIModProgress(ZIConnection conn, ZIModuleHandle handle, ZIDoubleData *progress)

Queries the current state of progress of the module's measurement task.

This function can be used to query the module's progress in performing its current measurement task, the progress is returned as a double in [0, 1], where 1 indicates task completion. ziAPIModExecute, ziAPIModFinish, ziAPIModFinished

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
progress	ZIDoubleData *	out	A pointer to ZIDoubleData indicating the current progress of the module.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModFinished¶

ZIResult_enum ziAPIModFinished(ZIConnection conn, ZIModuleHandle handle, ZIIntegerData *finished)

Queries whether the module has finished its measurement task.

This function can be used to query whether the module has finished its task or not. ziAPIModExecute, ziAPIModFinish, ziAPIModProgress

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
finished	ZIIntegerData *	out	A pointer to ZIIntegerData, upon return this will be 0 if the module is still executing or 1 if it has finished executing.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModFinish¶

ZIResult_enum ziAPIModFinish(ZIConnection conn, ZIModuleHandle handle)

Stops the module performing its measurement task.

This functions stops the module performing its associated measurement task and stops recording any data. The task and data recording may be restarted by calling ziAPIModExecute' again. ziAPIModProgress, ziAPIModFinished

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModSave¶

ZIResult_enum ziAPIModSave(ZIConnection conn, ZIModuleHandle handle, const char *fileName)

Saves the currently accumulated data to file.

This function saves the currently accumulated data to a file. The path of the file to save data to is specified via the module's directory parameter. ziAPIModExecute, ziAPIModFinish, ziAPIModFinished

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
fileName	const char *	in	The basename of the file to save the data in.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModRead¶

ZIResult_enum ziAPIModRead(ZIConnection conn, ZIModuleHandle handle, const char *path)

Make the currently accumulated data available for use in the C program.

This function can be used to either read (get) module parameters, in this case a path that addresses the module must be specified, or it can be used to read out the currently accumulated data from subscribed nodes in the module. In either case the actual data must then be accessed by the user using ziAPIModNextNode and ziAPIModGetChunk. ziAPIModGetChunk, ziAPIModNextNode

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
path	const char *	in	The path specifying the module parameter(s) to get, specify NULL to obtain all subscribed data.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModNextNode¶

ZIResult_enum ziAPIModNextNode(ZIConnection conn, ZIModuleHandle handle, char *path, uint32_t bufferSize, ZIValueType_enum *valueType, uint64_t *chunks)

Make the data for the next node available for reading with ziAPIModGetChunk.

After callin ziAPIModRead, subscribed data (or module parameters) may now be read out on a node-by-node and chunk-by-chunk basis. All nodes with data available in the module can be iterated over by using ziAPIModNextNode, then for each node the chunks of data available are read out using ziAPIModGetChunk. Calling this function makes the data from the next node available for read. ziAPIModRead, ziAPIModGetChunk, ziAPIModEventDeallocate

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
path	char *	out	A string specifying the node's path whose data chunk points to.
bufferSize	uint32_t	in	The length of the buffer specified as the path output parameter.
valueType	ZIValueType_enum *	out	The ZIValueType_enum of the node's data.
chunks	uint64_t *	out	The number of chunks of data available for the node.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModGetChunk¶

ZIResult_enum ziAPIModGetChunk(ZIConnection conn, ZIModuleHandle handle, uint64_t chunkIndex, ZIModuleEventPtr *ev)

Get the specified data chunk from the current node.

Data is read out node-by-node and then chunk-by-chunk. This function can be used to obtain specific data chunks from the current node that data is being read from. More precisely, it ppreallocates space for an event structure big enough to hold the node's data at the specified chunk index, updates ZIModuleEventPtr to point to this space and then copies the chunk data to this space.Note, before the very first call to ziAPIModGetChunk, the ZIModuleEventPtr should be initialized to NULL and then left untouched for all subsequent calls (even after calling ziAPIModNextNode to get data from the next node). This is because ziAPIModGetChunk internally manages the required space allocation for the event and then in subsequent calls only reallocates space when it is required. It is optimized to reduce the number of required space reallocations for the event.The ZIModuleEventPtr should be deallocated using ziAPIModEventDeallocate, otherwise the lifetime of the ZIModuleEventPtr is the same as the lifetime of the module. Indeed, the same ZIModuleEventPtr can be used, even for subsequent reads. It is also possible to work with multiple ZIModuleEventPtr so that some pointers can be kept for later processing. ziAPIModRead, ziAPIModNextNode, ziAPIModEventDeallocate

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
chunkIndex	uint64_t	out	The index of the data chunk to update the pointer to.
ev	ZIModuleEventPtr *	out	The module's ZIModuleEventPtr that points to the currently available data chunk.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModEventDeallocate¶

ZIResult_enum ziAPIModEventDeallocate(ZIConnection conn, ZIModuleHandle handle, ZIModuleEventPtr ev)

Deallocate the ZIModuleEventPtr being used by the module.

This function deallocates the ZIModuleEventPtr. Since a module event's allocated space is managed internally by ziAPIModGetChunk, when the user no longer requires the event (all data has been read out) it must be deallocated by the user with this function. ziAPIModGetChunk, ziAPIModRead

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.
ev	ZIModuleEventPtr	in	The ZIModuleEventPtr to deallocate.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ziAPIModClear¶

ZIResult_enum ziAPIModClear(ZIConnection conn, ZIModuleHandle handle)

Terminates the module's thread and destroys the module.

This function terminates the module's thread, releases memory and resources. After calling ziAPIModClear the module's handle may not be used any more. A new instance of the module must be initialized if required. This command is especially important if modules are created repetitively inside a while or for loop, in order to prevent excessive memory and resource consumption. ziAPIModExecute, ziAPIModFinish

Parameters

Name	Type	Direction	Description
conn	ZIConnection	in	The ZIConnection from which the module was created.
handle	ZIModuleHandle	in	The ZIModuleHandle specifying the module to execute.

Returns

ZI_INFO_SUCCESS On success.
ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.