C API General Functions¶
Connect\Disconnect¶
ziAPIInit¶
ZIResult_enum ziAPIInit(ZIConnection *conn)
Initializes a ZIConnection structure.
This function initializes the structure so that it is ready to connect to Data Server. It allocates memory and sets up the infrastructure needed. See Connection for an example ziAPIDestroy, ziAPIConnect, ziAPIDisconnect
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection * | out | Pointer to ZIConnection that is to be initialized |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_MALLOC on memory allocation failure
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIDestroy¶
ZIResult_enum ziAPIDestroy(ZIConnection conn)
Destroys a ZIConnection structure.
This function frees all memory that has been allocated by ziAPIInit. If it is called with an uninitialized ZIConnection struct it may result in segmentation faults as well when it is called with a struct for which ZIAPIDestroy already has been called. See Connection for an example ziAPIInit, ziAPIConnect, ziAPIDisconnect
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to ZIConnection struct that has to be destroyed |
Returns
- ZI_INFO_SUCCESS
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIConnect¶
ZIResult_enum ziAPIConnect(ZIConnection conn, const char *hostname, uint16_t port)
Connects the ZIConnection to Data Server.
Connects to Data Server using a ZIConnection and prepares for data exchange. For most cases it is enough to just give a reference to the connection and give NULL for hostname and 0 for the port, so it connects to localhost on the default port. See Connection for an example ziAPIDisconnect, ziAPIInit, ziAPIDestroy
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to ZIConnection with which the connection should be established |
| hostname | const char * | in | Name of the Host to which it should be connected, if NULL "localhost" will be used as default |
| port | uint16_t | in | The Number of the port to connect to. If 0, default port of the local Data Server will be used (8005) |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the Data Server didn't return the correct answer
- ZI_ERROR_TIMEOUT when initial communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIConnectEx¶
ZIResult_enum ziAPIConnectEx(ZIConnection conn, const char *hostname, uint16_t port, ZIAPIVersion_enum apiLevel, const char *implementation)
Connects to Data Server and enables extended ziAPI.
With apiLevel=ZI_API_VERSION_1 and implementation=NULL, this call is equivalent to plain ziAPIConnect. With other version and implementation values enables corresponding ziAPI extension and connection using different implementation. See Connection for an example ziAPIConnect, ziAPIDisconnect, ziAPIInit, ziAPIDestroy, ziAPIGetConnectionVersion
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection with which the connection should be established |
| hostname | const char * | in | Name of the host to which it should be connected, if NULL "localhost" will be used as default |
| port | uint16_t | in | The number of the port to connect to. If 0 the port of the local Data Server will be used |
| apiLevel | ZIAPIVersion_enum | in | Specifies the ziAPI compatibility level to use for this connection (1 or 4). |
| implementation | const char * | in | Specifies implementation to use for a connection. NULL selects the default implementation (recommended). |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION when the Data Server didn't return the correct answer or requested implementation is not found or doesn't support requested ziAPI level
- ZI_ERROR_TIMEOUT when initial communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIDisconnect¶
ZIResult_enum ziAPIDisconnect(ZIConnection conn)
Disconnects an established connection.
Disconnects from Data Server. If the connection has not been established and the function is called it returns without doing anything. See Connection for an example ziAPIConnect, ziAPIInit, ziAPIDestroy
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to ZIConnection to be disconnected |
Returns
- ZI_INFO_SUCCESS
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIConnectDevice¶
ZIResult_enum ziAPIConnectDevice(ZIConnection conn, const char *deviceSerial, const char *deviceInterface, const char *interfaceParams)
Connect a device to the server.
This function connects a device with deviceSerial via the specified deviceInterface for use with the server. ziAPIDisconnectDevice, ziAPIConnect, ziAPIDisconnect, ziAPIInit
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection with which the connection should be established |
| deviceSerial | const char * | in | The serial of the device to connect to, e.g., dev1000 |
| deviceInterface | const char * | in | The interface to use for the connection, e.g., USB |
| interfaceParams | const char * | in | Parameters for interface configuration (currently reserved for future use, NULL may be specified). |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIDisconnectDevice¶
ZIResult_enum ziAPIDisconnectDevice(ZIConnection conn, const char *deviceSerial)
Disconnect a device from the server.
This function disconnects a device specified by deviceSerial from the server. ziAPIConnectDevice, ziAPIConnect, ziAPIDisconnect, ziAPIInit
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection with which the connection should be established |
| deviceSerial | const char * | in | The serial of the device to connect to, e.g., dev1000 |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Node Info¶
ziAPIListNodes¶
ZIResult_enum ziAPIListNodes(ZIConnection conn, const char *path, char *nodes, uint32_t bufferSize, uint32_t flags)
Returns all child nodes found at the specified path.
This function returns a list of node names found at the specified path. 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, 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 ZIResult_enum::ZI_LENGTH. See Tree Listing for an exampleziAPIUpdate
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection for which the node 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 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
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIListNodesJSON¶
ZIResult_enum ziAPIListNodesJSON(ZIConnection conn, const char *path, char *nodes, uint32_t bufferSize, uint32_t flags)
Returns all child nodes found at the specified 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 ZIResult_enum::ZI_LENGTH. See Tree Listing for an exampleziAPIUpdate
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection for which the node 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
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Error Handling¶
ziAPIGetError¶
ZIResult_enum ziAPIGetError(ZIResult_enum result, char **buffer, int *base)
Returns a description and the severity for a ZIResult_enum.
This function returns a static char pointer to a description string for the given ZIResult_enum error code. It also provides a parameter returning the severity (info, warning, error). If the given error code does not exist a description for an unknown error and the base for an error will be returned. If a description or the base is not needed NULL may be passed. In general, it's recommended to use ziAPIGetLastError instead to get detailed error messages.
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| result | ZIResult_enum | in | A ZIResult_enum for which the description or base will be returned |
| buffer | char ** | out | A pointer to a char array to return the description. May be NULL if no description is needed. |
| base | int * | out | The severity for the provided Status parameter:
|
Returns
- ZI_INFO_SUCCESS Upon success.
ziAPIGetLastError¶
ZIResult_enum ziAPIGetLastError(ZIConnection conn, char *buffer, uint32_t bufferSize)
Returns the message from the last error that occurred.
This function can be used to obtain the error message from the last error that occurred associated with the provided ZIConnection. If the last ziAPI call is successful, then the last error message returned by ziAPIGetError is empty. Only ziAPI function calls that take ZIConnection as an input argument influence the message returned by ziAPIGetLastError, if they do not take ZIConnection as an input argument the last error message will neither be reset to be empty or set to an error message (in the case of the error). There are some exceptions to this rule, ziAPIGetLastError can also not be used with ziAPIInit, ziAPIConnect, ziAPIConnectEx and ziAPIDestroy. Note, a call to ziAPIGetLastError will also reset the last error message to empty if its call was successful. Since the buffer is left unchanged in the case of an error occurring in the call to ziAPIGetLastError it is safest to initialize the buffer with a known value, for example, "ziAPIGetLastError was not successful".
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | The ZIConnection from which to get the error message. |
| buffer | char * | out | A pointer to a char array to return the message. |
| bufferSize | uint32_t | in | The length of the provided buffer. |
Returns
- ZI_INFO_SUCCESS Upon success.
- ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred. In this case the provided buffer is left unchanged.
- ZI_ERROR_LENGTH If the message's length exceeds the provided bufferSize, the message is truncated and written to buffer.
Info¶
ziAPIGetConnectionAPILevel¶
ZIResult_enum ziAPIGetConnectionAPILevel(ZIConnection conn, ZIAPIVersion_enum *apiLevel)
Returns ziAPI level used for the connection conn.
ziAPIConnectEx, ziAPIGetVersion, ziAPIGetCommitHash, ziAPIGetRevision
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to ZIConnection |
| apiLevel | ZIAPIVersion_enum * | out | Pointer to preallocated ZIAPIVersion_enum, receiving the ziAPI level |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_CONNECTION if level can not be determined due to conn is not connected
ziAPIGetCommitHash¶
ZIResult_enum ziAPIGetCommitHash(const char **commitHash)
Retrieves the exact commit hash key of ziAPI.
Sets the passed pointer to point to the null-terminated commit hash string of ziAPI. ziAPIConnectEx, ziAPIGetRevision, ziAPIGetVersion, ziAPIGetConnectionAPILevel
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| commitHash | const char ** | in | Pointer to const char pointer. |
Returns
- ZI_INFO_SUCCESS
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIGetRevision¶
ZIResult_enum ziAPIGetRevision(uint32_t *revision)
Retrieves the version and build number of ziAPI.
Sets an unsigned int with the version and build number of the ziAPI you are using.The number is a packed representation of YY.MM.BUILD as a 32-bit unsigned integer: (YY << 24) | (MM << 16) | BUILD.Note: prior to LabOne 19.10, the packed representation did not contain YY.MM. ziAPIConnectEx, ziAPIGetVersion, ziAPIGetCommitHash, ziAPIGetConnectionAPILevel
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| revision | uint32_t * | in | Pointer to an unsigned int to fill up with the packed version number. |
Returns
- ZI_INFO_SUCCESS
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Logging¶
ziAPISetDebugLevel¶
void ziAPISetDebugLevel(int32_t severity)
Enable ziAPI's log and set the severity level of entries to be included in the log.
Calling this function enables ziAPI's log at the specified severity level. On Windows the logs can be found by navigating to the Zurich Instruments "Logs" folder entry in the Windows Start Menu: Programs -> Zurich Instruments -> LabOne Servers -> Logs. This will open an Explorer window displaying folders containing log files from various LabOne components, in particular, theziAPILog folder contains logs from ziAPI. On Linux, the logs can be found at "/tmp/ziAPILog_USERNAME", where "USERNAME" is the same as the output of the "whoami" command. ziAPIWriteDebugLog
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| severity | int32_t | in | An integer specifying the log's severity level:
|
ziAPIWriteDebugLog¶
void ziAPIWriteDebugLog(int32_t severity, const char *message)
Write a message to ziAPI's log with the specified severity.
This function may be used to write a message to ziAPI's log from client code to assist with debugging. Note, logging must be first enabled using ziAPISetDebugLevel. ziAPISetDebugLevel
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| severity | int32_t | in | An integer specifying the severity of the message to write in the log:
|
| message | const char * | in | A character array comprising of the message to be written. |
Synchronization¶
ziAPISync¶
ZIResult_enum ziAPISync(ZIConnection conn)
Synchronizes the session by dropping all pending data.
This function drops any data that is pending for transfer. Any data (including poll data) retrieved afterwards is guaranteed to be produced not earlier than the call to ziAPISync. This ensures in particular that any settings made prior to the call to ziAPISync have been propagated to the device, and the data retrieved afterwards is produced with the new settings already set to the hardware. Note, however, that this does not include any required settling time.
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| conn | ZIConnection | in | Pointer to the ZIConnection that is to be synchronized |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_TIMEOUT when communication timed out
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
Deprecated¶
ziAPIListImplementations¶
ZIResult_enum ziAPIListImplementations(char *implementations, uint32_t bufferSize)
Returns the list of supported implementations. Deprecated.
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| implementations | char * | out | Pointer to a buffer receiving a newline-delimited list of the names of all the supported ziAPI implementations. The string is zero-terminated. |
| bufferSize | uint32_t | in | The size of the buffer assigned to the implementations parameter |
Returns
- ZI_INFO_SUCCESS on success
- ZI_ERROR_LENGTH if the length of the char-buffer given by MaxLen is too small for all elements
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ziAPIGetVersion¶
ZIResult_enum ziAPIGetVersion(const char **version)
Retrieves the release version of ziAPI.
Sets the passed pointer to point to the null-terminated release version string of ziAPI. ziAPIConnectEx, ziAPIGetRevision, ziAPIGetCommitHash, ziAPIGetConnectionAPILevel
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| version | const char ** | in | Pointer to const char pointer. |
Returns
- ZI_INFO_SUCCESS
- Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.
ReadMEMFile¶
ZIResult_enum ReadMEMFile(const char *filename, char *buffer, int32_t bufferSize, int32_t *bytesUsed)
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| filename | const char * | ||
| buffer | char * | ||
| bufferSize | int32_t | ||
| bytesUsed | int32_t * |
ziAPISecondsTimeStamp¶
double ziAPISecondsTimeStamp(ziTimeStampType TS)
Deprecated: timestamps should instead be converted to seconds by dividing by the instrument's "clockbase". This is available as an leaf under the instrument's root "device" branch in the node hierarchy, e.g., /dev1000/clockbase.
Parameters
| Name | Type | Direction | Description |
|---|---|---|---|
| TS | ziTimeStampType | in | the timestamp to convert to seconds |
Returns The timestamp in seconds as a double