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