Source ziAPI.h#

   1// Copyright [2016] Zurich Instruments AG
   2
   3// clang-format off
   4
   5/**
   6@file  ziAPI.h
   7@brief Header File for the LabOne C/C++ API
   8
   9ziAPI provides all functionality to establish a connection with the Data Server and to communicate with it. It has
  10functions for setting and getting parameters in a single call as well as an event-framework with which the user may
  11subscribe the parameter tree and receive the events which occur when values change.
  12- All functions do not check passed pointers if they're NULL pointers. In that case a segmentation fault will occur.
  13- The ZIConnection is not thread-safe. One connection can only be used in one thread. If you want to use the ziAPI
  14  in a multi-threaded program you will have to use one ZIConnection for each thread that is communicating or implement
  15  a mutual exclusion.
  16- The Data Server is able to handle connections from threads simultaneously. The Data Server takes over
  17  the synchronization.
  18*/
  19
  20#ifndef ZI_API_H
  21#define ZI_API_H
  22
  23// Portable fixed-width integer types.
  24// In case <stdint.h> is not available on your system, define ZI_CUSTOM_STDINT_H and set it to the
  25// name of the custom (or specific to your system) implementation.
  26#ifdef ZI_CUSTOM_STDINT_H
  27#include ZI_CUSTOM_STDINT_H
  28#elif defined(_MSC_VER) && _MSC_VER < 1600
  29// <stdint.h> is not available on MSVC++ below 2010 (10.0)
  30typedef   signed __int8    int8_t;
  31typedef   signed __int16   int16_t;
  32typedef   signed __int32   int32_t;
  33typedef   signed __int64   int64_t;
  34typedef unsigned __int8   uint8_t;
  35typedef unsigned __int16  uint16_t;
  36typedef unsigned __int32  uint32_t;
  37typedef unsigned __int64  uint64_t;
  38#else
  39#include <stdint.h>
  40#endif
  41
  42#include <stddef.h>
  43
  44#ifdef _MSC_VER
  45  #if defined(ZI_API_DLL_EXPORTING)
  46    #define ZI_EXPORT __declspec(dllexport)
  47  #elif defined(ZI_API_INTERNAL)
  48    #define ZI_EXPORT
  49  #else
  50    #define ZI_EXPORT __declspec(dllimport)
  51  #endif
  52#else
  53  #if __GNUC__ >= 4
  54    #if defined(ZI_API_DLL_EXPORTING)
  55      #define ZI_EXPORT __attribute__ ((visibility ("default")))
  56    #elif defined(ZI_API_INTERNAL)
  57      #define ZI_EXPORT
  58    #else
  59      #define ZI_EXPORT __attribute__ ((visibility ("default")))
  60    #endif
  61  #else
  62    #define ZI_EXPORT
  63  #endif
  64#endif
  65
  66#ifdef __cplusplus
  67extern "C" {
  68#endif
  69
  70/// The maximum length that has to be used for passing paths to functions (including terminating zero)
  71#define MAX_PATH_LEN      256
  72/// The maximum size of an event's data block
  73#define MAX_EVENT_SIZE    0x400000
  74/// The maximum length of the node name (in tree change event)
  75#define MAX_NAME_LEN      32
  76
  77// deprecated symbols
  78// ******************
  79#ifdef __GNUC__
  80  #define DEPRECATED(decl) decl __attribute__ ((deprecated))
  81  #define DEPRECATED_ENUM(decl) __attribute__ ((deprecated)) decl
  82#elif defined(_MSC_VER)
  83  #define DEPRECATED(decl) __declspec(deprecated) decl
  84  #define DEPRECATED_ENUM(decl) decl
  85#else
  86  #pragma message("WARNING: You need to implement DEPRECATED for this compiler")
  87  #define DEPRECATED(decl) decl
  88  #define DEPRECATED_ENUM(decl) decl
  89#endif
  90
  91// We don't want to get the deprecated warnings for the ziAPI.h itself
  92#ifdef __GNUC__
  93#if __GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 6
  94// Only supported by GCC >= 4.6
  95#pragma GCC diagnostic push
  96#endif
  97#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  98#elif defined(_MSC_VER)
  99// Visual C++ specific
 100#pragma warning(push)
 101// 4996 - declared deprecated
 102#pragma warning(disable:4996)
 103#endif
 104
 105/// Defines return value for all ziAPI functions. Divided into 3 regions: info, warning and error.
 106enum ZIResult_enum {
 107  // *********** Infos
 108  ZI_INFO_BASE = 0x0000,
 109  /// Success (no error)
 110  ZI_INFO_SUCCESS = 0x0000,
 111
 112  ZI_INFO_MAX,
 113
 114  // *********** Warnings
 115  ZI_WARNING_BASE = 0x4000,
 116  /// Warning (general);
 117  ZI_WARNING_GENERAL = 0x4000,
 118
 119  /// Value or Node not found
 120  ZI_WARNING_NOTFOUND = 0x4003,
 121
 122  /// Unknown keyword
 123  ZI_WARNING_INVALID_KEYWORD = 0x4005,
 124
 125  ZI_WARNING_MAX,
 126
 127  // *********** Errors
 128  ZI_ERROR_BASE = 0x8000,
 129  /// Error (general)
 130  ZI_ERROR_GENERAL = 0x8000,
 131
 132  /// Memory allocation failed
 133  ZI_ERROR_MALLOC = 0x8002,
 134
 135  /// Connection invalid
 136  ZI_ERROR_CONNECTION = 0x800c,
 137  /// Command timed out
 138  ZI_ERROR_TIMEOUT = 0x800d,
 139  /// Command internally failed
 140  ZI_ERROR_COMMAND = 0x800e,
 141  /// Command failed in server
 142  ZI_ERROR_SERVER_INTERNAL = 0x800f,
 143
 144  /// Provided Buffer length is too small
 145  ZI_ERROR_LENGTH = 0x8010,
 146
 147  /// Can't open file or read from it
 148  ZI_ERROR_FILE = 0x8011,
 149
 150  /// There is already a similar entry
 151  ZI_ERROR_DUPLICATE = 0x8012,
 152
 153  /// Attempt to set a read-only node
 154  ZI_ERROR_READONLY = 0x8013,
 155
 156  /// Device is not visible to the server
 157  ZI_ERROR_DEVICE_NOT_VISIBLE = 0x8014,
 158  /// Device is already connected by a different server
 159  ZI_ERROR_DEVICE_IN_USE = 0x8015,
 160  /// Device does currently not support the specified interface
 161  ZI_ERROR_DEVICE_INTERFACE = 0x8016,
 162  /// Device connection timeout
 163  ZI_ERROR_DEVICE_CONNECTION_TIMEOUT = 0x8017,
 164  /// Device already connected over a different Interface
 165  ZI_ERROR_DEVICE_DIFFERENT_INTERFACE = 0x8018,
 166  /// Device needs FW upgrade
 167  ZI_ERROR_DEVICE_NEEDS_FW_UPGRADE = 0x8019,
 168  /// Trying to get data from a poll event with wrong target data type.
 169  ZI_ERROR_ZIEVENT_DATATYPE_MISMATCH = 0x801A,
 170  /// Device not found
 171  ZI_ERROR_DEVICE_NOT_FOUND = 0x801B,
 172
 173  /// Provided arguments are not supported for the command
 174  ZI_ERROR_NOT_SUPPORTED = 0x801C,
 175
 176  /// Connection invalid
 177  ZI_ERROR_TOO_MANY_CONNECTIONS = 0x801D,
 178
 179  /// Command not supported on HF2
 180  ZI_ERROR_NOT_ON_HF2 = 0x801E,
 181
 182  // Invalid argument received.
 183  ZI_ERROR_INVALID_ARGUMENT = 0x801F,
 184
 185  /// Errors reported by device
 186  ZI_ERROR_COM_NACK_BASE = 0x9000,
 187  ZI_ERROR_COM_NACK_NO_ERROR = 0x9000,
 188  ZI_ERROR_COM_NACK_INVALID_AP_ADDRESS,
 189  ZI_ERROR_COM_NACK_INVALID_AP_OFFSET,
 190  ZI_ERROR_COM_NACK_INVALID_AP_LENGTH,
 191  ZI_ERROR_COM_NACK_READONLY_AP,
 192  ZI_ERROR_COM_NACK_NOT_SERVED_AP,
 193  ZI_ERROR_COM_NACK_NOT_INDEXED_AP,
 194  ZI_ERROR_COM_NACK_INVALID_VECT_LEN,
 195  ZI_ERROR_COM_NACK_INVALID_VECT_FRAME,
 196  ZI_ERROR_COM_NACK_INVALID_VECT_OFFSET,
 197  ZI_ERROR_COM_NACK_INVALID_VECT_EXTRA,
 198  ZI_ERROR_COM_NACK_INVALID_VECT_SEQUENCE,
 199  ZI_ERROR_COM_NACK_INVALID_VECT_IDX_OFFSET,
 200  ZI_ERROR_COM_NACK_INVALID_VECT_TYPE,
 201  ZI_ERROR_COM_NACK_INVALID_VECT_DATA_LEN,
 202  ZI_ERROR_COM_NACK_INVALID_VECT_EXTRA_LEN,
 203  ZI_ERROR_COM_NACK_TIMEOUT,
 204  ZI_ERROR_COM_NACK_RESOURCE_INACTIVE,
 205  ZI_ERROR_COM_NACK_RESOURCE_BUSY,
 206  ZI_ERROR_COM_NACK_EXECUTION_ERROR,
 207  ZI_ERROR_COM_NACK_VECTOR_QUEUE_FULL,
 208
 209  /// SW-generated extension of device errors
 210  ZI_ERROR_COM_NACK_INTERNAL_BASE = 0x9100,
 211  ZI_ERROR_COM_NACK_INTERNAL_NO_PAYLOAD,
 212  ZI_ERROR_COM_NACK_INTERNAL_TOO_MANY_PENDING,
 213
 214  ZI_ERROR_MAX
 215
 216  /// @cond deprecated
 217  // **********
 218  ,
 219  /// FIFO Underrun
 220  ZI_WARNING_UNDERRUN = 0x4001,
 221  /// FIFO Overflow
 222  ZI_WARNING_OVERFLOW = 0x4002,
 223  /// Async command executed in sync mode (will be no async reply)
 224  ZI_WARNING_NO_ASYNC = 0x4004,
 225
 226  /// USB Communication failed
 227  ZI_ERROR_USB = 0x8001,
 228
 229  /// Unable to initialize mutex
 230  ZI_ERROR_MUTEX_INIT = 0x8003,
 231  /// Unable to destroy mutex
 232  ZI_ERROR_MUTEX_DESTROY = 0x8004,
 233  /// Unable to lock mutex
 234  ZI_ERROR_MUTEX_LOCK = 0x8005,
 235  /// Unable to unlock mutex
 236  ZI_ERROR_MUTEX_UNLOCK = 0x8006,
 237
 238  /// Unable to start thread
 239  ZI_ERROR_THREAD_START = 0x8007,
 240  /// Unable to join thread
 241  ZI_ERROR_THREAD_JOIN = 0x8008,
 242
 243  /// Can't initialize socket
 244  ZI_ERROR_SOCKET_INIT = 0x8009,
 245  /// Unable to connect socket
 246  ZI_ERROR_SOCKET_CONNECT = 0x800a,
 247  /// Hostname not found
 248  ZI_ERROR_HOSTNAME = 0x800b
 249
 250#ifdef _MSC_VER
 251  ,
 252  // Success (no error)
 253  ZI_SUCCESS = 0x0000,
 254
 255  ZI_MAX_INFO,
 256
 257  // Warning (general)
 258  ZI_WARNING = 0x4000,
 259
 260  // FIFO Underrun
 261  ZI_UNDERRUN,
 262  // FIFO Overflow
 263  ZI_OVERFLOW,
 264
 265  // Value or Node not found
 266  ZI_NOTFOUND,
 267
 268  ZI_MAX_WARNING,
 269
 270  // Error (general)
 271  ZI_ERROR = 0x8000,
 272
 273  // USB Communication failed
 274  ZI_USB,
 275
 276  // Memory allocation failed
 277  ZI_MALLOC,
 278
 279  // Unable to initialize mutex
 280  ZI_MUTEX_INIT,
 281  // Unable to destroy mutex
 282  ZI_MUTEX_DESTROY,
 283  // Unable to lock mutex
 284  ZI_MUTEX_LOCK,
 285  // Unable to unlock mutex
 286  ZI_MUTEX_UNLOCK,
 287
 288  // Unable to start thread
 289  ZI_THREAD_START,
 290  // Unable to join thread
 291  ZI_THREAD_JOIN,
 292
 293  // Can't initialize socket
 294  ZI_SOCKET_INIT,
 295  // Unable to connect socket
 296  ZI_SOCKET_CONNECT,
 297  // Hostname not found
 298  ZI_HOSTNAME,
 299
 300  // Connection invalid
 301  ZI_CONNECTION,
 302  // Command timed out
 303  ZI_TIMEOUT,
 304  // Command internally failed
 305  ZI_COMMAND,
 306  // Command failed in server
 307  ZI_SERVER_INTERNAL,
 308
 309  // Provided Buffer length doesn't reach
 310  ZI_LENGTH,
 311
 312  // Can't open file or read from it
 313  ZI_FILE,
 314
 315  // There is already a similar entry
 316  ZI_DUPLICATE,
 317
 318  // Attempt to set a read-only node
 319  ZI_READONLY,
 320
 321  ZI_MAX_ERROR,
 322#endif
 323  /// @endcond
 324};
 325
 326#ifndef __cplusplus
 327typedef enum ZIResult_enum ZIResult_enum;
 328#endif
 329
 330#ifdef _MSC_VER
 331#pragma deprecated(ZI_SUCCESS)
 332#pragma deprecated(ZI_MAX_INFO)
 333#pragma deprecated(ZI_WARNING)
 334#pragma deprecated(ZI_UNDERRUN)
 335#pragma deprecated(ZI_OVERFLOW)
 336#pragma deprecated(ZI_NOTFOUND)
 337#pragma deprecated(ZI_MAX_WARNING)
 338#pragma deprecated(ZI_ERROR)
 339#pragma deprecated(ZI_USB)
 340#pragma deprecated(ZI_MALLOC)
 341#pragma deprecated(ZI_MUTEX_INIT)
 342#pragma deprecated(ZI_MUTEX_DESTROY)
 343#pragma deprecated(ZI_MUTEX_LOCK)
 344#pragma deprecated(ZI_MUTEX_UNLOCK)
 345#pragma deprecated(ZI_THREAD_START)
 346#pragma deprecated(ZI_THREAD_JOIN)
 347#pragma deprecated(ZI_SOCKET_INIT)
 348#pragma deprecated(ZI_SOCKET_CONNECT)
 349#pragma deprecated(ZI_HOSTNAME)
 350#pragma deprecated(ZI_CONNECTION)
 351#pragma deprecated(ZI_TIMEOUT)
 352#pragma deprecated(ZI_COMMAND)
 353#pragma deprecated(ZI_SERVER_INTERNAL)
 354#pragma deprecated(ZI_LENGTH)
 355#pragma deprecated(ZI_FILE)
 356#pragma deprecated(ZI_DUPLICATE)
 357#pragma deprecated(ZI_READONLY)
 358#pragma deprecated(ZI_MAX_ERROR)
 359#else
 360
 361#ifdef __cplusplus
 362#define ZIResult_enum_cast(val) ZIResult_enum(val)
 363#else
 364#define ZIResult_enum_cast(val) val
 365#endif
 366
 367DEPRECATED_ENUM(static const ZIResult_enum ZI_SUCCESS         = ZIResult_enum_cast(0x0000));
 368DEPRECATED_ENUM(static const ZIResult_enum ZI_MAX_INFO        = ZIResult_enum_cast(0x0001));
 369DEPRECATED_ENUM(static const ZIResult_enum ZI_WARNING         = ZIResult_enum_cast(0x4000));
 370DEPRECATED_ENUM(static const ZIResult_enum ZI_UNDERRUN        = ZIResult_enum_cast(0x4001));
 371DEPRECATED_ENUM(static const ZIResult_enum ZI_OVERFLOW        = ZIResult_enum_cast(0x4002));
 372DEPRECATED_ENUM(static const ZIResult_enum ZI_NOTFOUND        = ZIResult_enum_cast(0x4003));
 373DEPRECATED_ENUM(static const ZIResult_enum ZI_MAX_WARNING     = ZIResult_enum_cast(0x4004));
 374DEPRECATED_ENUM(static const ZIResult_enum ZI_ERROR           = ZIResult_enum_cast(0x8000));
 375DEPRECATED_ENUM(static const ZIResult_enum ZI_USB             = ZIResult_enum_cast(0x8001));
 376DEPRECATED_ENUM(static const ZIResult_enum ZI_MALLOC          = ZIResult_enum_cast(0x8002));
 377DEPRECATED_ENUM(static const ZIResult_enum ZI_MUTEX_INIT      = ZIResult_enum_cast(0x8003));
 378DEPRECATED_ENUM(static const ZIResult_enum ZI_MUTEX_DESTROY   = ZIResult_enum_cast(0x8004));
 379DEPRECATED_ENUM(static const ZIResult_enum ZI_MUTEX_LOCK      = ZIResult_enum_cast(0x8005));
 380DEPRECATED_ENUM(static const ZIResult_enum ZI_MUTEX_UNLOCK    = ZIResult_enum_cast(0x8006));
 381DEPRECATED_ENUM(static const ZIResult_enum ZI_THREAD_START    = ZIResult_enum_cast(0x8007));
 382DEPRECATED_ENUM(static const ZIResult_enum ZI_THREAD_JOIN     = ZIResult_enum_cast(0x8008));
 383DEPRECATED_ENUM(static const ZIResult_enum ZI_SOCKET_INIT     = ZIResult_enum_cast(0x8009));
 384DEPRECATED_ENUM(static const ZIResult_enum ZI_SOCKET_CONNECT  = ZIResult_enum_cast(0x800a));
 385DEPRECATED_ENUM(static const ZIResult_enum ZI_HOSTNAME        = ZIResult_enum_cast(0x800b));
 386DEPRECATED_ENUM(static const ZIResult_enum ZI_CONNECTION      = ZIResult_enum_cast(0x800c));
 387DEPRECATED_ENUM(static const ZIResult_enum ZI_TIMEOUT         = ZIResult_enum_cast(0x800d));
 388DEPRECATED_ENUM(static const ZIResult_enum ZI_COMMAND         = ZIResult_enum_cast(0x800e));
 389DEPRECATED_ENUM(static const ZIResult_enum ZI_SERVER_INTERNAL = ZIResult_enum_cast(0x800f));
 390DEPRECATED_ENUM(static const ZIResult_enum ZI_LENGTH          = ZIResult_enum_cast(0x8010));
 391DEPRECATED_ENUM(static const ZIResult_enum ZI_FILE            = ZIResult_enum_cast(0x8011));
 392DEPRECATED_ENUM(static const ZIResult_enum ZI_DUPLICATE       = ZIResult_enum_cast(0x8012));
 393DEPRECATED_ENUM(static const ZIResult_enum ZI_READONLY        = ZIResult_enum_cast(0x8013));
 394DEPRECATED_ENUM(static const ZIResult_enum ZI_MAX_ERROR       = ZIResult_enum_cast(0x8014));
 395#endif
 396
 397/// Enumerates all types that data in a ZIEvent may have
 398enum ZIValueType_enum {
 399  /// No data type, event is invalid.
 400  ZI_VALUE_TYPE_NONE = 0,
 401
 402  /// ZIDoubleData type. Use the ZIEvent.value.doubleData pointer to read the data of the event.
 403  ZI_VALUE_TYPE_DOUBLE_DATA = 1,
 404
 405  /// ZIIntegerData type. Use the ZIEvent.value.integerData pointer to read the data of the event.
 406  ZI_VALUE_TYPE_INTEGER_DATA = 2,
 407
 408  /// ZIDemodSample type. Use the ZIEvent.value.demodSample pointer to read the data of the event.
 409  ZI_VALUE_TYPE_DEMOD_SAMPLE = 3,
 410
 411  /// ScopeWave type, used in v1 compatibility mode. use the ZIEvent.value.scopeWaveOld pointer
 412  /// to read the data of the event.
 413  ZI_VALUE_TYPE_SCOPE_WAVE_OLD = 4,
 414
 415  /// ZIAuxInSample type. Use the ZIEvent.value.auxInSample pointer to read the data of the event.
 416  ZI_VALUE_TYPE_AUXIN_SAMPLE = 5,
 417
 418  /// ZIDIOSample type. Use the ZIEvent.value.dioSample pointer to read the data of the event.
 419  ZI_VALUE_TYPE_DIO_SAMPLE = 6,
 420
 421  /// ZIByteArray type. Use the ZIEvent.value.byteArray pointer to read the data of the event.
 422  ZI_VALUE_TYPE_BYTE_ARRAY = 7,
 423
 424  /// ZIPWAWave type. Use the ZIEvent.value.pwaWave pointer to read the data of the event.
 425  ZI_VALUE_TYPE_PWA_WAVE = 8,
 426
 427  /// TreeChange type - a list of added or removed nodes, used in v1 compatibility mode. Use the
 428  /// ZIEvent.value.treeChangeDataOld pointer to read the data of the event.
 429  ZI_VALUE_TYPE_TREE_CHANGE_DATA_OLD = 16,
 430
 431  /// ZIDoubleDataTS type. Use the ZIEvent.value.doubleDataTS pointer to read the data of the event.
 432  ZI_VALUE_TYPE_DOUBLE_DATA_TS = 32,
 433
 434  /// ZIIntegerDataTS type. Use the ZIEvent.value.integerDataTS pointer to read the data of the event.
 435  ZI_VALUE_TYPE_INTEGER_DATA_TS = 33,
 436
 437  /// ZIComplexData type. Use the ZIEvent.value.complexData pointer to read the data of the event.
 438  ZI_VALUE_TYPE_COMPLEX_DATA = 34,
 439
 440  /// ZIScopeWave type. Use the ZIEvent.value.scopeWave pointer to read the data of the event.
 441  ZI_VALUE_TYPE_SCOPE_WAVE = 35,
 442
 443  /// ZIScopeWaveEx type. Use the ZIEvent.value.scopeWaveEx pointer to read the data of the event.
 444  ZI_VALUE_TYPE_SCOPE_WAVE_EX = 36,
 445
 446  /// ZIByteArrayTS type. Use the ZIEvent.value.byteArrayTS pointer to read the data of the event.
 447  ZI_VALUE_TYPE_BYTE_ARRAY_TS = 38,
 448
 449  /// ZICntSample type. Use the ZIEvent.value.cntSample pointer to read the data of the event.
 450  ZI_VALUE_TYPE_CNT_SAMPLE = 46,
 451
 452  /// ZITrigSample type. Use the ZIEvent.value.trigSample pointer to read the data of the event.
 453  ZI_VALUE_TYPE_TRIG_SAMPLE = 47,
 454
 455  /// ZITreeChangeData type - a list of added or removed nodes. Use the ZIEvent.value.treeChangeData
 456  /// pointer to read the data of the event.
 457  ZI_VALUE_TYPE_TREE_CHANGE_DATA = 48,
 458
 459  /// ZIAsyncReply type. Use the ZIEvent.value.asyncReply pointer to read the data of the event.
 460  ZI_VALUE_TYPE_ASYNC_REPLY = 50,
 461
 462  /// ZISweeperWave type. Use the ZIEvent.value.sweeperWave pointer to read the data of the event.
 463  ZI_VALUE_TYPE_SWEEPER_WAVE = 64,
 464
 465  /// ZISpectrumWave type. Use the ZIEvent.value.spectrumWave pointer to read the data of the event.
 466  ZI_VALUE_TYPE_SPECTRUM_WAVE = 65,
 467
 468  /// ZIAdvisorWave type. Use the ZIEvent.value.advisorWave pointer to read the data of the event.
 469  ZI_VALUE_TYPE_ADVISOR_WAVE = 66,
 470
 471  /// ZIVectorData type. Use the ZIEvent.value.vectorData pointer to access the data of the event.
 472  ZI_VALUE_TYPE_VECTOR_DATA = 67,
 473
 474  /// ZIImpedanceSample type. Use the ZIEvent.value.impedanceSample pointer to access the data of the event.
 475  ZI_VALUE_TYPE_IMPEDANCE_SAMPLE = 68,
 476
 477  /// ZISHFWaveformVectorData type. Use the ZIEvent.value.vectorData pointer to access the data of the event.
 478  ZI_VALUE_TYPE_SHF_GENERATOR_WAVEFORM_VECTOR_DATA = 69,
 479
 480  /// ZISHFResultLoggerVectorData type. Use the ZIEvent.value.vectorData pointer to access the data of the event.
 481  ZI_VALUE_TYPE_SHF_RESULT_LOGGER_VECTOR_DATA = 70,
 482
 483  /// ZISHFScopeOutputVectorData type. Use the ZIEvent.value.vectorData pointer to access the data of the event.
 484  ZI_VALUE_TYPE_SHF_SCOPE_VECTOR_DATA = 71,
 485
 486  /// ZISHFDemodulatorVectorData type. Use the ZIEvent.value.vectorData pointer to access the data of the event.
 487  ZI_VALUE_TYPE_SHF_DEMODULATOR_VECTOR_DATA = 72
 488
 489  /// @cond deprecated
 490  // **********
 491#ifdef _MSC_VER
 492  ,
 493  // no data type. the ziEvent is invalid.
 494  ZI_DATA_NONE = 0,
 495
 496  // double data type. use the ziEvent::Val.Double Pointer to read the data of the event.
 497  ZI_DATA_DOUBLE = 1,
 498  // integer data type. use the ziEvent::Val.Integer Pointer to read the data of the event.
 499  ZI_DATA_INTEGER = 2,
 500  // DemodSample data type. use the ziEvent::Val.Sample Pointer to read the data of the event.
 501  ZI_DATA_DEMODSAMPLE = 3,
 502  // ScopeWave data type. use the ziEvent::Val.Wave Pointer to read the data of the event.
 503  ZI_DATA_SCOPEWAVE = 4,
 504  // MiscADValue data type. use the ziEvent::Val.ADValue Pointer to read the data of the event.
 505  ZI_DATA_AUXINSAMPLE = 5,
 506  // DIOValue data type. use the ziEvent::Val.DIOValue Pointer to read the data of the event.
 507  ZI_DATA_DIOSAMPLE = 6,
 508  // ByteArray data type. use the ziEvent::Val.ByteArray Pointer to read the data of the event.
 509  ZI_DATA_BYTEARRAY = 7,
 510
 511  // a list of added or removed trees. use the ziEvent::Val.Tree Pointer to read the data of the event.
 512  ZI_DATA_TREE_CHANGED = 16
 513#endif
 514  /// @endcond
 515};
 516
 517#ifndef __cplusplus
 518typedef enum ZIValueType_enum ZIValueType_enum;
 519#endif
 520
 521#ifdef _MSC_VER
 522#pragma deprecated(ZI_DATA_NONE)
 523#pragma deprecated(ZI_DATA_DOUBLE)
 524#pragma deprecated(ZI_DATA_INTEGER)
 525#pragma deprecated(ZI_DATA_DEMODSAMPLE)
 526#pragma deprecated(ZI_DATA_SCOPEWAVE)
 527#pragma deprecated(ZI_DATA_AUXINSAMPLE)
 528#pragma deprecated(ZI_DATA_DIOSAMPLE)
 529#pragma deprecated(ZI_DATA_BYTEARRAY)
 530#pragma deprecated(ZI_DATA_TREE_CHANGED)
 531#else
 532
 533#ifdef __cplusplus
 534#define ZIValueType_enum_cast(val) ZIValueType_enum(val)
 535#else
 536#define ZIValueType_enum_cast(val) val
 537#endif
 538
 539DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_NONE         = ZIValueType_enum_cast(0));
 540DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_DOUBLE       = ZIValueType_enum_cast(1));
 541DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_INTEGER      = ZIValueType_enum_cast(2));
 542DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_DEMODSAMPLE  = ZIValueType_enum_cast(3));
 543DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_SCOPEWAVE    = ZIValueType_enum_cast(4));
 544DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_AUXINSAMPLE  = ZIValueType_enum_cast(5));
 545DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_DIOSAMPLE    = ZIValueType_enum_cast(6));
 546DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_BYTEARRAY    = ZIValueType_enum_cast(7));
 547DEPRECATED_ENUM(const ZIValueType_enum ZI_DATA_TREE_CHANGED = ZIValueType_enum_cast(16));
 548#endif
 549
 550typedef uint64_t ZITimeStamp;
 551typedef double ZIDoubleData;
 552typedef int64_t ZIIntegerData;
 553typedef uint32_t ZIAsyncTag;
 554/// A handle with which to reference an instance of a ziCore Module created with ::ziAPIModCreate.
 555typedef uint64_t ZIModuleHandle;
 556
 557/// The structure used to hold a single IEEE double value. Same as ZIDoubleData, but with timestamp.
 558struct ZIDoubleDataTS {
 559  /// Time stamp at which the value has changed
 560  ZITimeStamp timeStamp;
 561  ZIDoubleData value;
 562};
 563
 564#ifndef __cplusplus
 565typedef struct ZIDoubleDataTS ZIDoubleDataTS;
 566#endif
 567
 568/// The structure used to hold a single 64bit signed integer value. Same as ZIIntegerData, but with timestamp.
 569struct ZIIntegerDataTS {
 570  /// Time stamp at which the value has changed
 571  ZITimeStamp timeStamp;
 572  ZIIntegerData value;
 573};
 574
 575#ifndef __cplusplus
 576typedef struct ZIIntegerDataTS ZIIntegerDataTS;
 577#endif
 578
 579/// The structure used to hold a complex double value.
 580struct ZIComplexData {
 581  /// Time stamp at which the value has changed
 582  ZITimeStamp timeStamp;
 583  ZIDoubleData real;
 584  ZIDoubleData imag;
 585};
 586
 587#  ifndef __cplusplus
 588typedef struct ZIComplexData ZIComplexData;
 589#  endif
 590
 591/// Defines the actions that are performed on a tree, as returned in
 592/// the ZITreeChangeData::action or ZITreeChangeDataOld::action.
 593enum ZITreeAction_enum {
 594  /// A node has been removed.
 595  ZI_TREE_ACTION_REMOVE = 0,
 596
 597  /// A node has been added.
 598  ZI_TREE_ACTION_ADD = 1,
 599
 600  /// A node has been changed.
 601  ZI_TREE_ACTION_CHANGE = 2
 602};
 603
 604/// The struct is holding info about added or removed nodes.
 605struct ZITreeChangeData {
 606  /// Time stamp at which the data was updated.
 607  ZITimeStamp timeStamp;
 608  /// field indicating which action occurred on the tree. A value of the ZITreeAction_enum.
 609  uint32_t action;
 610  /// Name of the Path that has been added, removed or changed.
 611  char name[MAX_NAME_LEN];
 612};
 613
 614#ifndef __cplusplus
 615typedef struct ZITreeChangeData ZITreeChangeData;
 616#endif
 617
 618/// The structure used to hold info about added or removed nodes. This is the version without timestamp
 619/// used in API v1 compatibility mode.
 620struct TreeChange {
 621  /// field indicating which action occurred on the tree. A value of the ::ZITreeAction_enum (TREE_ACTION) enum.
 622  uint32_t Action;
 623  /// Name of the Path that has been added, removed or changed
 624  char Name[MAX_NAME_LEN];
 625};
 626
 627#ifndef __cplusplus
 628typedef struct TreeChange TreeChange;
 629#endif
 630
 631
 632/// The structure used to hold data for a single demodulator sample
 633struct ZIDemodSample {
 634  /// The timestamp at which the sample has been measured.
 635  ZITimeStamp timeStamp;
 636
 637  /// X part of the sample.
 638  double x;
 639  /// Y part of the sample.
 640  double y;
 641
 642  /// oscillator frequency at that sample.
 643  double frequency;
 644  /// oscillator phase at that sample.
 645  double phase;
 646
 647  /// the current bits of the DIO.
 648  uint32_t dioBits;
 649
 650  /// trigger bits
 651  uint32_t trigger;
 652
 653  /// value of Aux input 0.
 654  double auxIn0;
 655  /// value of Aux input 1.
 656  double auxIn1;
 657};
 658
 659#ifndef __cplusplus
 660typedef struct ZIDemodSample ZIDemodSample;
 661#endif
 662
 663/// The structure used to hold data for a single auxiliary inputs sample.
 664struct ZIAuxInSample {
 665  /// The timestamp at which the values have been measured.
 666  ZITimeStamp timeStamp;
 667
 668  /// Channel 0 voltage.
 669  double ch0;
 670  /// Channel 1 voltage.
 671  double ch1;
 672};
 673
 674#ifndef __cplusplus
 675typedef struct ZIAuxInSample ZIAuxInSample;
 676#endif
 677
 678/// The structure used to hold data for a single digital I/O sample
 679struct ZIDIOSample {
 680  /// The timestamp at which the values have been measured.
 681  ZITimeStamp timeStamp;
 682
 683  /// The digital I/O values.
 684  uint32_t bits;
 685
 686  /// Filler to keep 8 bytes alignment in the array of ZIDIOSample structures.
 687  uint32_t reserved;
 688};
 689
 690#ifndef __cplusplus
 691typedef struct ZIDIOSample ZIDIOSample;
 692#endif
 693
 694#ifdef _MSC_VER
 695// Visual C++ specific
 696#pragma warning(push)
 697#pragma warning(disable:4200)
 698#endif
 699
 700/// The structure used to hold an arbitrary array of bytes. This is the version without timestamp
 701/// used in API Level 1 compatibility mode.
 702struct ZIByteArray {
 703  /// Length of the data readable from the Bytes field.
 704  uint32_t length;
 705  /// The data itself. The array has the size given in length.
 706  uint8_t bytes[0];
 707};
 708
 709#ifndef __cplusplus
 710typedef struct ZIByteArray ZIByteArray;
 711#endif
 712
 713/// The structure used to hold an arbitrary array of bytes. This is the same as ZIByteArray, but with timestamp.
 714struct ZIByteArrayTS {
 715  /// Time stamp at which the data was updated
 716  ZITimeStamp timeStamp;
 717  /// length of the data readable from the bytes field
 718  uint32_t length;
 719  /// the data itself. The array has the size given in length
 720  uint8_t bytes[0];
 721};
 722
 723#ifndef __cplusplus
 724typedef struct ZIByteArrayTS ZIByteArrayTS;
 725#endif
 726
 727/// The structure used to hold data for a single counter sample.
 728struct ZICntSample {
 729  /// The timestamp at which the values have been measured.
 730  ZITimeStamp timeStamp;
 731  /// Counter value
 732  int32_t counter;
 733  /// Trigger bits
 734  uint32_t trigger;
 735};
 736
 737#ifndef __cplusplus
 738typedef struct ZICntSample ZICntSample;
 739#endif
 740
 741/// The structure used to hold data for a single counter sample.
 742struct ZITrigSample {
 743  /// The timestamp at which the values have been measured.
 744  ZITimeStamp timeStamp;
 745  /// The sample tick at which the values have been measured.
 746  ZITimeStamp sampleTick;
 747  /// Trigger bits
 748  uint32_t trigger;
 749  /// Missed trigger bits
 750  uint32_t missedTriggers;
 751  /// AWG trigger values at the time of trigger
 752  uint32_t awgTrigger;
 753  /// Dio values at the time of trigger
 754  uint32_t dio;
 755  /// AWG sequencer index at the time of trigger
 756  uint32_t sequenceIndex;
 757};
 758
 759#ifndef __cplusplus
 760typedef struct ZITrigSample ZITrigSample;
 761#endif
 762
 763/// The structure used to hold a single scope shot (API Level 1). If the client is connected to the Data Server using
 764/// API Level 4 (recommended if supported by your device class) please see ::ZIScopeWave instead (::ZIScopeWaveEx for
 765/// API Level 5 and above).
 766struct ScopeWave {
 767  /// Time difference between samples
 768  double dt;
 769
 770  /// Scope channel of the represented data
 771  uint32_t ScopeChannel;
 772  /// Trigger channel of the represented data
 773  uint32_t TriggerChannel;
 774
 775  /// Bandwidth-limit flag
 776  uint32_t BWLimit;
 777
 778  /// Count of samples
 779  uint32_t Count;
 780  /// First wave data
 781  int16_t Data[0];
 782};
 783
 784#ifndef __cplusplus
 785typedef struct ScopeWave ScopeWave;
 786#endif
 787
 788/// Defines the data format of scope samples:
 789enum ZIScopeSampleFormat_enum
 790{
 791  /// Int16 Non-Interleaved, the samples for each enabled scope channel are stored
 792  /// together one channel after the other,
 793  // e.g. channel0-sample0, channel0-sample1...channel0-sampleN, channel1-sample0, channel1-sample1...channel1-sampleN
 794  ZI_SCOPE_SAMPLE_FORMAT_INT16 = 0,
 795  /// Int32, Non-Interleaved
 796  ZI_SCOPE_SAMPLE_FORMAT_INT32 = 1,
 797  /// Float, Non-Interleaved
 798  ZI_SCOPE_SAMPLE_FORMAT_FLOAT = 2,
 799  /// Int16 Interleave d, the samples for each enabled scope channel are stored
 800  /// in successive elements in the data buffer,
 801  /// e.g. channel0-sample0,channel1-sample0,channel0-sample1,channel1-sample1,channel0-sample2,channel1-sample2.
 802  ZI_SCOPE_SAMPLE_FORMAT_INT16_INTERLEAVED = 4,
 803  /// Int32 Interleaved as described for ZI_SCOPE_SAMPLE_FORMAT_INT16INTERLEAVED.
 804  ZI_SCOPE_SAMPLE_FORMAT_INT32_INTERLEAVED = 5,
 805  /// Float Interleaved as described for ZI_SCOPE_SAMPLE_FORMAT_INT16INTERLEAVED.
 806  ZI_SCOPE_SAMPLE_FORMAT_FLOAT_INTERLEAVED = 6,
 807};
 808
 809/// Helper enum to enable testing certain properties of the scope sample format
 810enum ZIScopeSampleFormatMask_enum
 811{
 812  /// Mask to enable determining only the data type in ZIScopeSampleFormat_enum.
 813  ZI_SCOPE_SAMPLE_FORMAT_MASK_DATA_TYPE = 3,
 814  /// Mask to test the interleaved bit in ZIScopeSampleFormat_enum
 815  ZI_SCOPE_SAMPLE_FORMAT_MASK_INTERLEAVED = 4
 816};
 817
 818/// The structure used to hold scope data (when using API Level 4). Note that ZIScopeWave does not contain the structure
 819/// member channelOffset, whereas ::ZIScopeWaveEx does. The data may be formatted differently, depending on
 820/// settings. See the description of the structure members for details.
 821struct ZIScopeWave {
 822// --- 8 bytes border
 823    /// The timestamp of the last sample in this data block
 824    ZITimeStamp timeStamp;
 825
 826// --- 8 bytes border
 827    /// The timestamp of the trigger (may also fall between samples and in another block)
 828    ZITimeStamp triggerTimeStamp;
 829
 830// --- 8 bytes border
 831    /// Time difference between samples in seconds
 832    double dt;
 833
 834// --- 8 bytes border
 835    /// Up to four channels: if channel is enabled, corresponding element is non-zero.
 836    uint8_t channelEnable[4];
 837
 838    /// Specifies the input source for each of the scope four channels.
 839    ///
 840    /// Value of channelInput and corresponding input source:
 841    ///  - 0 = Signal Input 1,
 842    ///  - 1 = Signal Input 2,
 843    ///  - 2 = Trigger Input 1,
 844    ///  - 3 = Trigger Input 2,
 845    ///  - 4 = Aux Output 1,
 846    ///  - 5 = Aux Output 2,
 847    ///  - 6 = Aux Output 3,
 848    ///  - 7 = Aux Output 4,
 849    ///  - 8 = Aux Input 1,
 850    ///  - 9 = Aux Input 2.
 851    uint8_t channelInput[4];
 852
 853// --- 8 bytes border
 854    /// Non-zero if trigger is enabled:
 855    ///
 856    /// Bit encoded:
 857    ///   - Bit (0): 1 = Trigger on rising edge,
 858    ///   - Bit (1): 1 = Trigger on falling edge.
 859    uint8_t triggerEnable;
 860
 861    /// Trigger source (same values as for channel input)
 862    uint8_t triggerInput;
 863
 864    uint8_t reserved0[2];
 865
 866    /// Bandwidth-limit flag, per channel.
 867    ///
 868    /// Bit encoded:
 869    ///   - Bit (0): 1 = Enable bandwidth limiting.
 870    ///   - Bit (7...1): Reserved
 871    uint8_t channelBWLimit[4];
 872
 873// --- 8 bytes border
 874    /// Enable/disable math operations such as averaging or FFT.
 875    ///
 876    /// Bit encoded:
 877    ///   - Bit(0): 1 = Perform averaging,
 878    ///   - Bit(1): 1 = Perform FFT,
 879    ///   - Bit(2): 1 = Data originates from a channel-collapsing transform, e.g. |ch0+i*ch1|
 880    ///   - Bit(7...3): Reserved
 881    uint8_t channelMath[4];
 882
 883    /// Data scaling factors for up to 4 channels
 884    float channelScaling[4];
 885
 886    /// Current scope shot sequence number. Identifies a scope shot.
 887    uint32_t sequenceNumber;
 888
 889// --- 8 bytes border
 890    /// Current segment number.
 891    uint32_t segmentNumber;
 892
 893    /// Current block number from the beginning of a scope shot.
 894    /// Large scope shots are split into blocks, which need to be concatenated to obtain the complete scope shot.
 895    uint32_t blockNumber;
 896
 897// --- 8 bytes border
 898    /// Total number of samples in one channel in the current scope shot, same for all channels
 899    uint64_t totalSamples;
 900
 901// --- 8 bytes border
 902    /// Data transfer mode
 903    ///
 904    /// Value and the corresponding data transfer mode:
 905    ///  - 0 - SingleTransfer,
 906    ///  - 1 - BlockTransfer,
 907    ///  - 3 - ContinuousTransfer.
 908    /// Other values are reserved.
 909    uint8_t dataTransferMode;
 910
 911    /// Block marker:
 912    ///
 913    /// Bit encoded:
 914    ///   - Bit (0): 1 = End marker for continuous or multi-block transfer,
 915    ///   - Bit (7..0): Reserved.
 916    uint8_t blockMarker;
 917
 918
 919    /// Indicator Flags.
 920    ///
 921    /// Bit encoded:
 922    ///   - Bit (0): 1 = Data loss detected (samples are 0),
 923    ///   - Bit (1): 1 = Missed trigger,
 924    ///   - Bit (2): 1 = Transfer failure (corrupted data).
 925    uint8_t flags;
 926
 927    /// Data format of samples:
 928    ///
 929    /// Value is one of ZIScopeSampleFormat_enum
 930    uint8_t sampleFormat;
 931
 932    /// Number of samples in one channel in the current block, same for all channels
 933    uint32_t sampleCount;
 934
 935// --- 8 bytes border
 936    /// Wave data, access via union member dataInt16, dataInt32 or dataFloat depending on sampleFormat.
 937    /// Indexing scheme also depends on sampleFormat.
 938    ///
 939    /// Example for interleaved int16 wave, 4096 samples, 2 channels:
 940    ///   - data.dataInt16[0]    - sample 0 of channel 0,
 941    ///   - data.dataInt16[1]    - sample 0 of channel 1,
 942    ///   - data.dataInt16[2]    - sample 1 of channel 0,
 943    ///   - data.dataInt16[3]    - sample 1 of channel 1,
 944    ///   - ...
 945    ///   - data.dataInt16[8190] - sample 4095 of channel 0,
 946    ///   - data.dataInt16[8191] - sample 4095 of channel 1.
 947    ///
 948    /// Example for non-interleaved int16 wave, 4096 samples, 2 channels:
 949    ///   - data.dataInt16[0]    - sample 0 of channel 0,
 950    ///   - data.dataInt16[1]    - sample 1 of channel 0,
 951    ///   - ..                   - ...
 952    ///   - data.dataInt16[4095] - sample 4095 of channel 0,
 953    ///   - data.dataInt16[4096] - sample 0 of channel 1,
 954    ///   - data.dataInt16[4097] - sample 1 of channel 1,
 955    ///   - ...
 956    ///   - data.dataInt16[8191] - sample 4095 of channel 1.
 957    union {
 958      /// Wave data when sampleFormat==0 or sampleFormat==4
 959      int16_t dataInt16[0];
 960      /// Wave data when sampleFormat==1 or sampleFormat==5
 961      int32_t dataInt32[0];
 962      /// Wave data when sampleFormat==2 or sampleFormat==6
 963      float dataFloat[0];
 964    } data;
 965
 966};
 967
 968#ifndef __cplusplus
 969typedef struct ZIScopeWave ZIScopeWave;
 970#endif
 971
 972/// The structure used to hold scope data (extended, when using API Level 5). Note that ZIScopeWaveEx contains the
 973/// structure member channelOffset; ::ZIScopeWave does not. The data may be formatted differently, depending on
 974/// settings.  See the description of the structure members for details.
 975struct ZIScopeWaveEx {
 976// --- 8 bytes border
 977    /// The timestamp of the last sample in this data block.
 978    ZITimeStamp timeStamp;
 979
 980// --- 8 bytes border
 981    /// The Timestamp of the trigger (may also fall between samples and in another block).
 982    ZITimeStamp triggerTimeStamp;
 983
 984// --- 8 bytes border
 985    /// Time difference between samples in seconds.
 986    double dt;
 987
 988// --- 8 bytes border
 989    /// Up to four channels: If channel is enabled, the corresponding element is non-zero.
 990    uint8_t channelEnable[4];
 991
 992    /// Specifies the input source for each of the scope four channels.
 993    ///
 994    /// Value of channelInput and corresponding input source:
 995    ///   - 0 = Signal Input 1,
 996    ///   - 1 = Signal Input 2,
 997    ///   - 2 = Trigger Input 1,
 998    ///   - 3 = Trigger Input 2,
 999    ///   - 4 = Aux Output 1,
1000    ///   - 5 = Aux Output 2,
1001    ///   - 6 = Aux Output 3,
1002    ///   - 7 = Aux Output 4,
1003    ///   - 8 = Aux Input 1,
1004    ///   - 9 = Aux Input 2.
1005    uint8_t channelInput[4];
1006
1007// --- 8 bytes border
1008    /// Non-zero if trigger is enabled.
1009    ///
1010    /// Bit encoded:
1011    ///   - Bit (0): 1 = Trigger on rising edge,
1012    ///   - Bit (1): 1 = Trigger on falling edge.
1013    uint8_t triggerEnable;
1014
1015    /// Trigger source (same values as for channel input)
1016    uint8_t triggerInput;
1017
1018    uint8_t reserved0[2];
1019
1020    /// Bandwidth-limit flag, per channel.
1021    ///
1022    /// Bit encoded:
1023    ///   - Bit (0): 1 = Enable bandwidth limiting.
1024    ///   - Bit (7...1): Reserved
1025    uint8_t channelBWLimit[4];
1026
1027// --- 8 bytes border
1028    /// Enable/disable math operations such as averaging or FFT.
1029    ///
1030    /// Bit encoded:
1031    ///   - Bit(0): 1 = Perform averaging,
1032    ///   - Bit(1): 1 = Perform FFT,
1033    ///   - Bit(7...2): Reserved
1034    uint8_t channelMath[4];
1035
1036    /// Data scaling factors for up to 4 channels
1037    float channelScaling[4];
1038
1039    /// Current scope shot sequence number. Identifies a scope shot.
1040    uint32_t sequenceNumber;
1041
1042// --- 8 bytes border
1043    /// Current segment number.
1044    uint32_t segmentNumber;
1045
1046    /// Current block number from the beginning of a scope shot.
1047    /// Large scope shots are split into blocks, which need to be concatenated to obtain the complete scope shot.
1048    uint32_t blockNumber;
1049
1050// --- 8 bytes border
1051    /// Total number of samples in one channel in the current scope shot, same for all channels
1052    uint64_t totalSamples;
1053
1054// --- 8 bytes border
1055    /// Data transfer mode.
1056    ///
1057    /// Value and the corresponding data transfer mode:
1058    ///  - 0 - SingleTransfer,
1059    ///  - 1 - BlockTransfer,
1060    ///  - 3 - ContinuousTransfer.
1061    /// Other values are reserved.
1062    uint8_t dataTransferMode;
1063
1064    /// Block marker providing additional information about the current block.
1065    ///
1066    /// Bit encoded:
1067    ///   - Bit (0): 1 = End marker for continuous or multi-block transfer,
1068    ///   - Bit (7..0): Reserved.
1069    uint8_t blockMarker;
1070
1071
1072    /// Indicator Flags.
1073    ///
1074    /// Bit encoded:
1075    ///   - Bit (0): 1 = Data loss detected (samples are 0),
1076    ///   - Bit (1): 1 = Missed trigger,
1077    ///   - Bit (2): 1 = Transfer failure (corrupted data).
1078    ///   - Bit (3): 1 = Assembled scope recording. 'sampleCount' will be set to 0, use 'totalSamples' instead.
1079    ///   - Bit (7...4): Reserved.
1080    uint8_t flags;
1081
1082    /// Data format of samples:
1083    ///
1084    /// Value is one of ZIScopeSampleFormat_enum
1085    uint8_t sampleFormat;
1086
1087    /// Number of samples in one channel in the current block, same for all channels.
1088    uint32_t sampleCount;
1089
1090// --- 8 bytes border
1091    /// Data offset (scaled) for up to 4 channels.
1092    double channelOffset[4];
1093
1094// --- 8 bytes border
1095    /// Number of segments in the recording. Only valid if 'flags' bit (3) is set.
1096    uint32_t totalSegments;
1097
1098    uint32_t reserved1;
1099
1100// --- 8 bytes border
1101    uint64_t reserved2[31];
1102
1103// --- 8 bytes border
1104    /// Wave data, access via union member dataInt16, dataInt32 or dataFloat depending on sampleFormat.
1105    /// Indexing scheme also depends on sampleFormat.
1106    ///
1107    /// Example for interleaved int16 wave, 4096 samples, 2 channels:
1108    ///   - data.dataInt16[0]    - sample 0 of channel 0,
1109    ///   - data.dataInt16[1]    - sample 0 of channel 1,
1110    ///   - data.dataInt16[2]    - sample 1 of channel 0,
1111    ///   - data.dataInt16[3]    - sample 1 of channel 1,
1112    ///   - ...
1113    ///   - data.dataInt16[8190] - sample 4095 of channel 0,
1114    ///   - data.dataInt16[8191] - sample 4095 of channel 1.
1115    ///
1116    /// Example for non-interleaved int16 wave, 4096 samples, 2 channels:
1117    ///   - data.dataInt16[0]    - sample 0 of channel 0,
1118    ///   - data.dataInt16[1]    - sample 1 of channel 0,
1119    ///   - ..                   - ...
1120    ///   - data.dataInt16[4095] - sample 4095 of channel 0,
1121    ///   - data.dataInt16[4096] - sample 0 of channel 1,
1122    ///   - data.dataInt16[4097] - sample 1 of channel 1,
1123    ///   - ...
1124    ///   - data.dataInt16[8191] - sample 4095 of channel 1.
1125    union {
1126      /// Wave data when sampleFormat==0 or sampleFormat==4
1127      int16_t dataInt16[0];
1128      /// Wave data when sampleFormat==1 or sampleFormat==5
1129      int32_t dataInt32[0];
1130      /// Wave data when sampleFormat==2 or sampleFormat==6
1131      float dataFloat[0];
1132    } data;
1133
1134};
1135
1136#ifndef __cplusplus
1137typedef struct ZIScopeWaveEx ZIScopeWaveEx;
1138#endif
1139
1140/// Single PWA sample value
1141struct ZIPWASample {
1142  /// Phase position of each bin
1143  double binPhase;
1144  /// Real PWA result or X component of a demod PWA
1145  double x;
1146  /// Y component of the demod PWA
1147  double y;
1148  /// Number of events per bin
1149  uint32_t countBin;
1150  /// Reserved
1151  uint32_t reserved;
1152};
1153
1154#ifndef __cplusplus
1155typedef struct ZIPWASample ZIPWASample;
1156#endif
1157
1158/// PWA Wave
1159struct ZIPWAWave {
1160  /// Time stamp at which the data was updated
1161  ZITimeStamp timeStamp;
1162
1163  /// Total sample count considered for PWA
1164  uint64_t sampleCount;
1165
1166  /// Input selection used for the PWA
1167  uint32_t inputSelect;
1168  /// Oscillator used for the PWA
1169  uint32_t oscSelect;
1170  /// Harmonic setting
1171  uint32_t harmonic;
1172  /// Bin count of the PWA
1173  uint32_t binCount;
1174
1175  /// Frequency during PWA accumulation
1176  double frequency;
1177
1178  /// Type of the PWA
1179  uint8_t pwaType;
1180  /// PWA Mode [0: zoom PWA, 1: harmonic PWA]
1181  uint8_t mode;
1182  /// Overflow indicators.
1183  /// overflow[0]: Data accumulator overflow,
1184  /// overflow[1]: Counter at limit,
1185  /// overflow[6..2]: Reserved,
1186  /// overflow[7]: Invalid (missing frames).
1187  uint8_t overflow;
1188  /// Commensurability of the data
1189  uint8_t commensurable;
1190  /// Reserved 32bit
1191  uint32_t reservedUInt;
1192
1193  /// PWA data vector
1194  ZIPWASample data[0];
1195};
1196
1197#ifndef __cplusplus
1198typedef struct ZIPWAWave ZIPWAWave;
1199#endif
1200
1201/// Enumerates the bits set in an ::ZIImpedanceSample's flags.
1202enum ZIImpFlags_enum {
1203  ZI_IMP_FLAGS_NONE               = 0x00000000,
1204  /// Internal calibration is applied
1205  ZI_IMP_FLAGS_VALID_INTERNAL     = 0x00000001,
1206  /// User compensation is applied
1207  ZI_IMP_FLAGS_VALID_USER         = 0x00000002,
1208  /// Reserved for future use.
1209  ZI_IMP_FLAGS_AUTORANGE_GATING   = 0x00000004,
1210  /// Overflow on voltage input
1211  ZI_IMP_FLAGS_OVERFLOW_VOLTAGE   = 0x00000010,
1212  /// Overflow on current input
1213  ZI_IMP_FLAGS_OVERFLOW_CURRENT   = 0x00000020,
1214  /// Underflow on voltage input
1215  ZI_IMP_FLAGS_UNDERFLOW_VOLTAGE  = 0x00000040,
1216  /// Underflow on current input
1217  ZI_IMP_FLAGS_UNDERFLOW_CURRENT  = 0x00000080,
1218  /// Reserved for future use.
1219  ZI_IMP_FLAGS_FREQ_EXACT         = 0x00000100,
1220  /// Reserved for future use.
1221  ZI_IMP_FLAGS_FREQ_INTERPOLATION = 0x00000200,
1222  /// Reserved for future use.
1223  ZI_IMP_FLAGS_FREQ_EXTRAPOLATION = 0x00000400,
1224  /// LowDUT impedance detected
1225  ZI_IMP_FLAGS_LOWDUT2T           = 0x00000800,
1226  /// Suppression of first parameter PARAM0
1227  ZI_IMP_FLAGS_SUPPRESSION_PARAM0   = 0x00001000,
1228  /// Suppression of second parameter PARAM1
1229  ZI_IMP_FLAGS_SUPPRESSION_PARAM1   = 0x00002000,
1230  /// Reserved for future use
1231  ZI_IMP_FLAGS_FREQLIMIT_RANGE_VOLTAGE  = 0x00004000,
1232  /// Frequency bigger than the frequency limit of active current input range
1233  ZI_IMP_FLAGS_FREQLIMIT_RANGE_CURRENT  = 0x00008000,
1234  /// Strong compensation detected on PARAM0
1235  ZI_IMP_FLAGS_STRONGCOMPENSATION_PARAM0 = 0x00010000,
1236  /// Strong compensation detected on PARAM1
1237  ZI_IMP_FLAGS_STRONGCOMPENSATION_PARAM1 = 0x00020000,
1238  /// Non-reasonable values for Q/D measurement
1239  ZI_IMP_FLAGS_NEGATIVE_QFACTOR = 0x00040000,
1240  /// One-period measurement enabled
1241  ZI_IMP_FLAGS_ONE_PERIOD = 0x00080000,
1242  /// One-period measurement values are invalid
1243  ZI_IMP_FLAGS_ONE_PERIOD_INVALID = 0x00100000,
1244  /// Reserved for future use.
1245  ZI_IMP_FLAGS_BWC_BIT1           = 0x00200000,
1246  /// Reserved for future use.
1247  ZI_IMP_FLAGS_BWC_BIT2           = 0x00400000,
1248  /// Reserved for future use.
1249  ZI_IMP_FLAGS_BWC_BIT3           = 0x00800000,
1250  /// Reserved for future use.
1251  ZI_IMP_FLAGS_BWC_MASK           = 0x00f00000,
1252  /// Open detected on 4T measurement
1253  ZI_IMP_FLAGS_OPEN_DETECTION     = 0x01000000,
1254  /// Overflow on sigin0
1255  ZI_IMP_FLAGS_OVERFLOW_SIGIN0    = 0x04000000,
1256  /// Overflow on sigin1
1257  ZI_IMP_FLAGS_OVERFLOW_SIGIN1    = 0x08000000,
1258  /// Model selected for the measurement
1259  ZI_IMP_FLAGS_MODEL_MASK         = 0xf0000000
1260};
1261
1262#ifndef __cplusplus
1263typedef enum ZIImpFlags_enum ZIImpFlags_enum;
1264#endif
1265
1266/// The structure used to hold data for a single impedance sample.
1267struct ZIImpedanceSample {
1268  /// Timestamp at which the sample has been measured
1269  ZITimeStamp timeStamp;
1270
1271  /// Real part of the impedance sample
1272  double realz;
1273  /// Imaginary part of the impedance sample
1274  double imagz;
1275
1276  /// Frequency at that sample
1277  double frequency;
1278  /// Phase at that sample
1279  double phase;
1280
1281  /// Flags (see ::ZIImpFlags_enum)
1282  uint32_t flags;
1283
1284  /// Trigger bits
1285  uint32_t trigger;
1286
1287  /// Value of model parameter 0
1288  double param0;
1289  /// Value of model parameter 1
1290  double param1;
1291
1292  /// Drive amplitude
1293  double drive;
1294
1295  /// Bias voltage
1296  double bias;
1297};
1298
1299#ifndef __cplusplus
1300typedef struct ZIImpedanceSample ZIImpedanceSample;
1301#endif
1302
1303struct ZIStatisticSample {
1304  /// Average value or single value
1305  double avg;
1306
1307  /// Standard deviation
1308  double stddev;
1309
1310  /// Power value
1311  double pwr;
1312};
1313
1314#ifndef __cplusplus
1315typedef struct ZIStatisticSample ZIStatisticSample;
1316#endif
1317
1318struct ZISweeperDoubleSample {
1319  /// Grid value (x-axis)
1320  double grid;
1321
1322  /// Bandwidth
1323  double bandwidth;
1324
1325  /// Sample count used for statistic calculation
1326  uint64_t count;
1327
1328  /// Result value (y-axis)
1329  ZIStatisticSample value;
1330};
1331
1332#ifndef __cplusplus
1333typedef struct ZISweeperDoubleSample ZISweeperDoubleSample;
1334#endif
1335
1336struct ZISweeperDemodSample {
1337  /// Grid value (x-axis)
1338  double grid;
1339
1340  /// Demodulator bandwidth used for the specific sweep point
1341  double bandwidth;
1342
1343  /// Sample count used for statistic calculation
1344  uint64_t count;
1345
1346  /// Time constant calculated for the specific sweep point
1347  double tc;
1348
1349  /// Time constant used by the device
1350  double tcMeas;
1351
1352  /// Settling time (s) used to wait until averaging operation is started
1353  double settling;
1354
1355  /// Time stamp when the grid value was set on the device
1356  ZITimeStamp setTimeStamp;
1357
1358  /// Time stamp when the first statistic value was recorded
1359  ZITimeStamp nextTimeStamp;
1360
1361  /// Sweep point statistic result of X
1362  ZIStatisticSample x;
1363
1364  /// Sweep point statistic result of Y
1365  ZIStatisticSample y;
1366
1367  /// Sweep point statistic result of R
1368  ZIStatisticSample r;
1369
1370  /// Sweep point statistic result of phase
1371  ZIStatisticSample phase;
1372
1373  /// Sweep point statistic result of frequency
1374  ZIStatisticSample frequency;
1375
1376  /// Sweep point statistic result of auxin0
1377  ZIStatisticSample auxin0;
1378
1379  /// Sweep point statistic result of auxin1
1380  ZIStatisticSample auxin1;
1381};
1382
1383#ifndef __cplusplus
1384typedef struct ZISweeperDemodSample ZISweeperDemodSample;
1385#endif
1386
1387struct ZISweeperImpedanceSample {
1388  /// Grid value (x-axis)
1389  double grid;
1390
1391  /// Demodulator bandwidth used for the specific sweep point
1392  double bandwidth;
1393
1394  /// Sample count used for statistic calculation
1395  uint64_t count;
1396
1397  /// Time constant calculated for the specific sweep point
1398  double tc;
1399
1400  /// Time constant used by the device
1401  double tcMeas;
1402
1403  /// Settling time (s) used to wait until averaging operation is started
1404  double settling;
1405
1406  /// Time stamp when the grid value was set on the device
1407  ZITimeStamp setTimeStamp;
1408
1409  /// Time stamp when the first statistic value was recorded
1410  ZITimeStamp nextTimeStamp;
1411
1412  /// Sweep point statistic result of X
1413  ZIStatisticSample realz;
1414
1415  /// Sweep point statistic result of Y
1416  ZIStatisticSample imagz;
1417
1418  /// Sweep point statistic result of R
1419  ZIStatisticSample absz;
1420
1421  /// Sweep point statistic result of phase
1422  ZIStatisticSample phasez;
1423
1424  /// Sweep point statistic result of frequency
1425  ZIStatisticSample frequency;
1426
1427  /// Sweep point statistic result of param0
1428  ZIStatisticSample param0;
1429
1430  /// Sweep point statistic result of param1
1431  ZIStatisticSample param1;
1432
1433  /// Sweep point statistic result of drive amplitude
1434  ZIStatisticSample drive;
1435
1436  /// Sweep point statistic result of bias
1437  ZIStatisticSample bias;
1438
1439  /// Flags (see ::ZIImpFlags_enum)
1440  uint32_t flags;
1441};
1442
1443#ifndef __cplusplus
1444typedef struct ZISweeperImpedanceSample ZISweeperImpedanceSample;
1445#endif
1446
1447struct ZISweeperHeader {
1448  /// Total sample count considered for sweeper
1449  uint64_t sampleCount;
1450
1451// --- 8 bytes border
1452  /// Flags
1453  ///   Bit 0: Phase unwrap
1454  ///   Bit 1: Sinc filter
1455  uint8_t flags;
1456
1457  /// Sample format
1458  /// Double = 0, Demodulator = 1, Impedance = 2
1459  uint8_t sampleFormat;
1460
1461  /// Sweep mode
1462  /// Sequential = 0, Binary = 1, Bidirectional = 2, Reverse = 3
1463  uint8_t sweepMode;
1464
1465  /// Bandwidth mode
1466  /// Manual = 0, Fixed = 1, Auto = 2
1467  uint8_t bandwidthMode;
1468
1469  /// Reserved space for future use
1470  uint8_t reserved0[4];
1471
1472// --- 8 bytes border
1473  /// Reserved space for future use
1474  uint8_t reserved1[8];
1475};
1476
1477#ifndef __cplusplus
1478typedef struct ZISweeperHeader ZISweeperHeader;
1479#endif
1480
1481struct ZISweeperWave {
1482  /// Time stamp at which the data was updated
1483  ZITimeStamp timeStamp;
1484
1485// --- 8 bytes border
1486  ZISweeperHeader header;
1487
1488// --- 8 bytes border
1489  /// Sweeper data vector
1490  union {
1491    ZISweeperDoubleSample dataDouble[0];
1492    ZISweeperDemodSample dataDemod[0];
1493    ZISweeperImpedanceSample dataImpedance[0];
1494  } data;
1495};
1496
1497#ifndef __cplusplus
1498typedef struct ZISweeperWave ZISweeperWave;
1499#endif
1500
1501struct ZISpectrumDemodSample {
1502  /// Grid
1503  double grid;
1504
1505  /// Filter strength at the specific grid point
1506  double filter;
1507
1508  /// X
1509  double x;
1510
1511  /// Y
1512  double y;
1513
1514  /// R
1515  double r;
1516};
1517
1518#ifndef __cplusplus
1519typedef struct ZISpectrumDemodSample ZISpectrumDemodSample;
1520#endif
1521
1522struct ZISpectrumHeader {
1523  /// Total sample count considered for spectrum
1524  uint64_t sampleCount;
1525
1526// --- 8 bytes border
1527  /// Flags
1528  ///   Bit 0: Power
1529  ///   Bit 1: Spectral density
1530  ///   Bit 2: Absolute frequency
1531  ///   Bit 3: Full span
1532  uint8_t flags;
1533
1534  /// Sample format
1535  /// Demodulator = 0.
1536  uint8_t sampleFormat;
1537
1538  /// Spectrum mode
1539  /// FFT(x+iy) = 0, FFT(r) = 1, FFT(theta) = 2, FFT(freq) = 3, FFT(dtheta/dt)/2pi = 4
1540  uint8_t spectrumMode;
1541
1542  /// Window
1543  /// Rectangular = 0, Hann = 1, Hamming = 2, Blackman Harris = 3,
1544  /// Exponential = 16 (ring-down), Cosine = 17 (ring-down), Cosine squared = 18 (ring-down)
1545  uint8_t window;
1546
1547  /// Reserved space for future use
1548  uint8_t reserved0[4];
1549
1550// --- 8 bytes border
1551  /// Reserved space for future use
1552  uint8_t reserved1[8];
1553
1554// --- 8 bytes border
1555  /// Filter bandwidth
1556  double bandwidth;
1557
1558// --- 8 bytes border
1559  /// Rate of the sampled data
1560  double rate;
1561
1562// --- 8 bytes border
1563  /// FFT center value
1564  double center;
1565
1566// --- 8 bytes border
1567  /// FFT bin resolution
1568  double resolution;
1569
1570// --- 8 bytes border
1571  /// Aliasing reject (dB)
1572  double aliasingReject;
1573
1574// --- 8 bytes border
1575  /// Correction factor for the used window when calculating spectral density
1576  double nenbw;
1577
1578// --- 8 bytes border
1579  /// FFT overlap [0 .. 1[
1580  double overlap;
1581};
1582
1583#ifndef __cplusplus
1584typedef struct ZISpectrumHeader ZISpectrumHeader;
1585#endif
1586
1587struct ZISpectrumWave {
1588  /// Time stamp at which the data was updated
1589  ZITimeStamp timeStamp;
1590
1591// --- 8 bytes border
1592  ZISpectrumHeader header;
1593
1594// --- 8 bytes border
1595  /// Spectrum data vector
1596  union {
1597    ZISpectrumDemodSample dataDemod[0];
1598  } data;
1599};
1600
1601#ifndef __cplusplus
1602typedef struct ZISpectrumWave ZISpectrumWave;
1603#endif
1604
1605struct ZIAdvisorSample {
1606  /// Grid
1607  double grid;
1608
1609  /// X
1610  double x;
1611
1612  /// Y
1613  double y;
1614};
1615
1616#ifndef __cplusplus
1617typedef struct ZIAdvisorSample ZIAdvisorSample;
1618#endif
1619
1620struct ZIAdvisorHeader {
1621  /// Total sample count considered for advisor
1622  uint64_t sampleCount;
1623
1624// --- 8 bytes border
1625  /// Flags
1626  uint8_t flags;
1627
1628  /// Sample format
1629  /// Bode = 0, Step = 1, Impulse = 2.
1630  uint8_t sampleFormat;
1631
1632  /// Reserved space for future use
1633  uint8_t reserved0[6];
1634
1635// --- 8 bytes border
1636  /// Reserved space for future use
1637  uint8_t reserved1[8];
1638
1639};
1640
1641#ifndef __cplusplus
1642typedef struct ZIAdvisorHeader ZIAdvisorHeader;
1643#endif
1644
1645struct ZIAdvisorWave {
1646  /// Time stamp at which the data was updated
1647  ZITimeStamp timeStamp;
1648
1649// --- 8 bytes border
1650  ZIAdvisorHeader header;
1651
1652// --- 8 bytes border
1653  /// Advisor data vector
1654  union {
1655    ZIAdvisorSample data[0];
1656  } data;
1657};
1658
1659#ifndef __cplusplus
1660typedef struct ZIAdvisorWave ZIAdvisorWave;
1661#endif
1662
1663/// Enumerates all the types that a ZIVectorData::elementType may have.
1664enum ZIVectorElementType_enum {
1665  ZI_VECTOR_ELEMENT_TYPE_UINT8  = 0,
1666  ZI_VECTOR_ELEMENT_TYPE_UINT16 = 1,
1667  ZI_VECTOR_ELEMENT_TYPE_UINT32 = 2,
1668  ZI_VECTOR_ELEMENT_TYPE_UINT64 = 3,
1669  ZI_VECTOR_ELEMENT_TYPE_FLOAT  = 4,
1670  ZI_VECTOR_ELEMENT_TYPE_DOUBLE = 5,
1671  ZI_VECTOR_ELEMENT_TYPE_ASCIIZ = 6,  // NULL-terminated string
1672  ZI_VECTOR_ELEMENT_TYPE_COMPLEX_FLOAT = 7,
1673  ZI_VECTOR_ELEMENT_TYPE_COMPLEX_DOUBLE = 8
1674};
1675
1676#ifndef __cplusplus
1677typedef enum ZIVectorElementType_enum ZIVectorElementType_enum;
1678#endif
1679
1680/// The structure used to hold vector data block. See the description of the structure members for details.
1681struct ZIVectorData {
1682// --- 8 bytes border
1683    /// Time stamp of this array data block
1684    ZITimeStamp timeStamp;
1685
1686// --- 8 bytes border
1687    /// Current array transfer sequence number. Incremented for each new transfer. Stays same for all blocks of
1688    /// a single array transfer.
1689    uint32_t sequenceNumber;
1690
1691    /// Current block number from the beginning of an array transfer.
1692    /// Large array transfers are split into blocks, which need to be concatenated to obtain the complete array.
1693    uint32_t blockNumber;
1694
1695// --- 8 bytes border
1696    /// Total number of elements in the array
1697    uint64_t totalElements;
1698
1699// --- 8 bytes border
1700    /// Offset of the current block first element from the beginning of the array
1701    uint64_t blockOffset;
1702
1703// --- 8 bytes border
1704    /// Number of elements in the current block
1705    uint32_t blockElements;
1706
1707    /// Block marker:
1708    ///   Bit (0): 1 = End marker for multi-block transfer
1709    ///   Bit (1): 1 = Transfer failure
1710    ///   Bit (7..2): Reserved
1711    uint8_t flags;
1712
1713    /// Vector element type, see ::ZIVectorElementType_enum
1714    uint8_t elementType;
1715
1716    uint8_t reserved0[2];
1717
1718// --- 8 bytes border
1719    /// For internal use only
1720    uint32_t extraHeaderInfo;
1721
1722    uint8_t reserved1[4];
1723
1724// --- 8 bytes border
1725    uint64_t reserved2[31];
1726
1727// --- 8 bytes border
1728    /// First data element of the current block
1729    union {
1730      uint8_t dataUInt8[0];
1731      uint16_t dataUInt16[0];
1732      uint32_t dataUInt32[0];
1733      uint64_t dataUInt64[0];
1734      int8_t dataInt8[0];
1735      int16_t dataInt16[0];
1736      int32_t dataInt32[0];
1737      int64_t dataInt64[0];
1738      double dataDouble[0];
1739      float dataFloat[0];
1740    } data;
1741
1742};
1743
1744#ifndef __cplusplus
1745typedef struct ZIVectorData ZIVectorData;
1746#endif
1747
1748#ifdef _MSC_VER
1749// Visual C++ specific
1750#pragma warning(pop)
1751#endif
1752
1753
1754struct ZIAsyncReply {
1755// --- 8 bytes border
1756  /// Time stamp of the reply (server clock)
1757  ZITimeStamp timeStamp;
1758
1759// --- 8 bytes border
1760  /// Time stamp of the target node sample, to which the reply belongs
1761  ZITimeStamp sampleTimeStamp;
1762
1763// --- 8 bytes border
1764  /// Command:
1765  ///   1 - ziAPIAsyncSetDoubleData
1766  ///   2 - ziAPIAsyncSetIntegerData
1767  ///   3 - ziAPIAsyncSetByteArray
1768  ///   4 - ziAPIAsyncSubscribe
1769  ///   5 - ziAPIAsyncUnSubscribe
1770  ///   6 - ziAPIAsyncGetValueAsPollData
1771  uint16_t command;
1772
1773  /// Command result code (cast to ZIResult_enum)
1774  uint16_t resultCode;
1775
1776  /// Tag sent along with the async command
1777  ZIAsyncTag tag;
1778// --- 8 bytes border
1779};
1780
1781#ifndef __cplusplus
1782typedef struct ZIAsyncReply ZIAsyncReply;
1783#endif
1784
1785
1786/** @defgroup Connection Connecting to Data Server
1787 *  @brief This section describes how to initialize the ZIConnection and establish a connection to Data Server as well
1788 *         as how to disconnect after all data handling is done and cleanup the ZIConnection.
1789 *  @{
1790 */
1791
1792enum ZIAPIVersion_enum {
1793  ZI_API_VERSION_0 = 0,
1794  ZI_API_VERSION_1 = 1,
1795  ZI_API_VERSION_4 = 4,
1796  ZI_API_VERSION_5 = 5,
1797  ZI_API_VERSION_6 = 6,
1798  ZI_API_VERSION_MAX = ZI_API_VERSION_6
1799};
1800
1801#ifndef __cplusplus
1802typedef enum ZIAPIVersion_enum ZIAPIVersion_enum;
1803#endif
1804
1805
1806/// The ZIConnection is a connection reference; it holds information and helper variables about a connection to
1807/// the Data Server. There is nothing in this reference which the user user may use, so it is hidden and instead
1808/// an opaque pointer is used.  See ::ziAPIInit for how to create a ZIConnection.
1809typedef struct ZIConnectionProxy* ZIConnection;
1810
1811/// Initializes a ::ZIConnection structure.
1812/** This function initializes the structure so that it is ready to connect to Data Server. It allocates memory and sets
1813    up the infrastructure needed.
1814
1815    @param[out]  conn  Pointer to ::ZIConnection that is to be initialized
1816    @return
1817    - ZI_INFO_SUCCESS  on success
1818    - ZI_ERROR_MALLOC  on memory allocation failure
1819    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1820
1821    See @link Connection Connection @endlink for an example
1822    @sa ziAPIDestroy, ziAPIConnect, ziAPIDisconnect
1823 */
1824ZI_EXPORT ZIResult_enum ziAPIInit(ZIConnection* conn);
1825
1826/// Destroys a ::ZIConnection structure.
1827/** This function frees all memory that has been allocated by ::ziAPIInit. If it is called with an uninitialized
1828    ::ZIConnection struct it may result in segmentation faults as well when it is called with a struct for which
1829    ZIAPIDestroy already has been called.
1830
1831    @param[in] conn Pointer to ::ZIConnection struct that has to be destroyed
1832    @return
1833    - ZI_INFO_SUCCESS
1834    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1835
1836    See @link Connection Connection @endlink for an example
1837    @sa ziAPIInit, ziAPIConnect, ziAPIDisconnect
1838 */
1839ZI_EXPORT ZIResult_enum ziAPIDestroy(ZIConnection conn);
1840
1841/// Connects the ZIConnection to Data Server.
1842/** Connects to Data Server using a ::ZIConnection and prepares for data exchange. For most cases it is enough to just
1843    give a reference to the connection and give NULL for hostname and 0 for the port, so it connects to localhost
1844    on the default port.
1845
1846    @param[in]   conn      Pointer to ::ZIConnection with which the connection should be established
1847    @param[in]   hostname  Name of the Host to which it should be connected, if NULL "localhost" will be used as
1848                           default
1849    @param[in]   port      The Number of the port to connect to. If 0, default port of the local Data Server will be
1850                           used (8005)
1851    @return
1852    - ZI_INFO_SUCCESS          on success
1853    - ZI_ERROR_CONNECTION      when the Data Server didn't return the correct answer
1854    - ZI_ERROR_TIMEOUT         when initial communication timed out
1855    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1856
1857    See @link Connection Connection @endlink for an example
1858    @sa ziAPIDisconnect, ziAPIInit, ziAPIDestroy
1859 */
1860ZI_EXPORT ZIResult_enum ziAPIConnect(ZIConnection conn, const char* hostname, uint16_t port);
1861
1862/// Disconnects an established connection.
1863/** Disconnects from Data Server. If the connection has not been established and the function is called it returns
1864    without doing anything.
1865
1866    @param[in]   conn  Pointer to ZIConnection to be disconnected
1867    @return
1868    - ZI_INFO_SUCCESS
1869    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1870
1871    See @link Connection Connection @endlink for an example
1872    @sa ziAPIConnect, ziAPIInit, ziAPIDestroy
1873 */
1874ZI_EXPORT ZIResult_enum ziAPIDisconnect(ZIConnection conn);
1875
1876/// Returns the list of supported implementations. Deprecated.
1877/**
1878    @deprecated
1879    Returned names are defined by implementations in the linked library and may change depending on software version.
1880
1881     @param[out] implementations  Pointer to a buffer receiving a newline-delimited list of the names of all
1882                                  the supported ziAPI implementations. The string is zero-terminated.
1883     @param[in]  bufferSize       The size of the buffer assigned to the implementations parameter
1884     @return
1885     - ZI_INFO_SUCCESS            on success
1886     - ZI_ERROR_LENGTH            if the length of the char-buffer given by MaxLen is too small for all elements
1887     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1888
1889     @sa ziAPIConnectEx
1890 */
1891DEPRECATED(ZI_EXPORT ZIResult_enum ziAPIListImplementations(char* implementations, uint32_t bufferSize));
1892
1893/// Connects to Data Server and enables extended ziAPI.
1894/**
1895    With apiLevel=ZI_API_VERSION_1 and implementation=NULL, this call is equivalent to plain ::ziAPIConnect.
1896    With other version and implementation values enables corresponding ziAPI extension and connection using
1897    different implementation.
1898
1899     @param[in]  conn            Pointer to the ZIConnection with which the connection should be established
1900     @param[in]  hostname        Name of the host to which it should be connected, if NULL "localhost" will be used
1901                                 as default
1902     @param[in]  port            The number of the port to connect to. If 0 the port of the local Data Server
1903                                 will be used
1904     @param[in]  apiLevel        Specifies the ziAPI compatibility level to use for this connection (1 or 4).
1905     @param[in]  implementation  Specifies implementation to use for a connection. NULL selects the default
1906                                 implementation (recommended).
1907     @return
1908     - ZI_INFO_SUCCESS           on success
1909     - ZI_ERROR_CONNECTION       when the Data Server didn't return the correct answer or requested implementation
1910                                 is not found or doesn't support requested ziAPI level
1911     - ZI_ERROR_TIMEOUT          when initial communication timed out
1912     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1913
1914     See @link Connection Connection @endlink for an example
1915     @sa ziAPIConnect, ziAPIDisconnect, ziAPIInit, ziAPIDestroy, ziAPIGetConnectionVersion
1916 */
1917ZI_EXPORT ZIResult_enum ziAPIConnectEx(ZIConnection conn, const char* hostname, uint16_t port,
1918                                       ZIAPIVersion_enum apiLevel, const char* implementation);
1919
1920/// Returns ziAPI level used for the connection conn.
1921/**
1922     @param[in]  conn       Pointer to ZIConnection
1923     @param[out] apiLevel   Pointer to preallocated ZIAPIVersion_enum, receiving the ziAPI level
1924     @return
1925     - ZI_INFO_SUCCESS      on success
1926     - ZI_ERROR_CONNECTION  if level can not be determined due to conn is not connected
1927
1928     @sa ziAPIConnectEx, ziAPIGetVersion, ziAPIGetCommitHash, ziAPIGetRevision
1929 */
1930ZI_EXPORT ZIResult_enum ziAPIGetConnectionAPILevel(ZIConnection conn, ZIAPIVersion_enum* apiLevel);
1931
1932/// Retrieves the release version of ziAPI
1933/** Sets the passed pointer to point to the null-terminated release version string of ziAPI.
1934
1935    @param[in]   version  Pointer to const char pointer.
1936    @return
1937    - ZI_INFO_SUCCESS
1938    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1939
1940     @sa ziAPIConnectEx, ziAPIGetRevision, ziAPIGetCommitHash, ziAPIGetConnectionAPILevel
1941*/
1942ZI_EXPORT ZIResult_enum ziAPIGetVersion(const char** version);
1943
1944/// Retrieves the exact commit hash key of ziAPI
1945/** Sets the passed pointer to point to the null-terminated commit hash string of ziAPI.
1946
1947    @param[in]   commitHash  Pointer to const char pointer.
1948    @return
1949    - ZI_INFO_SUCCESS
1950    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1951
1952     @sa ziAPIConnectEx, ziAPIGetRevision, ziAPIGetVersion, ziAPIGetConnectionAPILevel
1953*/
1954ZI_EXPORT ZIResult_enum ziAPIGetCommitHash(const char** commitHash);
1955
1956/// Retrieves the version and build number of ziAPI
1957/** Sets an unsigned int with the version and build number of the ziAPI you are using.
1958
1959    The number is a packed representation of YY.MM.BUILD as a 32-bit unsigned integer:
1960    (YY << 24) | (MM << 16) | BUILD.
1961
1962    Note: prior to LabOne 19.10, the packed representation did not contain YY.MM.
1963
1964    @param[in]   revision  Pointer to an unsigned int to fill up with the packed version number.
1965    @return
1966    - ZI_INFO_SUCCESS
1967    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
1968
1969    @sa ziAPIConnectEx, ziAPIGetVersion, ziAPIGetCommitHash, ziAPIGetConnectionAPILevel
1970 */
1971ZI_EXPORT ZIResult_enum ziAPIGetRevision(uint32_t* revision);
1972
1973
1974/** @} */  // end of group Connection
1975
1976
1977/** @defgroup TreeListing Tree
1978 *  @brief All parameters and streams are organized in a tree. You can list the whole tree, parts of it or single items
1979 *         using ::ziAPIListNodes or you may update the tree with nodes of newly connected devices by using
1980 *         ::ziAPIUpdateDevices.
1981 *  @{
1982 */
1983
1984/// Defines the values of the flags used in ::ziAPIListNodes
1985enum ZIListNodes_enum {
1986  /// Default, return a simple listing of the given node immediate descendants.
1987  ZI_LIST_NODES_ALL = 0x00,
1988  /// List the nodes recursively
1989  ZI_LIST_NODES_RECURSIVE = 0x01,
1990  /// Return absolute paths
1991  ZI_LIST_NODES_ABSOLUTE = 0x02,
1992  /// Return only leaf nodes, which means the nodes at the outermost level of the tree
1993  ZI_LIST_NODES_LEAVESONLY = 0x04,
1994  /// Return only nodes which are marked as setting
1995  ZI_LIST_NODES_SETTINGSONLY = 0x08,
1996  /// Return only streaming nodes (nodes that can be pushed from the device at a high data rate)
1997  ZI_LIST_NODES_STREAMINGONLY = 0x10,
1998  /// Return only nodes that are subscribed to in the API session
1999  ZI_LIST_NODES_SUBSCRIBEDONLY = 0x20,
2000  /// Return only one instance of a node in case of multiple channels
2001  ZI_LIST_NODES_BASECHANNEL = 0x40,
2002  /// Return only nodes which can be used with the get command
2003  ZI_LIST_NODES_GETONLY = 0x80,
2004  /// Exclude streaming nodes
2005  ZI_LIST_NODES_EXCLUDESTREAMING = 0x100000,
2006  /// Exclude node vectors
2007  ZI_LIST_NODES_EXCLUDEVECTORS = 0x1000000,
2008  /// @cond deprecated
2009  // **********
2010  /// Alias for ZI_LIST_NODES_ALL, no flags specified.
2011  ZI_LIST_NODES_NONE = 0x00,
2012  /// Alias for ZI_LIST_NODES_LEAVESONLY.
2013  ZI_LIST_NODES_LEAFSONLY = 0x04
2014#ifdef _MSC_VER
2015  ,
2016  // Default, return a simple listing of the given node immediate descendants.
2017  ZI_LIST_NONE           = 0x00,
2018  // List the nodes recursively
2019  ZI_LIST_RECURSIVE      = 0x01,
2020  // Return absolute paths
2021  ZI_LIST_ABSOLUTE       = 0x02,
2022  // Return only leaf nodes, which means the nodes at the outermost level of the tree
2023  ZI_LIST_LEAFSONLY      = 0x04,
2024  // Return only nodes which are marked as setting
2025  ZI_LIST_SETTINGSONLY   = 0x08
2026#endif
2027  /// @endcond
2028};
2029
2030#ifndef __cplusplus
2031typedef enum ZIListNodes_enum ZIListNodes_enum;
2032#endif
2033
2034#ifdef _MSC_VER
2035#pragma deprecated(ZI_LIST_NONE)
2036#pragma deprecated(ZI_LIST_RECURSIVE)
2037#pragma deprecated(ZI_LIST_ABSOLUTE)
2038#pragma deprecated(ZI_LIST_LEAFSONLY)
2039#pragma deprecated(ZI_LIST_SETTINGSONLY)
2040#else
2041
2042#ifdef __cplusplus
2043#define ZIListNodes_enum_cast(val) ZIListNodes_enum(val)
2044#else
2045#define ZIListNodes_enum_cast(val) val
2046#endif
2047
2048DEPRECATED_ENUM(const ZIListNodes_enum ZI_LIST_NONE           = ZIListNodes_enum_cast(0x00));
2049DEPRECATED_ENUM(const ZIListNodes_enum ZI_LIST_RECURSIVE      = ZIListNodes_enum_cast(0x01));
2050DEPRECATED_ENUM(const ZIListNodes_enum ZI_LIST_ABSOLUTE       = ZIListNodes_enum_cast(0x02));
2051DEPRECATED_ENUM(const ZIListNodes_enum ZI_LIST_LEAFSONLY      = ZIListNodes_enum_cast(0x04));
2052DEPRECATED_ENUM(const ZIListNodes_enum ZI_LIST_SETTINGSONLY   = ZIListNodes_enum_cast(0x08));
2053#endif
2054
2055/// Returns all child nodes found at the specified path
2056/** This function returns a list of node names found at the specified path. The path may contain wildcards so that
2057    the returned nodes do not necessarily have to have the same parents. The list is returned in a null-terminated
2058    char-buffer, each element delimited by a newline. If the maximum length of the buffer (bufferSize) is not
2059    sufficient for all elements, nothing will be returned and the return value will be ZIResult_enum::ZI_LENGTH.
2060
2061    @param[in]   conn        Pointer to the ZIConnection for which the node names should be retrieved.
2062    @param[in]   path        Path for which all children will be returned. The path may contain wildcard characters.
2063    @param[out]  nodes       Upon call filled with newline-delimited list of the names of all the children found.
2064                             The string is zero-terminated.
2065    @param[in]   bufferSize  The length of the buffer used for the nodes output parameter.
2066    @param[in]   flags       A combination of flags (applied bitwise) as defined in ::ZIListNodes_enum.
2067
2068    @return
2069    - ZI_INFO_SUCCESS           on success
2070    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2071    - ZI_ERROR_LENGTH           if the path's length exceeds ::MAX_PATH_LEN or the length of the char-buffer for the
2072                                nodes given by bufferSize is too small for all elements
2073    - ZI_ERROR_COMMAND          on an incorrect answer of the server
2074    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
2075    - ZI_WARNING_NOTFOUND       if the given path could not be resolved
2076    - ZI_ERROR_TIMEOUT          when communication timed out
2077    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2078
2079    See @link TreeListing Tree Listing @endlink for an example
2080
2081    @sa ziAPIUpdate
2082 */
2083ZI_EXPORT ZIResult_enum ziAPIListNodes(ZIConnection conn, const char* path, char* nodes, uint32_t bufferSize,
2084                                       uint32_t flags);
2085
2086/// Returns all child nodes found at the specified path
2087/** This function returns a list of node names found at the specified path, formatted as JSON. The path may
2088    contain wildcards so that the returned nodes do not necessarily have to have the same parents.
2089    The list is returned in a null-terminated char-buffer. If the maximum length of the buffer (bufferSize) is not
2090    sufficient for all elements, nothing will be returned and the return value will be ZIResult_enum::ZI_LENGTH.
2091
2092    @param[in]   conn        Pointer to the ZIConnection for which the node names should be retrieved.
2093    @param[in]   path        Path for which all children will be returned. The path may contain wildcard characters.
2094    @param[out]  nodes       Upon call filled with JSON-formatted list of the names of all the children found.
2095                             The string is zero-terminated.
2096    @param[in]   bufferSize  The length of the buffer used for the nodes output parameter.
2097    @param[in]   flags       A combination of flags (applied bitwise) as defined in ::ZIListNodes_enum.
2098
2099    @return
2100    - ZI_INFO_SUCCESS           on success
2101    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2102    - ZI_ERROR_LENGTH           if the path's length exceeds ::MAX_PATH_LEN or the length of the char-buffer for the
2103                                nodes given by bufferSize is too small for all elements
2104    - ZI_ERROR_COMMAND          on an incorrect answer of the server
2105    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
2106    - ZI_WARNING_NOTFOUND       if the given path could not be resolved
2107    - ZI_ERROR_TIMEOUT          when communication timed out
2108    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2109
2110    See @link TreeListing Tree Listing @endlink for an example
2111
2112    @sa ziAPIUpdate
2113 */
2114ZI_EXPORT ZIResult_enum ziAPIListNodesJSON(ZIConnection conn, const char* path, char* nodes, uint32_t bufferSize,
2115                                           uint32_t flags);
2116
2117/** @} */  // end of group TreeListing
2118
2119/// Search for the newly connected devices and update the tree
2120/** This function forces the Data Server to search for newly connected devices and to connect to run them
2121
2122    @param[in]   conn  Pointer to ZIConnection
2123    @return
2124    - ZI_INFO_SUCCESS
2125    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2126
2127    @sa ziAPIListNodes
2128 */
2129ZI_EXPORT ZIResult_enum ziAPIUpdateDevices(ZIConnection conn);
2130
2131/// Connect a device to the server.
2132/** This function connects a device with deviceSerial via the specified deviceInterface for use with the server.
2133
2134    @param[in]  conn            Pointer to the ZIConnection with which the connection should be established
2135    @param[in]  deviceSerial    The serial of the device to connect to, e.g., dev2100
2136    @param[in]  deviceInterface The interface to use for the connection, e.g., USB|1GbE
2137    @param[in]  interfaceParams Parameters for interface configuration (currently reserved for future use,
2138                                NULL may be specified).
2139
2140    @return
2141    - ZI_INFO_SUCCESS           on success
2142    - ZI_ERROR_TIMEOUT          when communication timed out
2143    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2144
2145    @sa ziAPIDisconnectDevice, ziAPIConnect, ziAPIDisconnect, ziAPIInit
2146 */
2147ZI_EXPORT ZIResult_enum ziAPIConnectDevice(ZIConnection conn, const char* deviceSerial,
2148                                           const char* deviceInterface, const char* interfaceParams);
2149
2150/// Disconnect a device from the server.
2151/** This function disconnects a device specified by deviceSerial from the server.
2152
2153    @param[in]  conn            Pointer to the ZIConnection with which the connection should be established
2154    @param[in]  deviceSerial    The serial of the device to connect to, e.g., dev2100
2155
2156    @return
2157    - ZI_INFO_SUCCESS           on success
2158    - ZI_ERROR_TIMEOUT          when communication timed out
2159    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2160
2161    @sa ziAPIConnectDevice, ziAPIConnect, ziAPIDisconnect, ziAPIInit
2162 */
2163ZI_EXPORT ZIResult_enum ziAPIDisconnectDevice(ZIConnection conn, const char* deviceSerial);
2164
2165/** @defgroup Parameters Set and Get Parameters
2166 *  @brief This section describes several functions for getting and setting parameters of different datatypes.
2167 *  @{
2168 */
2169
2170/// gets the double-type value of the specified node
2171/** This function retrieves the numerical value of the specified node as an double-type value. The value first found
2172    is returned if more than one value is available (a wildcard is used in the path).
2173
2174    @param[in]   conn   Pointer to ZIConnection with which the value should be retrieved
2175    @param[in]   path   Path to the node holding the value
2176    @param[out]  value  Pointer to a double in which the value should be written
2177    @return
2178    - ZI_INFO_SUCCESS           on success
2179    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2180    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
2181    - ZI_ERROR_COMMAND          on an incorrect answer of the server
2182    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
2183    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the node
2184    - ZI_ERROR_TIMEOUT          when communication timed out
2185    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2186
2187    @include ExampleSetGet.cpp
2188
2189    @sa ziAPISetValueD, ziAPIGetValueAsPollData
2190 */
2191
2192ZI_EXPORT ZIResult_enum ziAPIGetValueD(ZIConnection conn, const char* path, ZIDoubleData* value);
2193
2194/// gets the complex double-type value of the specified node
2195/** This function retrieves the numerical value of the specified node as an complex double-type value.
2196    The value first found is returned if more than one value is available (a wildcard is used in the path).
2197
2198    @param[in]   conn   Pointer to ZIConnection with which the value should be retrieved
2199    @param[in]   path   Path to the node holding the value
2200    @param[out]  real   Pointer to a double in which the real value should be written
2201    @param[out]  imag   Pointer to a double in which the imaginary value should be written
2202    @return
2203    - ZI_INFO_SUCCESS           on success
2204    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2205    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
2206    - ZI_ERROR_COMMAND          on an incorrect answer of the server
2207    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
2208    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the node
2209    - ZI_ERROR_TIMEOUT          when communication timed out
2210    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2211
2212    @include ExampleSetGet.cpp
2213
2214    @sa ziAPISetComplexData, ziAPIGetValueAsPollData
2215 */
2216
2217ZI_EXPORT ZIResult_enum ziAPIGetComplexData(ZIConnection conn, const char* path, ZIDoubleData* real, ZIDoubleData* imag);
2218
2219
2220/// gets the integer-type value of the specified node
2221/** This function retrieves the numerical value of the specified node as an integer-type value. The value first
2222    found is returned if more than one value is available (a wildcard is used in the path).
2223
2224    @param[in]   conn   Pointer to ZIConnection with which the value should be retrieved
2225    @param[in]   path   Path to the node holding the value
2226    @param[out]  value  Pointer to an 64bit integer in which the value should be written
2227    @return
2228    - ZI_INFO_SUCCESS           on success
2229    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2230    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
2231    - ZI_ERROR_COMMAND          on an incorrect answer of the server
2232    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
2233    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the node
2234    - ZI_ERROR_TIMEOUT          when communication timed out
2235    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2236
2237    @sa ziAPISetValueI, ziAPIGetValueAsPollData
2238 */
2239ZI_EXPORT ZIResult_enum ziAPIGetValueI(ZIConnection conn, const char* path, ZIIntegerData* value);
2240
2241/// Gets the demodulator sample value of the specified node
2242/** This function retrieves the value of the specified node as an DemodSample struct. The value first found is
2243    returned if more than one value is available (a wildcard is used in the path). This function is only applicable
2244    to paths matching DEMODS/[0-9]+/SAMPLE.
2245
2246    @param[in]   conn   Pointer to ZIConnection with which the value should be retrieved
2247    @param[in]   path   Path to the node holding the value
2248    @param[out]  value  Pointer to a ZIDemodSample struct in which the value should be written
2249    @return
2250    - ZI_INFO_SUCCESS           on success
2251    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2252    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
2253    - ZI_ERROR_COMMAND          on an incorrect answer of the server
2254    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
2255    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the node
2256    - ZI_ERROR_TIMEOUT          when communication timed out
2257    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2258
2259    @sa ziAPIGetValueAsPollData
2260 */
2261ZI_EXPORT ZIResult_enum ziAPIGetDemodSample(ZIConnection conn, const char* path, ZIDemodSample* value);
2262
2263/// Gets the Digital I/O sample of the specified node
2264/** This function retrieves the newest available DIO sample from the specified node. The value first found
2265    is returned if more than one value is available (a wildcard is used in the path). This function is only
2266    applicable to nodes ending in "/DIOS/[0-9]+/INPUT".
2267
2268    @param[in]   conn   Pointer to the ZIConnection with which the value should be retrieved
2269    @param[in]   path   Path to the node holding the value
2270    @param[out]  value  Pointer to a ZIDIOSample struct in which the value should be written
2271    @return
2272     - ZI_INFO_SUCCESS           on success
2273     - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2274     - ZI_ERROR_LENGTH           if the Path's Length exceeds MAX_PATH_LEN or the length of the char-buffer for
2275                                 the nodes given by MaxLen is too small for all elements
2276     - ZI_ERROR_COMMAND          on an incorrect answer of the server
2277     - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in the Data Server
2278     - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the node
2279     - ZI_ERROR_TIMEOUT          when communication timed out
2280     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2281
2282    @sa ziAPIGetValueAsPollData
2283 */
2284ZI_EXPORT ZIResult_enum ziAPIGetDIOSample(ZIConnection conn, const char* path, ZIDIOSample* value);
2285
2286/// gets the AuxIn sample of the specified node
2287/** This function retrieves the newest available AuxIn sample from the specified node. The value first found
2288    is returned if more than one value is available (a wildcard is used in the path). This function is only
2289    applicable to nodes ending in "/AUXINS/[0-9]+/SAMPLE".
2290
2291    @param[in] conn Pointer to the ziConnection with which the Value should be retrieved
2292    @param[in] path Path to the Node holding the value
2293    @param[out] value Pointer to an ZIAuxInSample struct in which the value should be written
2294    @return
2295     - ZI_INFO_SUCCESS           on success
2296     - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2297     - ZI_ERROR_LENGTH           if the Path's Length exceeds MAX_PATH_LEN or the length of the char-buffer for the
2298                                 nodes given by MaxLen is too small for all elements
2299     - ZI_ERROR_COMMAND          on an incorrect answer of the server
2300     - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in the Data Server
2301     - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the node
2302     - ZI_ERROR_TIMEOUT          when communication timed out
2303     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2304
2305    @sa ziAPIGetValueAsPollData
2306 */
2307ZI_EXPORT ZIResult_enum ziAPIGetAuxInSample(ZIConnection conn, const char* path, ZIAuxInSample* value);
2308
2309  /// gets the Bytearray value of the specified node
2310  /**
2311     This function retrieves the newest available DIO sample from the specified node. The value first found
2312     is returned if more than one value is available (a wildcard is used in the path).
2313
2314     @param[in]  conn           Pointer to the ziConnection with which the value should be retrieved
2315     @param[in]  path           Path to the Node holding the value
2316     @param[out] buffer         Pointer to a buffer to store the retrieved data in
2317     @param[out] length         Pointer to an unsigned int which after the call, contains the length of
2318                                the retrieved data. If the length of the passed buffer is insufficient,
2319                                the value is modified to indicate the required minimum buffer size and
2320                                ZI_ERROR_LENGTH is returned.
2321     @param[in]  bufferSize     The length of the passed buffer
2322
2323     @return
2324     - ZI_INFO_SUCCESS          on success.
2325     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2326     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN or the length of the char-buffer for
2327                                the nodes given by MaxLen is too small for all elements.
2328     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2329     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2330     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no value is attached to the node
2331     - ZI_ERROR_TIMEOUT         when communication timed out
2332     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2333
2334     @sa ziAPISetValueB, ziAPIGetValueAsPollData
2335
2336  */
2337ZI_EXPORT ZIResult_enum ziAPIGetValueB(ZIConnection conn, const char* path, unsigned char* buffer,
2338                                       unsigned int* length, unsigned int bufferSize);
2339
2340  /// gets a null-terminated string value of the specified node
2341  /**
2342     This function retrieves the newest string value for the specified node. The value first found
2343     is returned if more than one value is available (a wildcard is used in the path).
2344
2345     @param[in]  conn           Pointer to the ziConnection with which the value should be retrieved
2346     @param[in]  path           Path to the Node holding the value
2347     @param[out] buffer         Pointer to a buffer to store the retrieved null-terminated string
2348     @param[out] length         Pointer to an unsigned int which after the call, contains the length of
2349                                the retrieved data (including the null terminator). If the length of the
2350                                passed buffer is insufficient, the value is modified to indicate the
2351                                required minimum buffer size and ZI_ERROR_LENGTH is returned.
2352
2353     @param[in]  bufferSize     The length of the passed buffer
2354
2355     @return
2356     - ZI_INFO_SUCCESS          on success.
2357     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2358     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN or the length of the char-buffer for
2359                                the nodes given by MaxLen is too small for all elements.
2360     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2361     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2362     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no value is attached to the node
2363     - ZI_ERROR_TIMEOUT         when communication timed out
2364     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2365
2366     @sa ziAPISetValueString, ziAPIGetValueAsPollData
2367
2368  */
2369ZI_EXPORT ZIResult_enum ziAPIGetValueString(ZIConnection conn, const char* path, char* buffer,
2370                                            unsigned int* length, unsigned int bufferSize);
2371
2372  /// gets a null-terminated string value of the specified node
2373  /**
2374     This function retrieves the newest unicode string value for the specified node. The value first found
2375     is returned if more than one value is available (a wildcard is used in the path).
2376
2377     @param[in]  conn           Pointer to the ziConnection with which the value should be retrieved
2378     @param[in]  path           Path to the Node holding the value
2379     @param[out] wbuffer        Pointer to a buffer to store the retrieved null-terminated string
2380     @param[out] length         Pointer to an unsigned int which after the call, contains the length of
2381                                the retrieved data (including the null terminator). If the length of the
2382                                passed buffer is insufficient, the value is modified to indicate the
2383                                required minimum buffer size and ZI_ERROR_LENGTH is returned.
2384     @param[in]  bufferSize     The length of the passed buffer
2385
2386     @return
2387     - ZI_INFO_SUCCESS          on success.
2388     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2389     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN or the length of the char-buffer for
2390                                the nodes given by MaxLen is too small for all elements.
2391     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2392     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2393     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no value is attached to the node
2394     - ZI_ERROR_TIMEOUT         when communication timed out
2395     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2396
2397     @sa ziAPISetValueStringUnicode, ziAPIGetValueAsPollData
2398
2399  */
2400ZI_EXPORT ZIResult_enum ziAPIGetValueStringUnicode(ZIConnection conn, const char* path, wchar_t* wbuffer,
2401                                                   unsigned int* length, unsigned int bufferSize);
2402
2403  /// asynchronously sets a double-type value to one or more nodes specified in the path
2404  /**
2405     This function sets the values of the nodes specified in path to Value. More than one value can be set if
2406     a wildcard is used. The function sets the value asynchronously which means that after the function returns
2407     you have no security to which value it is finally set nor at what point in time it is set.
2408
2409     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set.
2410     @param[in] path            Path to the Node(s) for which the value(s) will be set to Value.
2411     @param[in] value           The double-type value that will be written to the node(s).
2412     @return
2413     - ZI_INFO_SUCCESS          on success.
2414     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2415     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN.
2416     - ZI_ERROR_READONLY        on attempt to set a read-only node.
2417     - ZI_ERROR_COMMAND         on an incorrect answer of the server.
2418     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
2419     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able to hold values
2420     - ZI_ERROR_TIMEOUT         when communication timed out.
2421     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2422
2423     @sa ziAPIGetValueD. ziAPISyncSetValueD
2424  */
2425ZI_EXPORT ZIResult_enum ziAPISetValueD(ZIConnection conn, const char* path, ZIDoubleData value);
2426
2427  /// asynchronously sets a double-type complex value to one or more nodes specified in the path
2428/**
2429   This function sets the values of the nodes specified in path to the complex value (real, imag).
2430   More than one value can be set if a wildcard is used. The function sets the value asynchronously
2431   which means that after the function returns you have no security to which value it is finally
2432   set nor at what point in time it is set. If the node does not support complex values only the
2433   real value will be updated.
2434
2435   @param[in] conn            Pointer to the ziConnection for which the value(s) will be set.
2436   @param[in] path            Path to the Node(s) for which the value(s) will be set to Value.
2437   @param[in] real            The real value that will be written to the node(s).
2438   @param[in] imag            The imag value that will be written to the node(s).
2439   @return
2440   - ZI_INFO_SUCCESS          on success.
2441   - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2442   - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN.
2443   - ZI_ERROR_READONLY        on attempt to set a read-only node.
2444   - ZI_ERROR_COMMAND         on an incorrect answer of the server.
2445   - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
2446   - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able to hold values
2447   - ZI_ERROR_TIMEOUT         when communication timed out.
2448   - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2449
2450   @sa ziAPIGetComplexData. ziAPISyncSetComplexData
2451*/
2452ZI_EXPORT ZIResult_enum ziAPISetComplexData(ZIConnection conn, const char* path, ZIDoubleData real, ZIDoubleData imag);
2453
2454
2455  /// asynchronously sets an integer-type value to one or more nodes specified in a path
2456  /**
2457     This function sets the values of the nodes specified in path to Value. More than one value can be set if
2458     a wildcard is used. The function sets the value asynchronously which means that after the function returns
2459     you have no security to which value it is finally set nor at what point in time it is set.
2460
2461     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set
2462     @param[in] path            Path to the Node(s) for which the value(s) will be set
2463     @param[in] value           The int-type value that will be written to the node(s)
2464     @return
2465     - ZI_INFO_SUCCESS          on success.
2466     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2467     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN.
2468     - ZI_ERROR_READONLY        on attempt to set a read-only node.
2469     - ZI_ERROR_COMMAND         on an incorrect answer of the server.
2470     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
2471     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able to hold values
2472     - ZI_ERROR_TIMEOUT         when communication timed out.
2473     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2474
2475     @sa ziAPIGetValueI. ziAPISyncSetValueI
2476
2477  */
2478ZI_EXPORT ZIResult_enum ziAPISetValueI(ZIConnection conn, const char* path, ZIIntegerData value);
2479
2480  /// asynchronously sets the binary-type value of one or more nodes specified in the path
2481  /**
2482     This function sets the values at the nodes specified in a path. More than one value can be set if
2483     a wildcard is used. The function sets the value asynchronously which means that after the function
2484     returns you have no security to which value it is finally set nor at what point in time it is set.
2485
2486     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set
2487     @param[in] path            Path to the Node(s) for which the value(s) will be set
2488     @param[in] buffer          Pointer to the byte array with the data
2489     @param[in] length          Length of the data in the buffer
2490     @return
2491     - ZI_INFO_SUCCESS          on success.
2492     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred.
2493     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN.
2494     - ZI_ERROR_READONLY        on attempt to set a read-only node.
2495     - ZI_ERROR_COMMAND         on an incorrect answer of the server.
2496     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
2497     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able
2498                                to hold values.
2499     - ZI_ERROR_TIMEOUT         when communication timed out.
2500     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2501
2502     @sa ziAPIGetValueB. ziAPISyncSetValueB
2503
2504  */
2505ZI_EXPORT ZIResult_enum ziAPISetValueB(ZIConnection conn, const char* path, unsigned char* buffer, unsigned int length);
2506
2507  /// asynchronously sets a string value of one or more nodes specified in the path
2508  /**
2509     This function sets the values at the nodes specified in a path. More than one value can be set if
2510     a wildcard is used. The function sets the value asynchronously which means that after the function
2511     returns you have no security to which value it is finally set nor at what point in time it is set.
2512
2513     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set
2514     @param[in] path            Path to the Node(s) for which the value(s) will be set
2515     @param[in] str             Pointer to a null terminated string (max 64k characters)
2516     @return
2517     - ZI_INFO_SUCCESS             on success.
2518     - ZI_ERROR_CONNECTION         when the connection is invalid (not connected) or when a communication error occurred.
2519     - ZI_ERROR_LENGTH             if the Path's Length exceeds MAX_PATH_LEN.
2520     - ZI_ERROR_READONLY           on attempt to set a read-only node.
2521     - ZI_ERROR_COMMAND            on an incorrect answer of the server.
2522     - ZI_ERROR_SERVER_INTERNAL    if an internal error occurred in the Data Server.
2523     - ZI_WARNING_NOTFOUND         if the given path could not be resolved or no node given by path is able
2524                                   to hold values.
2525     - ZI_WARNING_INVALID_KEYWORD  if the given keyword could not be resolved
2526     - ZI_ERROR_TIMEOUT            when communication timed out.
2527     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2528
2529     @sa ziAPIGetValueString. ziAPISyncSetValueString
2530
2531  */
2532ZI_EXPORT ZIResult_enum ziAPISetValueString(ZIConnection conn, const char* path, const char* str);
2533
2534  /// asynchronously sets a unicode encoded string value of one or more nodes specified in the path
2535  /**
2536     This function sets the values at the nodes specified in a path. More than one value can be set if
2537     a wildcard is used. The function sets the value asynchronously which means that after the function
2538     returns you have no security to which value it is finally set nor at what point in time it is set.
2539
2540     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set
2541     @param[in] path            Path to the Node(s) for which the value(s) will be set
2542     @param[in] wstr            Pointer to a null terminated unicode string (max 64k characters)
2543     @return
2544     - ZI_INFO_SUCCESS             on success.
2545     - ZI_ERROR_CONNECTION         when the connection is invalid (not connected) or when a communication error occurred.
2546     - ZI_ERROR_LENGTH             if the Path's Length exceeds MAX_PATH_LEN.
2547     - ZI_ERROR_READONLY           on attempt to set a read-only node.
2548     - ZI_ERROR_COMMAND            on an incorrect answer of the server.
2549     - ZI_ERROR_SERVER_INTERNAL    if an internal error occurred in the Data Server.
2550     - ZI_WARNING_NOTFOUND         if the given path could not be resolved or no node given by path is able
2551                                   to hold values.
2552     - ZI_WARNING_INVALID_KEYWORD  if the given keyword could not be resolved
2553     - ZI_ERROR_TIMEOUT            when communication timed out.
2554     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2555
2556     @sa ziAPIGetValueStringUnicode. ziAPISyncSetValueStringUnicode
2557
2558  */
2559ZI_EXPORT ZIResult_enum ziAPISetValueStringUnicode(ZIConnection conn, const char* path, const wchar_t* wstr);
2560
2561  /// synchronously sets a double-type value to one or more nodes specified in the path
2562  /**
2563     This function sets the values of the nodes specified in path to Value. More than one value can be set if
2564     a wildcard is used. The function sets the value synchronously. After returning you know that it is set and
2565     to which value it is set.
2566
2567     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set
2568     @param[in] path            Path to the Node(s) for which the value(s) will be set to value
2569     @param[in] value           Pointer to a double-type containing the value to be written. When the function returns
2570                                value holds the effectively written value.
2571     @return
2572     - ZI_INFO_SUCCESS             on success
2573     - ZI_ERROR_CONNECTION         when the connection is invalid (not connected) or when a communication error occurred
2574     - ZI_ERROR_LENGTH             if the Path's Length exceeds MAX_PATH_LEN
2575     - ZI_ERROR_READONLY           on attempt to set a read-only node
2576     - ZI_ERROR_COMMAND            on an incorrect answer of the server
2577     - ZI_ERROR_SERVER_INTERNAL    if an internal error occurred in the Data Server
2578     - ZI_WARNING_NOTFOUND         if the given path could not be resolved or no node given by path is able to hold values
2579     - ZI_WARNING_INVALID_KEYWORD  if the given keyword could not be resolved
2580     - ZI_ERROR_TIMEOUT            when communication timed out
2581     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2582
2583     @sa ziAPIGetValueD, ziAPISetValueD
2584  */
2585ZI_EXPORT ZIResult_enum ziAPISyncSetValueD(ZIConnection conn, const char* path, ZIDoubleData* value);
2586
2587  /// synchronously sets an integer-type value to one or more nodes specified in a path
2588  /**
2589     This function sets the values of the nodes specified in path to value. More than one value can be set if
2590     a wildcard is used. The function sets the value synchronously. After returning you know that it is set and
2591     to which value it is set.
2592
2593     @param[in] conn            Pointer to the ziConnection for which the value(s) will be set
2594     @param[in] path            Path to the node(s) for which the value(s) will be set
2595     @param[in] value           Pointer to a int-type containing then value to be written. when the function returns
2596                                value holds the effectively written value.
2597
2598     @return
2599     - ZI_INFO_SUCCESS          on success
2600     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred
2601     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN
2602     - ZI_ERROR_READONLY        on attempt to set a read-only node
2603     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2604     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2605     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able to hold values
2606     - ZI_ERROR_TIMEOUT         when communication timed out
2607     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2608
2609     @sa ziAPIGetValueI, ziAPISetValueI
2610
2611  */
2612ZI_EXPORT ZIResult_enum ziAPISyncSetValueI(ZIConnection conn, const char* path, ZIIntegerData* value);
2613
2614/// Synchronously sets the binary-type value of one ore more nodes specified in the path
2615/** This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard
2616    is used. This function sets the value synchronously. After returning you know that it is set and to which
2617    value it is set.
2618
2619     @param[in]  conn            Pointer to the ziConnection for which the value(s) will be set
2620     @param[in]  path            Path to the Node(s) for which the value(s) will be set
2621     @param[in]  buffer          Pointer to the byte array with the data
2622     @param[in]  length          Length of the data in the buffer
2623     @param[in]  bufferSize      Length of the data in the buffer
2624     @return
2625     - ZI_INFO_SUCCESS           on success
2626     - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
2627     - ZI_ERROR_LENGTH           if the Path's Length exceeds MAX_PATH_LEN
2628     - ZI_ERROR_READONLY         on attempt to set a read-only node
2629     - ZI_ERROR_COMMAND          on an incorrect answer of the server
2630     - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in the Data Server
2631     - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no node given by path is able to hold
2632                                 values
2633     - ZI_ERROR_TIMEOUT          when communication timed out
2634     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2635
2636     @sa ziAPIGetValueB, ziAPISetValueB
2637*/
2638ZI_EXPORT ZIResult_enum ziAPISyncSetValueB(ZIConnection conn, const char* path, uint8_t* buffer, uint32_t* length,
2639                                           uint32_t bufferSize);
2640
2641/// Synchronously sets a string value of one or more nodes specified in the path
2642/** This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard
2643    is used. This function sets the value synchronously. After returning you know that it is set.
2644
2645     @param[in]     conn         Pointer to the ziConnection for which the value(s) will be set
2646     @param[in]     path         Path to the Node(s) for which the value(s) will be set
2647     @param[inout]  str          Pointer to a null terminated string (max 64k characters)
2648     @return
2649     - ZI_INFO_SUCCESS              on success
2650     - ZI_ERROR_CONNECTION          when the connection is invalid (not connected) or when a communication error occurred
2651     - ZI_ERROR_LENGTH              if the Path's Length exceeds MAX_PATH_LEN
2652     - ZI_ERROR_READONLY            on attempt to set a read-only node
2653     - ZI_ERROR_COMMAND             on an incorrect answer of the server
2654     - ZI_ERROR_SERVER_INTERNAL     if an internal error occurred in the Data Server
2655     - ZI_WARNING_NOTFOUND          if the given path could not be resolved or no node given by path is able to hold
2656                                    values
2657     - ZI_WARNING_INVALID_KEYWORD   if the given keyword could not be resolved
2658     - ZI_ERROR_TIMEOUT             when communication timed out
2659     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2660
2661     @sa ziAPIGetValueString, ziAPISetValueString
2662*/
2663ZI_EXPORT ZIResult_enum ziAPISyncSetValueString(ZIConnection conn, const char* path, const char* str);
2664
2665/// Synchronously sets a unicode string value of one or more nodes specified in the path
2666/** This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard
2667    is used. This function sets the value synchronously. After returning you know that it is set.
2668
2669     @param[in]     conn         Pointer to the ziConnection for which the value(s) will be set
2670     @param[in]     path         Path to the Node(s) for which the value(s) will be set
2671     @param[inout]  wstr         Pointer to a null terminated unicode string (max 64k characters)
2672     @return
2673     - ZI_INFO_SUCCESS              on success
2674     - ZI_ERROR_CONNECTION          when the connection is invalid (not connected) or when a communication error occurred
2675     - ZI_ERROR_LENGTH              if the Path's Length exceeds MAX_PATH_LEN
2676     - ZI_ERROR_READONLY            on attempt to set a read-only node
2677     - ZI_ERROR_COMMAND             on an incorrect answer of the server
2678     - ZI_ERROR_SERVER_INTERNAL     if an internal error occurred in the Data Server
2679     - ZI_WARNING_NOTFOUND          if the given path could not be resolved or no node given by path is able to hold
2680                                    values
2681     - ZI_WARNING_INVALID_KEYWORD   if the given keyword could not be resolved
2682     - ZI_ERROR_TIMEOUT             when communication timed out
2683     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2684
2685     @sa ziAPIGetValueStringUnicode, ziAPISetValueStringUnicode
2686*/
2687ZI_EXPORT ZIResult_enum ziAPISyncSetValueStringUnicode(ZIConnection conn, const char* path, const wchar_t* wstr);
2688
2689/// Synchronizes the session by dropping all pending data.
2690/** This function drops any data that is pending for transfer. Any data (including poll data)
2691    retrieved afterwards is guaranteed to be produced not earlier than the call to ziAPISync. This ensures in
2692    particular that any settings made prior to the call to ziAPISync have been propagated to the device, and the
2693    data retrieved afterwards is produced with the new settings already set to the hardware. Note, however, that
2694    this does not include any required settling time.
2695
2696     @param[in]  conn            Pointer to the ZIConnection that is to be synchronized
2697
2698     @return
2699     - ZI_INFO_SUCCESS           on success
2700     - ZI_ERROR_TIMEOUT          when communication timed out
2701     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2702
2703 */
2704ZI_EXPORT ZIResult_enum ziAPISync(ZIConnection conn);
2705
2706/// Sends an echo command to a device and blocks until answer is received.
2707/** This is useful to flush all buffers between API and device to enforce that further code is only executed after
2708    the device executed a previous command.
2709    Per device echo is only implemented for HF2. For other device types it is a synonym to ziAPISync, and
2710    deviceSerial parameter is ignored.
2711
2712     @param[in]  conn            Pointer to the ZIConnection that is to be synchronized
2713     @param[in]  deviceSerial    The serial of the device to get the echo from, e.g., dev2100
2714
2715
2716     @return
2717     - ZI_INFO_SUCCESS           on success
2718     - ZI_ERROR_TIMEOUT          when communication timed out
2719     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2720
2721 */
2722ZI_EXPORT ZIResult_enum ziAPIEchoDevice(ZIConnection conn, const char* deviceSerial);
2723
2724/** @} */  // end of group Parameters
2725
2726
2727/** @defgroup DataHandling Data Streaming
2728 *  @brief This section describes how to perform data streaming. It allows for recording at high data rates without
2729 *         sample loss.
2730 *  @{
2731 */
2732
2733/// This struct holds event data forwarded by the Data Server
2734/**
2735    ZIEvent is used to give out events like value changes or errors to the user. Event handling functionality is
2736    provided by ziAPISubscribe and ziAPIUnSubscribe as well as ziAPIPollDataEx.
2737
2738    @sa ziAPISubscribe, ziAPIUnSubscribe, ziAPIPollDataEx
2739 */
2740struct ZIEvent {
2741// --- 8 bytes border
2742  /// Specifies the type of the data held by the ZIEvent, see ::ZIValueType_enum
2743  uint32_t valueType;
2744
2745  /// Number of values available in this event
2746  uint32_t count;
2747
2748// --- 8 bytes border
2749  /// The path to the node from which the event originates
2750  uint8_t path[MAX_PATH_LEN];
2751
2752// --- 8 bytes border
2753  /// Convenience pointer to allow for access to the first entry in Data using the correct type
2754  /// according to ZIEvent.valueType field.
2755  union {
2756    /// For convenience. The void field doesn't have a corresponding data type.
2757    void* untyped;
2758
2759    /// when valueType == ZI_VALUE_TYPE_DOUBLE_DATA
2760    ZIDoubleData* doubleData;
2761
2762    /// when valueType == ZI_VALUE_TYPE_DOUBLE_DATA_TS
2763    ZIDoubleDataTS* doubleDataTS;
2764
2765    /// when valueType == ZI_VALUE_TYPE_INTEGER_DATA
2766    ZIIntegerData* integerData;
2767
2768    /// when valueType == ZI_VALUE_TYPE_INTEGER_DATA_TS
2769    ZIIntegerDataTS* integerDataTS;
2770
2771    /// when valueType == ZI_VALUE_TYPE_COMPLEX_DATA
2772    ZIComplexData* complexData;
2773
2774    /// when valueType == ZI_VALUE_TYPE_BYTE_ARRAY
2775    ZIByteArray* byteArray;
2776
2777    /// when valueType == ZI_VALUE_TYPE_BYTE_ARRAY_TS
2778    ZIByteArrayTS* byteArrayTS;
2779
2780    /// when valueType == ZI_VALUE_TYPE_CNT_SAMPLE
2781    ZICntSample* cntSample;
2782
2783    /// when valueType == ZI_VALUE_TYPE_TRIG_SAMPLE
2784    ZITrigSample* trigSample;
2785
2786    /// when valueType == ZI_VALUE_TYPE_TREE_CHANGE_DATA
2787    ZITreeChangeData* treeChangeData;
2788
2789    /// when valueType == ZI_VALUE_TYPE_TREE_CHANGE_DATA_OLD
2790    TreeChange* treeChangeDataOld;
2791
2792    /// when valueType == ZI_VALUE_TYPE_DEMOD_SAMPLE
2793    ZIDemodSample* demodSample;
2794
2795    /// when valueType == ZI_VALUE_TYPE_AUXIN_SAMPLE
2796    ZIAuxInSample* auxInSample;
2797
2798    /// when valueType == ZI_VALUE_TYPE_DIO_SAMPLE
2799    ZIDIOSample* dioSample;
2800
2801    /// when valueType == ZI_VALUE_TYPE_SCOPE_WAVE
2802    ZIScopeWave* scopeWave;
2803
2804    /// when valueType == ZI_VALUE_TYPE_SCOPE_WAVE_EX
2805    ZIScopeWaveEx* scopeWaveEx;
2806
2807    /// when valueType == ZI_VALUE_TYPE_SCOPE_WAVE_OLD
2808    ScopeWave* scopeWaveOld;
2809
2810    /// when valueType == ZI_VALUE_TYPE_PWA_WAVE
2811    ZIPWAWave* pwaWave;
2812
2813    /// when valueType == ZI_VALUE_TYPE_SWEEPER_WAVE
2814    ZISweeperWave* sweeperWave;
2815
2816    /// when valueType == ZI_VALUE_TYPE_SPECTRUM_WAVE
2817    ZISpectrumWave* spectrumWave;
2818
2819    /// when valueType == ZI_VALUE_TYPE_ADVISOR_WAVE
2820    ZIAdvisorWave* advisorWave;
2821
2822    /// when valueType == ZI_VALUE_TYPE_ASYNC_REPLY
2823    ZIAsyncReply* asyncReply;
2824
2825    /// when valueType == ZI_VALUE_TYPE_VECTOR_DATA
2826    ZIVectorData* vectorData;
2827
2828    /// when valueType == ZI_VALUE_TYPE_IMPEDANCE_SAMPLE
2829    ZIImpedanceSample* impedanceSample;
2830
2831    /// ensure union size is 8 bytes
2832    uint64_t alignment;
2833  } value;
2834
2835// --- 8 bytes border
2836  /// The raw value data.
2837  uint8_t data[MAX_EVENT_SIZE];
2838};
2839
2840#ifndef __cplusplus
2841typedef struct ZIEvent ZIEvent;
2842#endif
2843
2844/// Allocates ZIEvent structure and returns the pointer to it. Attention!!! It is the client code responsibility
2845/// to deallocate the structure by calling ziAPIDeallocateEventEx!
2846/** This function allocates a ZIEvent structure and returns the pointer to it. Free the memory
2847    using ziAPIDeallocateEventEx.
2848
2849    @sa ziAPIDeallocateEventEx
2850*/
2851ZI_EXPORT ZIEvent* ziAPIAllocateEventEx(void);
2852
2853/// Deallocates ZIEvent structure created with ziAPIAllocateEventEx().
2854/** This function is the compliment to ziAPIAllocateEventEx()
2855    @param[in] ev Pointer to ZIEvent structure to be deallocated..
2856
2857    @sa ziAPIAllocateEventEx
2858*/
2859ZI_EXPORT void ziAPIDeallocateEventEx(ZIEvent* ev);
2860
2861/// subscribes the nodes given by path for ::ziAPIPollDataEx
2862/** This function subscribes to nodes so that whenever the value of the node changes the new value can be polled
2863    using ::ziAPIPollDataEx. By using wildcards or by using a path that is not a leaf node but contains sub nodes,
2864    more than one leaf can be subscribed to with one function call.
2865
2866    @param[in] conn             Pointer to the ziConnection for which to subscribe for
2867    @param[in] path             Path to the nodes to subscribe
2868    @return
2869     - ZI_INFO_SUCCESS          on success
2870     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred
2871     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN
2872     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2873     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2874     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able to hold values
2875     - ZI_ERROR_TIMEOUT         when communication timed out
2876     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2877
2878   See @link DataHandling Data Handling @endlink for an example
2879
2880   @sa ziAPIUnSubscribe, ziAPIPollDataEx, ziAPIGetValueAsPollData
2881 */
2882ZI_EXPORT ZIResult_enum ziAPISubscribe(ZIConnection conn, const char* path);
2883
2884  /// unsubscribes to the nodes given by path
2885  /**
2886      This function is the complement to ::ziAPISubscribe. By using wildcards or by using a path that is not a leaf
2887      node but contains sub nodes, more than one node can be unsubscribed with one function call.
2888
2889      @param[in] conn           Pointer to the ziConnection for which to unsubscribe for
2890      @param[in] path           Path to the Nodes to unsubscribe
2891      @return
2892     - ZI_INFO_SUCCESS          on success
2893     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred
2894     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN
2895     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2896     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2897     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no node given by path is able to hold values
2898     - ZI_ERROR_TIMEOUT         when communication timed out
2899     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2900
2901     See @link DataHandling Data Handling @endlink for an example
2902
2903     @sa ziAPISubscribe, ziAPIPollDataEx, ziAPIGetValueAsPollData
2904
2905  */
2906ZI_EXPORT ZIResult_enum ziAPIUnSubscribe(ZIConnection conn, const char* path);
2907  /// checks if an event is available to read
2908  /**
2909     This function returns immediately if an event is pending. Otherwise it waits for an event for up to
2910     timeOutMilliseconds. All value changes that occur in nodes that have been subscribed to or in children of nodes
2911     that have been subscribed to are sent from the Data Server to the ziAPI session. For a description of how the data
2912     are available in the struct, refer to the documentation of struct ziEvent. When no event was available within
2913     timeOutMilliseconds, the ziEvent::Type field will be ZI_DATA_NONE and the ziEvent::Count field will be zero.
2914     Otherwise these fields hold the values corresponding to the event that occurred.
2915
2916     @param[in]  conn                Pointer to the ::ZIConnection for which events should be received
2917     @param[out] ev                  Pointer to a ::ZIEvent struct in which the received event will be written
2918     @param[in]  timeOutMilliseconds Time to wait for an event in milliseconds. If -1 it will wait forever,
2919                                     if 0 the function returns immediately.
2920     @return
2921     - ZI_INFO_SUCCESS          on success
2922     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred
2923     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2924
2925     See @link DataHandling Data Handling @endlink for an example
2926
2927     @sa ziAPISubscribe, ziAPIUnSubscribe, ziAPIGetValueAsPollData, ziEvent
2928
2929  */
2930ZI_EXPORT ZIResult_enum ziAPIPollDataEx(ZIConnection conn, ZIEvent* ev, uint32_t timeOutMilliseconds);
2931
2932  /// triggers a value request, which will be given back on the poll event queue
2933  /**
2934     Use this function to receive the value of one or more nodes as one or more events using ::ziAPIPollDataEx, even
2935     when the node is not subscribed or no value change has occurred.
2936
2937     @param[in] conn            Pointer to the ::ZIConnection with which the value should be retrieved
2938     @param[in] path            Path to the Node holding the value.
2939                                Note: Wildcards and paths referring to streamimg nodes are not permitted.
2940
2941     @return
2942     - ZI_INFO_SUCCESS          on success
2943     - ZI_ERROR_CONNECTION      when the connection is invalid (not connected) or when a communication error occurred
2944     - ZI_ERROR_LENGTH          if the Path's Length exceeds MAX_PATH_LEN or the length of the char-buffer for
2945                                the nodes given by MaxLen is too small for all elements
2946     - ZI_ERROR_COMMAND         on an incorrect answer of the server
2947     - ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
2948     - ZI_WARNING_NOTFOUND      if the given path could not be resolved or no value is attached to the node
2949     - ZI_ERROR_TIMEOUT         when communication timed out
2950     - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
2951
2952     See @link DataHandling Data Handling @endlink for an example
2953
2954     @sa ziAPISubscribe, ziAPIUnSubscribe, ziAPIPollDataEx
2955
2956   */
2957ZI_EXPORT ZIResult_enum ziAPIGetValueAsPollData(ZIConnection conn, const char* path);
2958
2959/** @} */  // end of group DataHandling
2960
2961
2962
2963/** @defgroup Asynchronous   API for fast asynchronous operation
2964 *  @brief Functions in this group are non-blocking, and on return only report errors that can be identified directly
2965 *         on a client side (e.g. not connected). Any further results (including errors like node not found) of
2966 *         the command processing is returned as a special event in poll data. Tags are used to match the asynchronous
2967 *         replies with the sent commands.
2968 *  @{
2969 */
2970
2971ZI_EXPORT ZIResult_enum ziAPIAsyncSetDoubleData(ZIConnection conn, const char* path, ZIDoubleData value);
2972ZI_EXPORT ZIResult_enum ziAPIAsyncSetIntegerData(ZIConnection conn, const char* path, ZIIntegerData value);
2973ZI_EXPORT ZIResult_enum ziAPIAsyncSetByteArray(ZIConnection conn, const char* path, uint8_t* buffer, uint32_t length);
2974ZI_EXPORT ZIResult_enum ziAPIAsyncSetString(ZIConnection conn, const char* path, const char* str);
2975ZI_EXPORT ZIResult_enum ziAPIAsyncSetStringUnicode(ZIConnection conn, const char* path, const wchar_t* wstr);
2976ZI_EXPORT ZIResult_enum ziAPIAsyncSubscribe(ZIConnection conn, const char* path, ZIAsyncTag tag);
2977ZI_EXPORT ZIResult_enum ziAPIAsyncUnSubscribe(ZIConnection conn, const char* path, ZIAsyncTag tag);
2978ZI_EXPORT ZIResult_enum ziAPIAsyncGetValueAsPollData(ZIConnection conn, const char* path, ZIAsyncTag tag);
2979
2980/** @} */  // end of group Asynchronous
2981
2982
2983
2984/** @defgroup ErrorHandling Error Handling and Logging in the LabOne C API
2985
2986 * @brief This section describes how to get more information when an error occurs.
2987
2988   @{
2989
2990   In general, two types of errors can occur when using ziAPI. The two types are distinguished by the origin of the
2991   error: Whether it occurred within ziAPI itself or whether it occurred internally in the Zurich Instruments Core
2992   library.
2993
2994   All ziAPI functions (apart from a very few exceptions) return an exit code ::ZIResult_enum, which will be non-zero
2995   if the function call was not entirely successful. If the error originated in ziAPI itself, the exit code describes
2996   precisely the type of error that occurred (in other words, the exit code is not ZI_ERROR_GENERAL). In this case the
2997   error message corresponding to the exit code can be obtained with the function ::ziAPIGetError.
2998
2999   However, if the error has occurred internally, the exit code will be ZI_ERROR_GENERAL. In this case, the exit code
3000   does not describe the type of error precisely, instead a detailed error message is available to the user which can
3001   be obtained with the function ::ziAPIGetLastError. The function ::ziAPIGetLastError may be used with any function
3002   that takes a ZIConnection as an input argument (with the exception of ::ziAPIInit, ::ziAPIDestroy, ::ziAPIConnect,
3003   ::ziAPIConnectEx) and is the recommended function to use, if applicable, otherwise ::ziAPIGetError should be used.
3004
3005   The function ::ziAPIGetLastError was introduced in LabOne 15.11 due to the availability of \ref modules "ziCore
3006   Modules" in ziAPI - its not desirable in general to map every possible error to an exit code in ziAPI; what is more
3007   relevant is the associated error message.
3008
3009   In addition to these two functions, ziAPI's log can be very helpful whilst debugging ziAPI-based programs. The log
3010   is not enabled by default; it's enabled by specifying a logging level with ::ziAPISetDebugLevel.
3011
3012*/
3013
3014/// Returns a description and the severity for a ::ZIResult_enum.
3015/** This function returns a static char pointer to a description string for the given ::ZIResult_enum error code.  It
3016    also provides a parameter returning the severity (info, warning, error). If the given error code does not exist a
3017    description for an unknown error and the base for an error will be returned. If a description or the base is not
3018    needed NULL may be passed. In general, it's recommended to use ::ziAPIGetLastError instead to get detailed error
3019    messages.
3020
3021    @param[in]  result          A ::ZIResult_enum for which the description or base will be returned
3022    @param[out] buffer          A pointer to a char array to return the description. May be NULL if no description
3023                                is needed.
3024    @param[out] base            The severity for the provided Status parameter:
3025                                - ZI_INFO_BASE    For infos.
3026                                - ZI_WARNING_BASE For warnings.
3027                                - ZI_ERROR_BASE   For errors.
3028
3029    @return
3030    - ZI_INFO_SUCCESS           Upon success.
3031
3032*/
3033ZI_EXPORT ZIResult_enum ziAPIGetError(ZIResult_enum result, char** buffer, int* base);
3034
3035/// Returns the message from the last error that occurred.
3036/** This function can be used to obtain the error message from the last error that occurred associated with the
3037    provided ::ZIConnection. If the last ziAPI call is successful, then the last error message returned by
3038    ziAPIGetError is empty. Only ziAPI function calls that take ::ZIConnection as an input argument influence the
3039    message returned by ziAPIGetLastError, if they do not take ::ZIConnection as an input argument the last error
3040    message will neither be reset to be empty or set to an error message (in the case of the error). There are some
3041    exceptions to this rule, ziAPIGetLastError can also not be used with ::ziAPIInit, ::ziAPIConnect, ::ziAPIConnectEx
3042    and ::ziAPIDestroy. Note, a call to ziAPIGetLastError will also reset the last error message to empty if its call
3043    was successful. Since the buffer is left unchanged in the case of an error occurring in the call to
3044    ziAPIGetLastError it is safest to initialize the buffer with a known value, for example, "ziAPIGetLastError was
3045    not successful".
3046
3047    @param[in]  conn            The ::ZIConnection from which to get the error message.
3048    @param[out] buffer          A pointer to a char array to return the message.
3049    @param[in]  bufferSize      The length of the provided buffer.
3050
3051    @return
3052    - ZI_INFO_SUCCESS           Upon success.
3053    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3054                                In this case the provided buffer is left unchanged.
3055    - ZI_ERROR_LENGTH           If the message's length exceeds the provided bufferSize, the message is truncated and
3056                                written to buffer.
3057
3058*/
3059ZI_EXPORT ZIResult_enum ziAPIGetLastError(ZIConnection conn, char* buffer, uint32_t bufferSize);
3060
3061/// Enable ziAPI's log and set the severity level of entries to be included in the log.
3062/** Calling this function enables ziAPI's log at the specified severity level. On Windows the logs can be found by
3063    navigating to the Zurich Instruments "Logs" folder entry in the Windows Start Menu: Programs -> Zurich Instruments
3064    -> LabOne Servers -> Logs. This will open an Explorer window displaying folders containing log files from various
3065    LabOne components, in particular, the <code>ziAPILog</code> folder contains logs from ziAPI. On Linux, the logs can
3066    be found at "/tmp/ziAPILog_USERNAME", where "USERNAME" is the same as the output of the "whoami" command.
3067
3068    @param[in]  severity        An integer specifying the log's severity level:
3069                                - trace:   0,
3070                                - debug:   1,
3071                                - info:    2,
3072                                - status:  3,
3073                                - warning: 4,
3074                                - error:   5,
3075                                - fatal:   6,
3076
3077    @sa ziAPIWriteDebugLog
3078 */
3079ZI_EXPORT void ziAPISetDebugLevel(int32_t severity);
3080
3081/// Write a message to ziAPI's log with the specified severity.
3082/** This function may be used to write a message to ziAPI's log from client code to assist with debugging. Note,
3083 logging must be first enabled using ::ziAPISetDebugLevel.
3084
3085    @param[in]  severity        An integer specifying the severity of the message to write in the log:
3086                                - trace:   0,
3087                                - debug:   1,
3088                                - info:    2,
3089                                - status:  3,
3090                                - warning: 4,
3091                                - error:   5,
3092                                - fatal:   6,
3093    @param[in]  message         A character array comprising of the message to be written.
3094
3095    @sa ziAPISetDebugLevel
3096*/
3097ZI_EXPORT void ziAPIWriteDebugLog(int32_t severity, const char* message);
3098
3099/** @} */  // end of group ErrorHandling
3100
3101ZI_EXPORT ZIResult_enum ReadMEMFile(const char* filename, char* buffer, int32_t bufferSize, int32_t* bytesUsed);
3102
3103/** @defgroup modules Using ziCore Modules in the LabOne C API
3104
3105    @brief This sections describes ziAPI's interface for working with ziCore Modules. Modules provide a high-level
3106    interface for performing common measurement tasks such as sweeping data (Sweeper Module) or recording bursts of
3107    when certain trigger criteria have been fulfilled (Software Trigger Module). For an introduction to working with
3108    Modules please see the "ziCore Modules" section in the LabOne Programming Manual:
3109    https://www.zhinst.com/manuals/programming .
3110
3111   @{
3112 */
3113
3114/// Defines the flags returned in the chunk header for all modules.
3115enum ZIChunkHeaderFlags_enum {
3116  /// Indicates that the chunk data is complete. This flag will be set if data is read out from the module before the
3117  /// measurement (e.g. sweep) has finished.
3118  ZI_CHUNK_HEADER_FLAG_FINISHED       = 0x00000001,
3119  /// Unused.
3120  ZI_CHUNK_HEADER_FLAG_ROLLMODE       = 0x00000002,
3121  /// Indicates that dataloss has occurred.
3122  ZI_CHUNK_HEADER_FLAG_DATALOSS       = 0x00000004,
3123  /// Indcates that the data is valid.
3124  ZI_CHUNK_HEADER_FLAG_VALID          = 0x00000008,
3125  /// Indicates whether then chunk contains data (opposite to setting).
3126  ZI_CHUNK_HEADER_FLAG_DATA           = 0x00000010,
3127  /// Internal use only.
3128  ZI_CHUNK_HEADER_FLAG_DISPLAY        = 0x00000020,
3129  /// chunk contains frequency domain data, opposite to time domain.
3130  ZI_CHUNK_HEADER_FLAG_FREQDOMAIN     = 0x00000040,
3131  /// chunk recorded in spectrum mode.
3132  ZI_CHUNK_HEADER_FLAG_SPECTRUM       = 0x00000080,
3133  /// chunk results overlap with neighboring chunks, see spectrum.
3134  ZI_CHUNK_HEADER_FLAG_OVERLAPPED     = 0x00000100,
3135  /// indicates that the current row is finished - useful for row first averaging.
3136  ZI_CHUNK_HEADER_FLAG_ROWFINISHED    = 0x00000200,
3137  /// exact sampling was used.
3138  ZI_CHUNK_HEADER_FLAG_ONGRIDSAMPLING = 0x00000400,
3139  /// row first averaging is enabled.
3140  ZI_CHUNK_HEADER_FLAG_ROWREPETITION  = 0x00000800,
3141  /// chunk contains preview (fft with less points).
3142  ZI_CHUNK_HEADER_FLAG_PREVIEW        = 0x00001000,
3143};
3144
3145/// Defines flags returned in the chunk header that only apply for certain modules.
3146enum ZIChunkHeaderModuleFlags_enum {
3147  // Data Acquisition Module
3148  /// FFT Window used in the Data Acquisition Module: 0 - Rectangular, 1 - Hann, 2 - Hamming, 3 - Blackmanharris,
3149  /// 4 - Exponential, 5 - Cosine, 6 - CosineSquare
3150  ZI_CHUNK_HEADER_MODULE_FLAGS_WINDOW = 0x00000003
3151
3152};
3153
3154/// Structure to hold generic chunk data header information
3155struct ZIChunkHeader {
3156  /// System timestamp
3157  ZITimeStamp systemTime;
3158
3159  /// Creation timestamp
3160  ZITimeStamp createdTimeStamp;
3161
3162  /// Last changed timestamp
3163  ZITimeStamp changedTimeStamp;
3164
3165// --- 8 bytes border
3166  /// Flags (bitmask of values from ZIChunkHeaderFlags_enum)
3167  uint32_t flags;
3168
3169  /// moduleFlags (bitmask of values from ZIChunkHeaderModuleFlags_enum, module-specific)
3170  uint32_t moduleFlags;
3171
3172// --- 8 bytes border
3173  /// Status Flag:
3174  /// [0] : selected
3175  /// [1] : group assigned
3176  /// [2] : color edited
3177  /// [4] : name edited
3178  uint32_t status;
3179
3180  uint32_t reserved0;
3181
3182// --- 8 bytes border
3183  /// Size in bytes used for memory usage calculation
3184  uint64_t chunkSizeBytes;
3185
3186  /// SW Trigger counter since execution start
3187  uint64_t triggerNumber;
3188
3189// --- 8 bytes border
3190  /// Name in history list
3191  char name[MAX_NAME_LEN];
3192
3193  /// Group index in history list
3194  uint32_t groupIndex;
3195
3196// --- 8 bytes border
3197  /// Color in history list
3198  uint32_t color;
3199
3200  /// Active row in history list
3201  uint32_t activeRow;
3202
3203// --- 8 bytes border
3204  /// Number of grid rows
3205  uint32_t gridRows;
3206
3207  /// Number of grid columns
3208  uint32_t gridCols;
3209
3210// --- 8 bytes border
3211  /// Grid mode interpolation mode (0 = off, 1 = nearest, 2 = linear, 3 = Lanczos)
3212  uint32_t gridMode;
3213
3214  /// Grid mode operation (0 = replace, 1 = average)
3215  uint32_t gridOperation;
3216
3217// --- 8 bytes border
3218  /// Grid mode direction (0 = forward, 1 = revers, 2 = bidirectional)
3219  uint32_t gridDirection;
3220
3221  /// Number of repetitions in grid mode
3222  uint32_t gridRepetitions;
3223
3224// --- 8 bytes border
3225  /// Delta between grid points in SI unit
3226  double gridColDelta;
3227
3228// --- 8 bytes border
3229  /// Offset of first grid point relative to trigger
3230  double gridColOffset;
3231
3232// --- 8 bytes border
3233  /// Delta between grid rows in SI unit
3234  double gridRowDelta;
3235
3236// --- 8 bytes border
3237  /// Delay of first grid row relative to trigger
3238  double gridRowOffset;
3239
3240// --- 8 bytes border
3241  /// For FFT the bandwidth of the signal
3242  double bandwidth;
3243
3244// --- 8 bytes border
3245  /// The FFT center frequency
3246  double center;
3247
3248// --- 8 bytes border
3249  /// For FFT the normalized effective noise bandwidth
3250  double nenbw;
3251};
3252
3253#ifndef __cplusplus
3254typedef struct ZIChunkHeader ZIChunkHeader;
3255#endif
3256
3257#ifdef _MSC_VER
3258// Visual C++ specific
3259#pragma warning(push)
3260#pragma warning(disable:4200)
3261#endif
3262
3263/// This struct holds data of a single chunk from module lookup
3264struct ZIModuleEvent {
3265  /// For internal use - never modify!
3266  uint64_t allocatedSize;
3267
3268  /// Chunk header
3269  ZIChunkHeader* header;
3270
3271  /// Defines location of stored ZIEvent
3272  ZIEvent value[0];
3273};
3274
3275#ifdef _MSC_VER
3276// Visual C++ specific
3277#pragma warning(pop)
3278#endif
3279
3280#ifndef __cplusplus
3281typedef struct ZIModuleEvent ZIModuleEvent;
3282#endif
3283
3284/// The pointer to a Module's data chunk to read out, updated via ::ziAPIModGetChunk.
3285typedef ZIModuleEvent* ZIModuleEventPtr;
3286
3287/// Create a ::ZIModuleHandle that can be used for asynchronous measurement tasks.
3288/** This function initializes a ziCore module and provides a pointer (handle) with which to access and work with it.
3289    Note that this function does not start the module's thread. Before the thread can be started (with
3290    ::ziAPIModExecute):
3291    - the device serial (e.g., "dev100") to be used with module must be specified via ::ziAPIModSetByteArray.
3292    - the desired data (node paths) to record during the measurement must be specified via ::ziAPIModSubscribe.
3293    The module's thread is stopped with ::ziAPIModClear.
3294
3295    @param[in]  conn            The ::ZIConnection which should be used to initialize the module.
3296    @param[out] handle          Pointer to the initialized ::ZIModuleHandle, which from then on can be used to
3297                                reference the module.
3298    @param[in]  moduleId        The name specifying the type the module to create (only the following ziCore Modules
3299                                are currently supported in ziAPI):
3300                                - "sweep" to initialize an instance of the Sweeper Module.
3301                                - "record" to initialize an instance of the Software Trigger (Recorder) Module.
3302                                - "zoomFFT" to initialize an instance of the Spectrum Module.
3303                                - "deviceSettings" to initialize an instance to save/load device settings.
3304                                - "pidAdvisor" to initialize an instance of the PID Advisor Module.
3305                                - "awgModule" to initialize an instance of the AWG Compiler Module.
3306                                - "impedanceModule" to initialize an instance of the Impedance Compensation Module.
3307                                - "scopeModule" to initialize an instance of the Scope Module to assembly scope shots.
3308                                - "multiDeviceSyncModule" to initialize an instance of the Device Synchronization Module.
3309                                - "dataAcquisitionModule" to initialize an instance of the Data Acquisition Module.
3310                                - "precompensationAdvisor" to initialize an instance of the Precompensation Advisor Module.
3311                                - "quantumAnalyzerModule" to initialize an instance of the Quantum Analyzer Module.
3312
3313    @return
3314    - ZI_INFO_SUCCESS           On success.
3315    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred.
3316    - ZI_WARNING_NOTFOUND       if the provided moduleId was invalid.
3317    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3318
3319    @sa ziAPIModExecute, ziAPIModClear
3320 */
3321ZI_EXPORT ZIResult_enum ziAPIModCreate(ZIConnection conn, ZIModuleHandle* handle, const char* moduleId);
3322
3323/// Sets a module parameter to the specified double type.
3324/** This function is used to configure (set) module parameters which have double types.
3325
3326    @param[in]  conn            The ::ZIConnection from which the module was created.
3327    @param[in]  handle          The ::ZIModuleHandle specifying the module to set data on.
3328    @param[in]  path            Path of the module parameter to set.
3329    @param[in]  value           The double data to write to the path.
3330
3331    @return
3332    - ZI_INFO_SUCCESS           On success.
3333    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3334    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3335    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3336
3337    @sa ziAPIModSetIntegerData, ziAPIModSetByteArray, ziAPIModSetString
3338 */
3339ZI_EXPORT ZIResult_enum ziAPIModSetDoubleData(ZIConnection conn, ZIModuleHandle handle, const char* path,
3340                                              ZIDoubleData value);
3341
3342/// Sets a module parameter to the specified integer type.
3343/** This function is used to configure (set) module parameters which have integer types.
3344
3345    @param[in]  conn            The ::ZIConnection from which the module was created.
3346    @param[in]  handle          The ::ZIModuleHandle specifying the module to set data on.
3347    @param[in]  path            Path of the module parameter to set.
3348    @param[in]  value           The integer data to write to the path.
3349
3350    @return
3351    - ZI_INFO_SUCCESS           On success.
3352    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3353    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3354    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3355
3356    @sa ziAPIModSetDoubleData, ziAPIModSetByteArray, ziAPIModSetString
3357 */
3358ZI_EXPORT ZIResult_enum ziAPIModSetIntegerData(ZIConnection conn, ZIModuleHandle handle, const char* path,
3359                                               ZIIntegerData value);
3360
3361/// Sets a module parameter to the specified byte array.
3362/** This function is used to configure (set) module parameters which have byte array types.
3363
3364    @param[in]  conn            The ::ZIConnection from which the module was created.
3365    @param[in]  handle          The ::ZIModuleHandle specifying the module to set data on.
3366    @param[in]  path            Path of the module parameter to set.
3367    @param[in]  buffer          Pointer to the byte array with the data.
3368    @param[in]  length          Length of the data in the buffer.
3369
3370    @return
3371    - ZI_INFO_SUCCESS           On success.
3372    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3373    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3374    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3375
3376    @sa ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetString
3377 */
3378ZI_EXPORT ZIResult_enum ziAPIModSetByteArray(ZIConnection conn, ZIModuleHandle handle, const char* path,
3379                                             uint8_t* buffer, uint32_t length);
3380
3381/// Sets a module parameter to the specified null-terminated string
3382/** This function is used to configure (set) module parameters which have string types.
3383
3384    @param[in]  conn            The ::ZIConnection from which the module was created.
3385    @param[in]  handle          The ::ZIModuleHandle specifying the module to set data on.
3386    @param[in]  path            Path of the module parameter to set.
3387    @param[in]  str             Pointer to a null-terminated string (max 64k characters).
3388
3389    @return
3390    - ZI_INFO_SUCCESS           On success.
3391    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3392    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3393    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3394
3395    @sa ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetByteArray
3396 */
3397ZI_EXPORT ZIResult_enum ziAPIModSetString(ZIConnection conn, ZIModuleHandle handle, const char* path,
3398                                          const char* str);
3399
3400/// Sets a module parameter to the specified null-terminated unicode string
3401/** This function is used to configure (set) module parameters which have string types.
3402
3403    @param[in]  conn            The ::ZIConnection from which the module was created.
3404    @param[in]  handle          The ::ZIModuleHandle specifying the module to set data on.
3405    @param[in]  path            Path of the module parameter to set.
3406    @param[in]  wstr            Pointer to a null-terminated unicode string (max 64k characters).
3407
3408    @return
3409    - ZI_INFO_SUCCESS           On success.
3410    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3411    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3412    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3413
3414    @sa ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetByteArray
3415 */
3416ZI_EXPORT ZIResult_enum ziAPIModSetStringUnicode(ZIConnection conn, ZIModuleHandle handle, const char* path,
3417                                                 const wchar_t* wstr);
3418
3419/// Sets a module parameter to the specified vector
3420/** This function is used to configure (set) module parameters which have vector types.
3421
3422    @param[in]  conn            The ::ZIConnection from which the module was created.
3423    @param[in]  handle          The ::ZIModuleHandle specifying the module to set data on.
3424    @param[in]  path            Path of the module parameter to set.
3425    @param[in]  vectorData      Pointer to the vector data.
3426    @param[in]  elementType     Type of elements stored in the vector.
3427    @param[in]  numElements     Number of elements of the vector.
3428
3429    @return
3430    - ZI_INFO_SUCCESS           On success.
3431    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3432    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3433    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3434
3435    @sa ziAPIModSetDoubleData, ziAPIModSetIntegerData, ziAPIModSetByteArray
3436 */
3437ZI_EXPORT ZIResult_enum ziAPIModSetVector(ZIConnection conn, ZIModuleHandle handle, const char* path, const void* vectorData,
3438                                          ZIVectorElementType_enum elementType, unsigned int numElements);
3439
3440/// Gets the integer-type value of the specified module parameter path
3441/** This function is used to retrieve module parameter values of type integer.
3442
3443    @param[in]  conn            Pointer to ZIConnection with which the value should be retrieved.
3444    @param[in]  handle          The ::ZIModuleHandle specifying the module to get the value from.
3445    @param[in]  path            The path of the module parameter to get data from.
3446    @param[out] value           Pointer to an 64bit integer in which the value should be written
3447    @return
3448    - ZI_INFO_SUCCESS           on success
3449    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
3450    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
3451    - ZI_ERROR_COMMAND          on an incorrect answer of the server
3452    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
3453    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the path
3454    - ZI_ERROR_TIMEOUT          when communication timed out
3455    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3456
3457@sa ziAPIModGetDouble, ziApiModGetString
3458*/
3459ZI_EXPORT ZIResult_enum ziAPIModGetInteger(ZIConnection conn, ZIModuleHandle handle, const char* path, ZIIntegerData* value);
3460
3461/// Gets the double-type value of the specified module parameter path
3462/** This function is used to retrieve module parameter values of type floating point double.
3463
3464    @param[in]  conn            Pointer to ZIConnection with which the value should be retrieved
3465    @param[in]  handle          The ::ZIModuleHandle specifying the module to get the value from.
3466    @param[in]  path            The path of the module parameter to get data from.
3467    @param[out] value           Pointer to an floating point double in which the value should be written
3468    @return
3469    - ZI_INFO_SUCCESS           on success
3470    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
3471    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
3472    - ZI_ERROR_COMMAND          on an incorrect answer of the server
3473    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
3474    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the path
3475    - ZI_ERROR_TIMEOUT          when communication timed out
3476    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3477
3478@sa ziAPIModGetInteger, ziApiModGetString
3479*/
3480ZI_EXPORT ZIResult_enum ziAPIModGetDouble(ZIConnection conn, ZIModuleHandle handle, const char* path, ZIDoubleData* value);
3481
3482/// gets the null-terminated string value of the specified module parameter path
3483/** This function is used to retrieve module parameter values of type string.
3484
3485    @param[in]  conn            Pointer to the ziConnection with which the value should be retrieved
3486    @param[in]  handle          The ::ZIModuleHandle specifying the module to get the value from.
3487    @param[in]  path            The path of the module parameter to get data from.
3488    @param[out] buffer          Pointer to a buffer to store the retrieved null-terminated string
3489     @param[out] length         Pointer to an unsigned int which after the call, contains the length of
3490                                the retrieved data (including the null terminator). If the length of the
3491                                passed buffer is insufficient, the value is modified to indicate the
3492                                required minimum buffer size and ZI_ERROR_LENGTH is returned.
3493    @param[in]  bufferSize      The length of the passed buffer
3494
3495    @return
3496    - ZI_INFO_SUCCESS           on success
3497    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
3498    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
3499    - ZI_ERROR_COMMAND          on an incorrect answer of the server
3500    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
3501    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the path
3502    - ZI_ERROR_TIMEOUT          when communication timed out
3503    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3504
3505@sa ziAPIModGetInteger, ziApiModGetDouble
3506*/
3507ZI_EXPORT ZIResult_enum ziAPIModGetString(ZIConnection conn, ZIModuleHandle handle, const char* path, char* buffer,
3508                                          unsigned int* length, unsigned int bufferSize);
3509
3510/// Gets the null-terminated string value of the specified module parameter path
3511/** This function is used to retrieve module parameter values of type string.
3512
3513    @param[in]  conn            Pointer to the ziConnection with which the value should be retrieved
3514    @param[in]  handle          The ::ZIModuleHandle specifying the module to get the value from.
3515    @param[in]  path            The path of the module parameter to get data from.
3516    @param[out] wbuffer         Pointer to a buffer to store the retrieved null-terminated string
3517    @param[out] length         Pointer to an unsigned int which after the call, contains the length of
3518                                the retrieved data (including the null terminator). If the length of the
3519                                passed buffer is insufficient, the value is modified to indicate the
3520                                required minimum buffer size and ZI_ERROR_LENGTH is returned.
3521    @param[in]  bufferSize      The length of the passed buffer
3522
3523    @return
3524    - ZI_INFO_SUCCESS           on success
3525    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
3526    - ZI_ERROR_LENGTH           if the path's length exceeds MAX_PATH_LEN
3527    - ZI_ERROR_COMMAND          on an incorrect answer of the server
3528    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
3529    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the path
3530    - ZI_ERROR_TIMEOUT          when communication timed out
3531    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3532
3533@sa ziAPIModGetInteger, ziApiModGetDouble, ziAPIModGetString
3534*/
3535ZI_EXPORT ZIResult_enum ziAPIModGetStringUnicode(ZIConnection conn, ZIModuleHandle handle, const char* path, wchar_t* wbuffer,
3536                                                 unsigned int* length, unsigned int bufferSize);
3537
3538/// Gets the vector stored at the specified module parameter path
3539/** This function is used to retrieve module parameter values of type vector.
3540
3541    @param[in]     conn         Pointer to the ziConnection with which the value should be retrieved.
3542    @param[in]     handle       The ::ZIModuleHandle specifying the module to get the value from.
3543    @param[in]     path         The path of the module parameter to get data from.
3544    @param[out]    buffer       Pointer to a buffer to store the retrieved vector buffer.
3545    @param[in,out] bufferSize   Pointer to an unsigned int indicating the length of the buffer. If the length of the
3546                                passed buffer is insufficient to store the vector, the value is modified to indicate
3547                                the required minimum buffer size and ZI_ERROR_LENGTH is returned.
3548    @param[out]    elementType  Pointer to store the type of vector elements.
3549    @param[out]    numElements  Pointer to an unsigned int to store the number of elements of the vector. If the length
3550                                of the passed buffer is insufficient, a zero will be returned.
3551
3552    @return
3553    - ZI_INFO_SUCCESS           on success
3554    - ZI_ERROR_CONNECTION       when the connection is invalid (not connected) or when a communication error occurred
3555    - ZI_ERROR_LENGTH           if the vector's length exceeds the buffer size
3556    - ZI_ERROR_COMMAND          on an incorrect answer of the server
3557    - ZI_ERROR_SERVER_INTERNAL  if an internal error occurred in Data Server
3558    - ZI_WARNING_NOTFOUND       if the given path could not be resolved or no value is attached to the path
3559    - ZI_ERROR_TIMEOUT          when communication timed out
3560    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3561
3562@sa ziAPIModGetInteger, ziApiModGetDouble, ziAPIModGetString
3563*/
3564ZI_EXPORT ZIResult_enum ziAPIModGetVector(ZIConnection conn, ZIModuleHandle handle, const char *path, void* buffer,
3565                                          unsigned int *bufferSize, ZIVectorElementType_enum *elementType,
3566                                          unsigned int *numElements);
3567
3568/// Returns all child parameter node paths found under the specified parent module parameter path
3569/** This function returns a list of parameter names found at the specified path. The path may contain wildcards. The
3570    list is returned in a null-terminated char-buffer, each element delimited by a newline. If the maximum length of
3571    the buffer (bufferSize) is not sufficient for all elements, nothing will be returned and the return value will be
3572    ::ZI_ERROR_LENGTH.
3573
3574    @param[in]  conn            The ::ZIConnection from which the module was created.
3575    @param[in]  handle          The ::ZIModuleHandle from which the parameter names should be retrieved.
3576    @param[in]  path            Path for which all children will be returned. The path may contain wildcard characters.
3577    @param[out] nodes           Upon call filled with newline-delimited list of the names of all the children found.
3578                                The string is zero-terminated.
3579    @param[in]  bufferSize      The length of the buffer specified as the nodes output parameter.
3580    @param[in]  flags           A combination of flags (applied bitwise) as defined in ::ZIListNodes_enum.
3581
3582    @return
3583    - ZI_INFO_SUCCESS           On success
3584    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3585    - ZI_ERROR_LENGTH           If the path's length exceeds ::MAX_PATH_LEN or the length of the char-buffer for the
3586                                nodes given by bufferSize is too small for all elements.
3587    - ZI_ERROR_COMMAND          On an incorrect answer of the server.
3588    - ZI_ERROR_SERVER_INTERNAL  If an internal error occurred in Data Server.
3589    - ZI_WARNING_NOTFOUND       If the given path could not be resolved.
3590    - ZI_ERROR_TIMEOUT          When communication timed out.
3591    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3592    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3593
3594 */
3595ZI_EXPORT ZIResult_enum ziAPIModListNodes(ZIConnection conn, ZIModuleHandle handle, const char* path, char* nodes,
3596                                          uint32_t bufferSize, uint32_t flags);
3597
3598/// Returns all child parameter node paths found under the specified parent module parameter path
3599/** This function returns a list of node names found at the specified path, formatted as JSON. The path may
3600    contain wildcards so that the returned nodes do not necessarily have to have the same parents.
3601    The list is returned in a null-terminated char-buffer. If the maximum length of the buffer (bufferSize) is
3602    not sufficient for all elements, nothing will be returned and the return value will be ::ZI_ERROR_LENGTH.
3603
3604    @param[in]   conn        The ::ZIConnection from which the module was created.
3605    @param[in]   handle      The ::ZIModuleHandle from which the parameter names should be retrieved.
3606    @param[in]   path        Path for which all children will be returned. The path may contain wildcard characters.
3607    @param[out]  nodes       Upon call filled with JSON-formatted list of the names of all the children found.
3608                             The string is zero-terminated.
3609    @param[in]   bufferSize  The length of the buffer used for the nodes output parameter.
3610    @param[in]   flags       A combination of flags (applied bitwise) as defined in ::ZIListNodes_enum.
3611
3612    @return
3613    - ZI_INFO_SUCCESS           On success
3614    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3615    - ZI_ERROR_LENGTH           If the path's length exceeds ::MAX_PATH_LEN or the length of the char-buffer for the
3616                                nodes given by bufferSize is too small for all elements.
3617    - ZI_ERROR_COMMAND          On an incorrect answer of the server.
3618    - ZI_ERROR_SERVER_INTERNAL  If an internal error occurred in Data Server.
3619    - ZI_WARNING_NOTFOUND       If the given path could not be resolved.
3620    - ZI_ERROR_TIMEOUT          When communication timed out.
3621    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3622    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3623
3624 */
3625ZI_EXPORT ZIResult_enum ziAPIModListNodesJSON(ZIConnection conn, ZIModuleHandle handle, const char* path, char* nodes,
3626                                              uint32_t bufferSize, uint32_t flags);
3627
3628/// Subscribes to the nodes specified by path, these nodes will be recorded during module execution.
3629/** This function subscribes to nodes so that whenever the value of the node changes while the module is executing the
3630    new value will be accumulated and then read using ::ziAPIModRead. By using wildcards or by using a path that is not
3631    a leaf node but contains sub nodes, more than one leaf can be subscribed to with one function call.
3632
3633    @param[in]  conn            The ::ZIConnection from which the module was created.
3634    @param[in]  handle          The ::ZIModuleHandle specifying the module in which the nodes should be subscribed to.
3635    @param[in]  path            Path specifying the nodes to subscribe to, may contain wildcards.
3636
3637    @return
3638    - ZI_INFO_SUCCESS           On success.
3639    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or a general error occurred, enable
3640                                ziAPI's log for detailed information, see ::ziAPISetDebugLevel.
3641    - ZI_ERROR_LENGTH           If the Path's Length exceeds MAX_PATH_LEN.
3642    - ZI_ERROR_COMMAND          On an incorrect answer of the server.
3643    - ZI_ERROR_SERVER_INTERNAL  If an internal error occurred in the Data Server.
3644    - ZI_WARNING_NOTFOUND       If the given path could not be resolved or no node given by path is able
3645                                to hold values.
3646    - ZI_ERROR_TIMEOUT          When communication timed out.
3647    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3648    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3649
3650   @sa ziAPIModUnSubscribe, ziAPIModRead
3651*/
3652ZI_EXPORT ZIResult_enum ziAPIModSubscribe(ZIConnection conn, ZIModuleHandle handle, const char* path);
3653
3654/// Unsubscribes to the nodes specified by path.
3655/** This function is the complement to ::ziAPIModSubscribe. By using wildcards or by using a path that is not a leaf
3656    node but contains sub nodes, more than one node can be unsubscribed with one function call.
3657
3658    @param[in]  conn            The ::ZIConnection from which the module was created.
3659    @param[in]  handle          The ::ZIModuleHandle specifyin the module in which the nodes should be unsubscribed
3660                                from.
3661    @param[in]  path            Path specifying the nodes to unsubscribe from, may contain wildcards.
3662
3663    @return
3664    - ZI_INFO_SUCCESS           On success.
3665    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3666    - ZI_ERROR_LENGTH           If the Path's Length exceeds MAX_PATH_LEN.
3667    - ZI_ERROR_COMMAND          On an incorrect answer of the server.
3668    - ZI_ERROR_SERVER_INTERNAL  If an internal error occurred in the Data Server.
3669    - ZI_WARNING_NOTFOUND       If the given path could not be resolved or no node given by path is able
3670                                to hold values.
3671    - ZI_ERROR_TIMEOUT          When communication timed out.
3672    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3673    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3674
3675    @sa ziAPIModSubscribe, ziAPIModRead
3676*/
3677ZI_EXPORT ZIResult_enum ziAPIModUnSubscribe(ZIConnection conn, ZIModuleHandle handle, const char* path);
3678
3679/// Starts the module's thread and its associated measurement task.
3680/** Once the module's parameters has been configured as required via, e.g. ::ziAPIModSetDoubleData, this function
3681    starts the module's thread. This starts the module's main measurement task which will run asynchronously.
3682    The thread will run until either the module has completed its task or until ::ziAPIModFinish is called.
3683    Subscription or unsubscription is not possible while the module is executing. The status of the module can be
3684    obtained with either ::ziAPIModFinished or ::ziAPIModProgress.
3685
3686    @param[in]  conn            The ::ZIConnection from which the module was created.
3687    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3688
3689    @return
3690    - ZI_INFO_SUCCESS           On success.
3691    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3692    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3693    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3694
3695    @sa ziAPIModCreate, ziAPIModProgress, ziAPIModFinish
3696*/
3697ZI_EXPORT ZIResult_enum ziAPIModExecute(ZIConnection conn, ZIModuleHandle handle);
3698
3699/// Manually issue a trigger forcing data recording (SW Trigger Module only).
3700/** This function is used with the Software Trigger Module in order to manually issue a trigger in order to force
3701 *  recording of data. A burst of subscribed data will be recorded as configured via the SW Trigger's parameters as
3702 *  would a regular trigger event.
3703
3704    @param[in]  conn            The ::ZIConnection from which the module was created.
3705    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3706
3707    @return
3708    - ZI_INFO_SUCCESS           On success.
3709    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3710    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3711    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3712
3713*/
3714ZI_EXPORT ZIResult_enum ziAPIModTrigger(ZIConnection conn, ZIModuleHandle handle);
3715
3716/// Queries the current state of progress of the module's measurement task.
3717/** This function can be used to query the module's progress in performing its current measurement task, the progress
3718    is returned as a double in [0, 1], where 1 indicates task completion.
3719
3720    @param[in]  conn            The ::ZIConnection from which the module was created.
3721    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3722    @param[out] progress        A pointer to ZIDoubleData indicating the current progress of the module.
3723
3724    @return
3725    - ZI_INFO_SUCCESS           On success.
3726    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3727    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3728    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3729
3730    @sa ziAPIModExecute, ziAPIModFinish, ziAPIModFinished
3731*/
3732ZI_EXPORT ZIResult_enum ziAPIModProgress(ZIConnection conn, ZIModuleHandle handle, ZIDoubleData* progress);
3733
3734/// Queries whether the module has finished its measurement task.
3735/** This function can be used to query whether the module has finished its task or not.
3736
3737    @param[in]  conn            The ::ZIConnection from which the module was created.
3738    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3739    @param[out] finished        A pointer to ZIIntegerData, upon return this will be 0 if the module is still
3740                                executing or 1 if it has finished executing.
3741
3742    @return
3743    - ZI_INFO_SUCCESS           On success.
3744    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3745    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3746    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3747
3748    @sa ziAPIModExecute, ziAPIModFinish, ziAPIModProgress
3749*/
3750ZI_EXPORT ZIResult_enum ziAPIModFinished(ZIConnection conn, ZIModuleHandle handle, ZIIntegerData* finished);
3751
3752/// Stops the module performing its measurement task.
3753/** This functions stops the module performing its associated measurement task and stops recording any data. The task
3754    and data recording may be restarted by calling ::ziAPIModExecute' again.
3755
3756    @param[in]  conn            The ::ZIConnection from which the module was created.
3757    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3758
3759    @return
3760    - ZI_INFO_SUCCESS           On success.
3761    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3762    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3763    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3764
3765    @sa ziAPIModProgress, ziAPIModFinished
3766*/
3767ZI_EXPORT ZIResult_enum ziAPIModFinish(ZIConnection conn, ZIModuleHandle handle);
3768
3769/// Saves the currently accumulated data to file.
3770/** This function saves the currently accumulated data to a file. The path of the file to save data to is specified via
3771    the module's directory parameter.
3772
3773    @param[in]  conn            The ::ZIConnection from which the module was created.
3774    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3775    @param[in]  fileName        The basename of the file to save the data in.
3776
3777    @return
3778    - ZI_INFO_SUCCESS           On success.
3779    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3780    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3781    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3782
3783    @sa ziAPIModExecute, ziAPIModFinish, ziAPIModFinished
3784*/
3785ZI_EXPORT ZIResult_enum ziAPIModSave(ZIConnection conn, ZIModuleHandle handle, const char* fileName);
3786
3787/// Make the currently accumulated data available for use in the C program.
3788/** This function can be used to either read (get) module parameters, in this case a path that addresses the module
3789    must be specified, or it can be used to read out the currently accumulated data from subscribed nodes in the
3790    module. In either case the actual data must then be accessed by the user using ::ziAPIModNextNode and
3791    ::ziAPIModGetChunk.
3792
3793
3794    @param[in]  conn            The ::ZIConnection from which the module was created.
3795    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3796    @param[in]  path            The path specifying the module parameter(s) to get, specify NULL to obtain all
3797                                subscribed data.
3798
3799    @return
3800    - ZI_INFO_SUCCESS           On success.
3801    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3802    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3803    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3804
3805    @sa ziAPIModGetChunk, ziAPIModNextNode
3806*/
3807ZI_EXPORT ZIResult_enum ziAPIModRead(ZIConnection conn, ZIModuleHandle handle, const char* path);
3808
3809/// Make the data for the next node available for reading with ::ziAPIModGetChunk.
3810/** After callin ::ziAPIModRead, subscribed data (or module parameters) may now be read out on a node-by-node and
3811    chunk-by-chunk basis. All nodes with data available in the module can be iterated over by using ziAPIModNextNode,
3812    then for each node the chunks of data available are read out using ::ziAPIModGetChunk. Calling this function makes
3813    the data from the next node available for read.
3814
3815    @param[in]  conn            The ::ZIConnection from which the module was created.
3816    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3817    @param[out] path            A string specifying the node's path whose data chunk points to.
3818    @param[in]  bufferSize      The length of the buffer specified as the path output parameter.
3819    @param[out] valueType       The ::ZIValueType_enum of the node's data.
3820    @param[out] chunks          The number of chunks of data available for the node.
3821
3822    @return
3823    - ZI_INFO_SUCCESS           On success.
3824    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3825    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3826    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3827
3828    @sa ziAPIModRead, ziAPIModGetChunk, ziAPIModEventDeallocate
3829*/
3830ZI_EXPORT ZIResult_enum ziAPIModNextNode(ZIConnection conn, ZIModuleHandle handle, char* path, uint32_t bufferSize,
3831                                         ZIValueType_enum* valueType, uint64_t* chunks);
3832
3833/// Get the specified data chunk from the current node.
3834/** Data is read out node-by-node and then chunk-by-chunk. This function can be used to obtain specific data chunks
3835    from the current node that data is being read from. More precisely, it ppreallocates space for an event structure
3836    big enough to hold the node's data at the specified chunk index, updates ::ZIModuleEventPtr to point to this space
3837    and then copies the chunk data to this space.
3838
3839    Note, before the very first call to ziAPIModGetChunk, the ::ZIModuleEventPtr should be initialized to NULL and then
3840    left untouched for all subsequent calls (even after calling ::ziAPIModNextNode to get data from the next node).
3841    This is because ziAPIModGetChunk internally manages the required space allocation for the event and then in
3842    subsequent calls only reallocates space when it is required. It is optimized to reduce the number of required space
3843    reallocations for the event.
3844
3845    The ::ZIModuleEventPtr should be deallocated using ::ziAPIModEventDeallocate, otherwise the lifetime of the
3846    ::ZIModuleEventPtr is the same as the lifetime of the module. Indeed, the same ::ZIModuleEventPtr can be used, even
3847    for subsequent reads. It is also possible to work with multiple ::ZIModuleEventPtr so that some pointers can be
3848    kept for later processing.
3849
3850    @param[in]  conn            The ::ZIConnection from which the module was created.
3851    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3852    @param[out] chunkIndex      The index of the data chunk to update the pointer to.
3853    @param[out] ev              The module's ::ZIModuleEventPtr that points to the currently available data chunk.
3854
3855    @return
3856    - ZI_INFO_SUCCESS           On success.
3857    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3858    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3859    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3860
3861    @sa ziAPIModRead, ziAPIModNextNode, ziAPIModEventDeallocate
3862*/
3863ZI_EXPORT ZIResult_enum ziAPIModGetChunk(ZIConnection conn, ZIModuleHandle handle, uint64_t chunkIndex,
3864                                         ZIModuleEventPtr* ev);
3865
3866/// Deallocate the ::ZIModuleEventPtr being used by the module.
3867/** This function deallocates the ZIModuleEventPtr. Since a module event's allocated space is managed internally by
3868    ::ziAPIModGetChunk, when the user no longer requires the event (all data has been read out) it must be deallocated
3869    by the user with this function.
3870
3871    @param[in]  conn            The ::ZIConnection from which the module was created.
3872    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3873    @param[in]  ev              The ::ZIModuleEventPtr to deallocate.
3874
3875    @return
3876    - ZI_INFO_SUCCESS           On success.
3877    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3878    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3879    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3880
3881    @sa ziAPIModGetChunk, ziAPIModRead
3882*/
3883ZI_EXPORT ZIResult_enum ziAPIModEventDeallocate(ZIConnection conn, ZIModuleHandle handle, ZIModuleEventPtr ev);
3884
3885/// Terminates the module's thread and destroys the module.
3886/** This function terminates the module's thread, releases memory and resources.
3887    After calling ziAPIModClear the module's handle may not be used any
3888    more. A new instance of the module must be initialized if required.
3889    This command is especially important if modules are created repetitively
3890    inside a while or for loop, in order to prevent excessive memory and resource consumption.
3891
3892    @param[in]  conn            The ::ZIConnection from which the module was created.
3893    @param[in]  handle          The ::ZIModuleHandle specifying the module to execute.
3894
3895    @return
3896    - ZI_INFO_SUCCESS           On success.
3897    - ZI_ERROR_CONNECTION       When the connection is invalid (not connected) or when a communication error occurred.
3898    - ZI_ERROR_GENERAL          If a general error occurred, use ::ziAPIGetLastError for a detailed error message.
3899    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
3900
3901    @sa ziAPIModExecute, ziAPIModFinish
3902*/
3903ZI_EXPORT ZIResult_enum ziAPIModClear(ZIConnection conn, ZIModuleHandle handle);
3904
3905/** @} */  // end of group modules
3906
3907/** @defgroup Vector Vector operations
3908 *  @brief Functions for working with vector data.
3909 *  @{
3910 */
3911
3912/// vectorElementType - see ::ZIVectorElementType_enum
3913ZI_EXPORT ZIResult_enum ziAPISetVector(ZIConnection conn, const char* path, const void* vectorData,
3914                                       uint8_t vectorElementType, uint64_t vectorSizeElements);
3915
3916/** @} */  // end of group Vector
3917
3918#if defined(ZI_API_EXPERIMENTAL)
3919
3920/** @defgroup Transactions Transactional commands
3921 *  @brief Functions for handling transactional set commands.
3922 *  @{
3923 *
3924 *  @warning The functions in here are experimental and may break without
3925 *  further notice. You may opt in to use these functions through definition of
3926 *  ZI_API_EXPERIMENTAL.
3927 */
3928
3929/// Begin a transaction.
3930ZI_EXPORT ZIResult_enum ziAPIBeginTransaction(ZIConnection conn);
3931
3932/// Ends a transaction.
3933ZI_EXPORT ZIResult_enum ziAPIEndTransaction(ZIConnection conn);
3934
3935/// @sa ziAPISetValueI
3936ZI_EXPORT ZIResult_enum ziAPITransactionalSetInt(ZIConnection conn, const char* path, ZIIntegerData value);
3937
3938/// @sa ziAPISetValueD
3939ZI_EXPORT ZIResult_enum ziAPITransactionalSetDouble(ZIConnection conn, const char* path, ZIDoubleData value);
3940
3941/// @sa ziAPISetComplexData
3942ZI_EXPORT ZIResult_enum ziAPITransactionalSetComplex(ZIConnection conn, const char* path, ZIDoubleData real, ZIDoubleData imag);
3943
3944/// @sa ziAPISetValueB
3945ZI_EXPORT ZIResult_enum ziAPITransactionalSetBytes(ZIConnection conn, const char* path, unsigned char* buffer, unsigned int length);
3946
3947/// @sa ziAPISetVector
3948ZI_EXPORT ZIResult_enum ziAPITransactionalSetVector(ZIConnection conn, const char* path, const void* vectorData,
3949                                                    uint8_t vectorElementType, uint64_t vectorSizeElements);
3950
3951/** @} */  // end of group Transactions
3952
3953#endif  // ZI_API_EXPERIMENTAL
3954
3955/** @defgroup Sequencer Sequencer commands
3956 *  @brief Functions for working with SeqC programs and waveforms.
3957 *  @{
3958 */
3959
3960/// Defines the return structure for ::ziAPICompileSeqC.
3961struct ZICompileResult {
3962  /// ELF binary output
3963  uint8_t* elf;
3964  /// Size of ELF data
3965  unsigned int size;
3966  /// Zero-terminated JSON string with extra information. The "message" element
3967  /// contains the compiler output.
3968  char* extra;
3969};
3970
3971#ifndef __cplusplus
3972typedef struct ZICompileResult ZICompileResult;
3973#endif
3974
3975/// Allocates ::ZICompileResult structure and returns a pointer to it.
3976/** This function allocates a ::ZICompileResult structure and returns a pointer to
3977    it. The memory must be freed using ::ziAPIDeallocateCompileResult.
3978
3979    @sa ziAPIDeallocateCompileResult
3980*/
3981ZI_EXPORT ZICompileResult* ziAPIAllocateCompileResult(void);
3982
3983/// Deallocates ::ZICompileResult structure created with ::ziAPIAllocateCompileResult.
3984/** This function is the complement to ::ziAPIAllocateCompileResult.
3985
3986    @param[in] result Pointer to ::ZICompileResult structure to be deallocated.
3987
3988    @sa ziAPIAllocateCompileResult
3989*/
3990ZI_EXPORT void ziAPIDeallocateCompileResult(ZICompileResult* result);
3991
3992/// Compile a SeqC program for a sequencer.
3993/** Compile the sequencer program and return the ELF data for upload to an
3994    instrument.
3995
3996    @param[in]  source            SeqC input
3997    @param[in]  deviceType        Target device type, e.g., HDAWG8, SHFQC
3998    @param[in]  deviceOptions     List of device options, separated by newlines
3999                                  as returned by node `/dev.../features/options`.
4000    @param[in]  coreIndex         Index of the AWG core
4001    @param[in]  kwargs            JSON object with keyword arguments.
4002    @param[out] result            Structure to populate with compiler result.
4003                                  Holds the ELF data and extra output as JSON.
4004
4005    @return
4006     - ZI_INFO_SUCCESS            on success
4007     - ZI_ERROR_GENERAL           if an error occured during compilation
4008     - ZI_ERROR_INVALID_ARGUMENT  if an invalid argument was provided
4009     - In case of error, the "message" property in the extra output contains the
4010       precise error reason.
4011
4012    Keyword arguments (JSON):
4013    - `samplerate` (float): target sample rate of the sequencer.
4014      Mandatory and only respected for HDAWG. Should match the value set on the device:
4015      `/dev.../system/clocks/sampleclock/freq`.
4016    - `sequencer` (str): one of `qa`, `sg`, or `auto`. Mandatory for SHFQC.
4017    - `wavepath` (str): path to directory with waveforms.
4018      Defaults to path used by LabOne UI or AWG Module.
4019    - `waveform` (str): list of CSV waveform files separated by `;`.
4020      Defaults to all CSV files in `wavepath`.
4021    - `output` (str): name of embedded ELF filename.
4022
4023    @sa ziAPIAllocateCompileResult, ziAPIDeallocateCompileResult,
4024        ZICompileResult
4025 */
4026ZI_EXPORT ZIResult_enum ziAPICompileSeqC(const char* source, const char* deviceType, const char* deviceOptions,
4027                                         unsigned int coreIndex, const char *kwargs, ZICompileResult* result);
4028
4029/** @} */  // end of group Sequencer
4030
4031/** @defgroup Discovery Device discovery
4032 *  @brief Functions for working with device Discovery.
4033 *  @{
4034 */
4035
4036/// Defines the values of the Discovery property 'statusflags' retrieved by ::ziAPIDiscoveryGetValueI
4037enum ZIDeviceStatus_enum
4038{
4039  ZI_DEVICE_STATUS_NOT_YET_READY          = 0x0001,
4040  ZI_DEVICE_STATUS_FREE                   = 0x0002,
4041  ZI_DEVICE_STATUS_IN_USE_BY              = 0x0004,
4042  ZI_DEVICE_STATUS_FW_UPGRADE_USB         = 0x0008,
4043  ZI_DEVICE_STATUS_FW_UPGRADE_REQUIRED    = 0x0010,
4044  ZI_DEVICE_STATUS_FW_UPGRADE_AVAILABLE   = 0x0020,
4045  ZI_DEVICE_STATUS_FW_DOWNGRADE_REQUIRED  = 0x0040,
4046  ZI_DEVICE_STATUS_FW_DOWNGRADE_AVAILABLE = 0x0080,
4047  ZI_DEVICE_STATUS_FW_UPDATE_IN_PROGRESS  = 0x0100,
4048  ZI_DEVICE_STATUS_DEVICE_UNKNOWN         = 0x0200
4049};
4050
4051/** Perform a Discovery property look-up for the specified deviceAddress and return its device ID. Attention! This
4052    invalidates all pointers previously returned by ziAPIDiscovery* calls. The deviceId need not be deallocated by the
4053    user.
4054
4055    @param[in]  conn          Pointer to ::ZIConnection with which the value should be retrieved.
4056    @param[out] deviceIds     Pointer to a buffer that is to contain the list of newline-separated
4057                              IDs of the devices found, e.g. "DEV2006\nDEV2007\n".
4058    @param[in]  bufferSize    The size of the buffer pointed to by deviceIds. If the buffer is too small
4059                              to hold the complete list of device IDs, its contents remain unchanged.
4060
4061    @return
4062    - ZI_INFO_SUCCESS
4063    - ZI_ERROR_LENGTH         The provided buffer is too small to hold the list.
4064    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
4065
4066    @sa ziAPIDiscoveryFind, ziAPIDiscoveryGet, ziAPIDiscoveryGetValueI, ziAPIDiscoveryGetValueS
4067*/
4068ZI_EXPORT ZIResult_enum ziAPIDiscoveryFindAll(ZIConnection conn, char* deviceIds, uint32_t bufferSize);
4069
4070/** Perform a Discovery property look-up for the specified deviceAddress and return its device ID. Attention! This
4071    invalidates all pointers previously returned by ziAPIDiscovery* calls. The deviceId need not be deallocated by the
4072    user.
4073
4074    @param[in]  conn          Pointer to ::ZIConnection with which the value should be retrieved.
4075    @param[in]  deviceAddress The address or ID of the device to find, e.g., 'uhf-dev2006' or 'dev2006'.
4076    @param[out] deviceId      The ID of the device that was found, e.g. 'DEV2006'.
4077
4078    @return
4079    - ZI_INFO_SUCCESS
4080    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
4081
4082    @sa ziAPIDiscoveryFindAll, ziAPIDiscoveryGet, ziAPIDiscoveryGetValueI, ziAPIDiscoveryGetValueS
4083*/
4084ZI_EXPORT ZIResult_enum ziAPIDiscoveryFind(ZIConnection conn, const char* deviceAddress, const char** deviceId);
4085
4086/** Returns the device Discovery properties for a given device ID in JSON format. The function ::ziAPIDiscoveryFind must
4087    be called before ziAPIDiscoveryGet can be used. The propsJSON need not be deallocated by the user.
4088
4089    @param[in]  conn          Pointer to ::ZIConnection with which the value should be retrieved.
4090    @param[in]  deviceId      The ID of the device to get Discovery information for, as returned by
4091                              ::ziAPIDiscoveryFind, e.g., 'dev2006'.
4092    @param[out] propsJSON     The Discovery properites in JSON format of the specified device.
4093
4094    @return
4095    - ZI_INFO_SUCCESS
4096    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
4097
4098    @sa ziAPIDiscoveryFind, ziAPIDiscoveryGetValueI, ziAPIDiscoveryGetValueS
4099*/
4100ZI_EXPORT ZIResult_enum ziAPIDiscoveryGet(ZIConnection conn, const char* deviceId, const char** propsJSON);
4101
4102/** Returns the specified integer Discovery property value for a given device ID. The function ::ziAPIDiscoveryFind must
4103    be called with the required device ID before using ziAPIDiscoveryGetValueI.
4104
4105    @param[in]  conn          Pointer to ::ZIConnection with which the value should be retrieved.
4106    @param[in]  deviceId      The ID of the device to get Discovery information for, as returned by
4107                              ::ziAPIDiscoveryFind, e.g., 'dev2006'.
4108    @param[in]  propName      The name of the desired integer Discovery property.
4109    @param[out] value         Pointer to the value of the specified Discovery property.
4110
4111    @return
4112    - ZI_INFO_SUCCESS
4113    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
4114
4115    @sa ziAPIDiscoveryFind, ziAPIDiscoveryGet, ziAPIDiscoveryGetValueS
4116*/
4117ZI_EXPORT ZIResult_enum ziAPIDiscoveryGetValueI(ZIConnection conn, const char* deviceId, const char* propName,
4118                                                ZIIntegerData* value);
4119
4120/** Returns the specified string Discovery property value for a given device ID. The function ::ziAPIDiscoveryFind must
4121    be called with the required device ID before using ziAPIDiscoveryGetValueS. The value must not be deallocated by the
4122    user.
4123
4124    @param[in]  conn          Pointer to ::ZIConnection with which the value should be retrieved.
4125    @param[in]  deviceId      The ID of the device to get Discovery information for, as returned by
4126                              ::ziAPIDiscoveryFind, e.g., 'dev2006'.
4127    @param[in]  propName      The name of the desired integer Discovery property.
4128    @param[out] value         Pointer to the value of the specified Discovery property.
4129
4130    @return
4131    - ZI_INFO_SUCCESS
4132    - Other return codes may also be returned, for a detailed error message use ::ziAPIGetLastError.
4133
4134    @sa ziAPIDiscoveryFind, ziAPIDiscoveryGet, ziAPIDiscoveryGetValueI
4135*/
4136ZI_EXPORT ZIResult_enum ziAPIDiscoveryGetValueS(ZIConnection conn, const char* deviceId, const char* propName,
4137                                                const char** value);
4138
4139/** @} */  // end of group Discovery
4140
4141
4142typedef ZIValueType_enum DEPRECATED(ziAPIDataType);
4143typedef ZITimeStamp DEPRECATED(ziTimeStampType);
4144typedef ZIResult_enum DEPRECATED(ZI_STATUS);
4145typedef ZIConnection DEPRECATED(ziConnection);
4146typedef ZIDoubleData DEPRECATED(ziDoubleType);
4147typedef ZIIntegerData DEPRECATED(ziIntegerType);
4148
4149/// The DemodSample struct holds data for the ZI_DATA_DEMODSAMPLE data type. Deprecated: See ::ZIDemodSample.
4150struct DEPRECATED(DemodSample {
4151  /// Time stamp at which the sample has been measured
4152  ziTimeStampType TimeStamp;
4153
4154  /// X part of the sample
4155  double X;
4156  /// Y part of the sample
4157  double Y;
4158
4159  /// oscillator frequency at that sample
4160  double Frequency;
4161  /// oscillator phase at that sample
4162  double Phase;
4163
4164  /// the current bits of the DIO
4165  unsigned int DIOBits;
4166
4167  /// reserved uint to maintain 8bytes alignment
4168  unsigned int Reserved;
4169
4170  /// values of Aux inputs
4171  double AuxIn0;
4172  double AuxIn1;
4173});
4174
4175#ifndef __cplusplus
4176typedef struct DemodSample DEPRECATED(DemodSample);
4177#endif
4178
4179/// The AuxInSample struct holds data for the ZI_DATA_AUXINSAMPLE data type. Deprecated: See ::ZIAuxInSample.
4180struct DEPRECATED(AuxInSample {
4181  /// Time stamp at which the values have been measured
4182  ziTimeStampType TimeStamp;
4183
4184  /// Channel 0 voltage
4185  double Ch0;
4186  /// Channel 1 voltage
4187  double Ch1;
4188});
4189
4190#ifndef __cplusplus
4191typedef struct AuxInSample DEPRECATED(AuxInSample);
4192#endif
4193
4194/// The DIOSample struct holds data for the ZI_DATA_DIOSAMPLE data type. Deprecated: See ::ZIDIOSample.
4195struct DEPRECATED(DIOSample {
4196  /// The timestamp at which the values have been measured.
4197  ziTimeStampType TimeStamp;
4198
4199  /// The value of the DIO.
4200  unsigned int Bits;
4201
4202  /// Alignment to 8 bytes.
4203  unsigned int Reserved;
4204});
4205
4206#ifndef __cplusplus
4207typedef struct DIOSample DEPRECATED(DIOSample);
4208#endif
4209
4210/// TREE_ACTION defines the values for the TreeChange::Action Variable
4211enum TREE_ACTION {
4212#ifdef _MSC_VER
4213  /// a tree has been removed
4214  TREE_ACTION_REMOVE = 0,
4215
4216  /// a tree has been added
4217  TREE_ACTION_ADD = 1,
4218
4219  /// a tree has changed
4220  TREE_ACTION_CHANGE = 2
4221#else
4222  /* empty enums are not allowed in ANSI C (gcc) */
4223  TREE_ACTION_REMOVE_DUMMY_FOR_ANSI_C = 0,
4224  TREE_ACTION_ADD_DUMMY_FOR_ANSI_C = 1,
4225  TREE_ACTION_CHANGE_DUMMY_FOR_ANSI_C = 2
4226#endif
4227};
4228
4229#ifndef __cplusplus
4230typedef enum TREE_ACTION TREE_ACTION;
4231#endif
4232
4233#ifdef _MSC_VER
4234#pragma deprecated(TREE_ACTION_REMOVE)
4235#pragma deprecated(TREE_ACTION_ADD)
4236#pragma deprecated(TREE_ACTION_CHANGE)
4237#else
4238
4239#ifdef __cplusplus
4240#define TREE_ACTION_cast(val) TREE_ACTION(val)
4241#else
4242#define TREE_ACTION_cast(val) val
4243#endif
4244
4245DEPRECATED_ENUM(const TREE_ACTION TREE_ACTION_REMOVE   = TREE_ACTION_cast(0));
4246DEPRECATED_ENUM(const TREE_ACTION TREE_ACTION_ADD      = TREE_ACTION_cast(1));
4247DEPRECATED_ENUM(const TREE_ACTION TREE_ACTION_CHANGE   = TREE_ACTION_cast(2));
4248#endif
4249
4250#ifdef _MSC_VER
4251// Visual C++ specific
4252#pragma warning(push)
4253#pragma warning(disable:4200)
4254#endif
4255
4256/// The ByteArrayData struct holds data for the ZI_DATA_BYTEARRAY data type. Deprecated: See ::ZIByteArray.
4257struct DEPRECATED(ByteArrayData {
4258  /// length of the data readable from the Bytes field
4259  unsigned int Len;
4260  /// the data itself. The array has the size given in Len
4261  unsigned char Bytes[0];
4262});
4263
4264#ifndef __cplusplus
4265typedef struct ByteArrayData DEPRECATED(ByteArrayData);
4266#endif
4267
4268#ifdef _MSC_VER
4269// Visual C++ specific
4270#pragma warning(pop)
4271#endif
4272
4273/// This struct holds event data forwarded by the Data Server. Deprecated: See ::ZIEvent.
4274/**
4275 *  @ingroup DataHandling
4276    ziEvent is used to give out events like value changes or errors to the user. Event handling functionality is
4277    provided by ziAPISubscribe and ziAPIUnSubscribe as well as ziAPIPollDataEx.
4278
4279    @sa ziAPISubscribe, ziAPIUnSubscribe, ziAPIPollDataEx
4280 */
4281struct DEPRECATED(ziEvent {
4282  /// Specifies the type of the data held by the ziEvent
4283  uint32_t Type;
4284
4285  /// Number of values available in this event
4286  uint32_t Count;
4287
4288  /// The path to the node from which the event originates
4289  unsigned char Path[MAX_PATH_LEN];
4290
4291  /// Convenience pointer to allow for access to the first entry in Data using the correct type
4292  /// according to ziEvent::Type field.
4293  union Val {
4294    /// For convenience. The void field doesn't have a corresponding data type.
4295    void* Void;
4296
4297    /// Data of type ZI_DATA_DEMODSAMPLE
4298    DemodSample* SampleDemod;
4299
4300    /// Data of type ZI_DATA_AUXINSAMPLE
4301    AuxInSample* SampleAuxIn;
4302
4303    /// Data of type ZI_DATA_DIOSAMPLE
4304    DIOSample* SampleDIO;
4305
4306    /// Data of type ZI_DATA_DOUBLE
4307    ziDoubleType* Double;
4308
4309    /// Data of type ZI_DATA_INTEGER
4310    ziIntegerType* Integer;
4311
4312    /// Data of type ZI_DATA_TREE_CHANGED
4313    TreeChange* Tree;
4314
4315    /// Data of type ZI_DATA_BYTEARRAY
4316    ByteArrayData* ByteArray;
4317
4318    /// Data of type ZI_DATA_SCOPEWAVE
4319    ScopeWave* Wave;
4320
4321    /// ensure union size is 8 bytes
4322    uint64_t alignment;
4323  } Val;
4324
4325  /// The raw value data
4326  unsigned char Data[ MAX_EVENT_SIZE ];
4327});
4328
4329#ifndef __cplusplus
4330typedef struct ziEvent DEPRECATED(ziEvent);
4331#endif
4332
4333/// @deprecated
4334/// Converts a ziTimeStampType into a double-type representing seconds.
4335/**
4336     Deprecated: timestamps should instead be converted to seconds by dividing by the instrument's
4337     "clockbase". This is available as an leaf under the instrument's root "device" branch in the node
4338     hierarchy, e.g., /dev2001/clockbase.
4339
4340     @param[in] TS the timestamp to convert to seconds
4341     @return The timestamp in seconds as a double
4342*/
4343DEPRECATED(double ZI_EXPORT ziAPISecondsTimeStamp(ziTimeStampType TS));
4344
4345#define ZI_ERROR(dummy, result) return result;
4346
4347#ifdef __GNUC__
4348#if __GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 6
4349// Only supported by GCC >= 4.6
4350#pragma GCC diagnostic pop
4351#else
4352// There is no way for GCC < 4.6 to restore the previously set diagnostic level (push/pop is not supported),
4353// therefore we just set it to the default "warning" level. Unwanted side effect - it will be set to warning
4354// for the remainder of any file that includes ziAPI.h, even if it was changed via command line or with another
4355// pragma.
4356#pragma GCC diagnostic warning "-Wdeprecated-declarations"
4357#endif
4358#elif defined(_MSC_VER)
4359// Visual C++ specific
4360// restore 4996 - declared deprecated
4361#pragma warning(pop)
4362#endif
4363
4364#ifdef __cplusplus
4365}  // extern "C"
4366#endif
4367
4368#endif  // ZI_API_H
4369// clang-format on