Skip to content

.Net API General Functions

Connect\Disconnect

ziDotNET

ziDotNET()

~ziDotNET

~ziDotNET()

init

void init()

DEPRECATED! Initializes the connection Parameters with the default Parameters.

WARNING: Only applies for the HF2!!!Uses the default parameters "localhost", 8005, 1 to initiate the connection Parameters.

init

void init(String^ hostString, uint16_t portValue, ZIAPIVersion_enum apiLevel)

Initializes the connection Parameters.

It is needed to callconnect in order to initiate the connection to the specified data server.

Parameters

Name Type Direction Description
hostString String^ in Host address of the LabOne data server (e.g. "localhost").
portValue uint16_t in Port number of the server. By default the Labone data server listens on port 8004 (8005 for HF2)
apiLevel ZIAPIVersion_enum in API level number. It is recommended to use the latest level 6.

connect

void connect()

Connect the ziDotNET instance to the specified data server.

disconnect

void disconnect()

Disconnect the ziDotNET instance to the specified data server.

terminate

bool terminate()

Disconnect the ziDotNET instance to the specified data server without any error handling.

connectDevice

void connectDevice(String^ deviceSerial, String^ deviceInterface, String^ interfaceParams)

Connect with the data server to a specified device.

The device must be visible to the server. If the device is already connected the call will be ignored. The function will block until the device is connected and the device is ready to use.

Parameters

Name Type Direction Description
deviceSerial String^ in Device serial string.
deviceInterface String^ in Device interface.
interfaceParams String^ in Optional interface parameters string. Can be an empty string.

disconnectDevice

void disconnectDevice(String^ deviceSerial)

Disconnect a device from the data server.

This function will return immediately. The disconnection of the device may not yet be finished.

Parameters

Name Type Direction Description
deviceSerial String^ in Device serial string of device to disconnect.

Node Info

listNodes

List<String^> listNodes(String^ path, ZIListNodes_enum flags)

This function returns a list of node names found at the specified path.

Parameters

Name Type Direction Description
path String^ in Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.
flags ZIListNodes_enum in Flags specifying how the selected nodes are listed (seeZIListNodes_enum)

Returns List of node names.

listNodes

List<String^> listNodes(String^ path, ZIListNodes_enum flags)

This function returns a list of node names found at the specified path.

Parameters

Name Type Direction Description
path String^ in Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.
flags ZIListNodes_enum in Flags specifying how the selected nodes are listed (seeZIListNodes_enum)

Returns List of node names.

listNodesJSON

String listNodesJSON(String^ path, ZIListNodes_enum flags)

Returns a list of nodes with description found at the specified path.

HF2 devices do not support this functionality.

Parameters

Name Type Direction Description
path String^ in Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.
flags ZIListNodes_enum in Flags specifying how the selected nodes are listed (seeZIListNodes_enum)

Returns JSON formatted string (nodepath:information).

listNodesJSON

String listNodesJSON(String^ path, ZIListNodes_enum flags)

Returns a list of nodes with description found at the specified path.

Parameters

Name Type Direction Description
path String^ in Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.
flags ZIListNodes_enum in Flags specifying how the selected nodes are listed (seeZIListNodes_enum)

Returns JSON formatted string (nodepath:information).

Error Handling

getLastError

String getLastError()

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 Note, a call to getLastError will also reset the last error message to empty if its call was successful.

Returns Message from the last error.

Info

getConnectionAPILevel

ZIAPIVersion_enum getConnectionAPILevel()

Get the ziAPI level used for the active connection.

version

String version()

Retrieves release version of the ziDotNet API.

Returns release version of the ziDotNet API.

commitHash

String commitHash()

Retrieves the exact commit hash key of the ziDotNet API.

Returns Commit hash string of the ziDotNet API.

revision

int64_t revision()

Retrieves the version and build number of the ziDotNet API.

Returns 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.

Returns Build Version of the ziDotNet API.

Logging

setDebugLevel

void setDebugLevel(int32_t debugLevel)

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.

Parameters

Name Type Direction Description
debugLevel int32_t in An integer specifying the log's severity level:
  • trace: 0,
  • debug: 1,
  • info: 2,
  • status: 3,
  • warning: 4,
  • error: 5,
  • fatal: 6,

writeDebugLog

void writeDebugLog(int32_t debugLevel, String^ 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 setDebugLevel

Parameters

Name Type Direction Description
debugLevel int32_t in An integer specifying the severity of the message to write in the log:
  • trace: 0,
  • debug: 1,
  • info: 2,
  • status: 3,
  • warning: 4,
  • error: 5,
  • fatal: 6,
message String^ in Message to be written.

Synchronization

sync

void sync()

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.