Set and Get Parameters#

group Parameters

This section describes several functions for getting and setting parameters of different datatypes.

Functions

ZIResult_enum ziAPIGetValueD(ZIConnection conn, const char *path, ZIDoubleData *value)

gets the double-type value of the specified node

This function retrieves the numerical value of the specified node as an double-type value. The value first found is returned if more than one value is available (a wildcard is used in the path).

// Copyright [2018] Zurich Instruments AG

#include <algorithm>
#include <cstdlib>
#include <ctime>
#include <iostream>
#include <map>
#include <string>

#include "ziAPI.h"
#include "ziUtils.hpp"

void setDemodRate(
    ZIConnection conn,
    const char** deviceAddress,
    uint32_t index,
    ZIDoubleData rate)
{
  char nodePath[1024];
  snprintf(
      nodePath, sizeof(nodePath), "/%s/demods/%d/rate", *deviceAddress, index);
  checkError(ziAPISetValueD(conn, nodePath, rate));
}

ZIDoubleData getDemodRate(
    ZIConnection conn, const char** deviceAddress, uint32_t index)
{
  ZIDoubleData rate;
  char nodePath[1024];
  snprintf(
      nodePath, sizeof(nodePath), "/%s/demods/%d/rate", *deviceAddress, index);
  checkError(ziAPIGetValueD(conn, nodePath, &rate));
  return rate;
}

int main()
{
  // The device address of the device to run the example on.
  const char* deviceAddress = ziUtilsGetEnv("LABONE_DEVICE", "dev2123");
  printf("ENV LABONE_DEVICE=%s\n", deviceAddress);

  // Address of the data server.
  const char* dataServer = ziUtilsGetEnv("LABONE_SERVER", "localhost");

  // Port of the data server.
  const uint16_t port = 8004;

  // Over which interface the connection to the
  // device should be established. Can be either
  // - 1: "1GbE" - Ethernet
  // - 2: "USB" - USB
  // - 3: "PCIe" - PCIe
  const char* deviceInterface = "1GbE";

  ZIConnection conn = nullptr;

  if (isError(ziAPIInit(&conn)))
  {
    return 1;
  }

  ziAPISetDebugLevel(0);
  ziAPIWriteDebugLog(0, "Logging enabled.");

  try
  {
    checkError(
        ziAPIConnectEx(conn, dataServer, port, ZI_API_VERSION_6, nullptr));
    ziApiServerVersionCheck(conn);
    checkError(
        ziAPIConnectDevice(conn, deviceAddress, deviceInterface, nullptr));

    // Set a device configuration.
    uint32_t index = 0;
    ZIDoubleData rate = 10e3;
    setDemodRate(conn, &deviceAddress, index, rate);

    // Read it back.
    rate = getDemodRate(conn, &deviceAddress, index);
    std::cout << "[INFO] "
              << "Device " << deviceAddress << " demod " << index
              << " has rate " << rate << ".\n";

    ziAPIDisconnect(conn);
  }
  catch (std::runtime_error& e)
  {
    char extErrorMessage[1024] = "";
    ziAPIGetLastError(conn, extErrorMessage, 1024);
    fprintf(stderr, "[ERROR] %s\ndetails: `%s`\n.", e.what(), extErrorMessage);
    return 1;
  }
  catch (...)
  {
    // Ensure all exceptions are caught.
    fprintf(stderr, "[ERROR] Unexpected error\n.");
    return 1;
  }

  ziAPIDestroy(conn);
  return 0;
}

See also

ziAPISetValueD, ziAPIGetValueAsPollData

Parameters:

conn – [in] Pointer to ZIConnection with which the value should be retrieved
path – [in] Path to the node holding the value
value – [out] Pointer to a double in which the value should be written

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetComplexData(ZIConnection conn, const char *path, ZIDoubleData *real, ZIDoubleData *imag)

gets the complex double-type value of the specified node

This function retrieves the numerical value of the specified node as an complex double-type value. The value first found is returned if more than one value is available (a wildcard is used in the path).

// Copyright [2018] Zurich Instruments AG

#include <algorithm>
#include <cstdlib>
#include <ctime>
#include <iostream>
#include <map>
#include <string>

#include "ziAPI.h"
#include "ziUtils.hpp"

void setDemodRate(
    ZIConnection conn,
    const char** deviceAddress,
    uint32_t index,
    ZIDoubleData rate)
{
  char nodePath[1024];
  snprintf(
      nodePath, sizeof(nodePath), "/%s/demods/%d/rate", *deviceAddress, index);
  checkError(ziAPISetValueD(conn, nodePath, rate));
}

ZIDoubleData getDemodRate(
    ZIConnection conn, const char** deviceAddress, uint32_t index)
{
  ZIDoubleData rate;
  char nodePath[1024];
  snprintf(
      nodePath, sizeof(nodePath), "/%s/demods/%d/rate", *deviceAddress, index);
  checkError(ziAPIGetValueD(conn, nodePath, &rate));
  return rate;
}

int main()
{
  // The device address of the device to run the example on.
  const char* deviceAddress = ziUtilsGetEnv("LABONE_DEVICE", "dev2123");
  printf("ENV LABONE_DEVICE=%s\n", deviceAddress);

  // Address of the data server.
  const char* dataServer = ziUtilsGetEnv("LABONE_SERVER", "localhost");

  // Port of the data server.
  const uint16_t port = 8004;

  // Over which interface the connection to the
  // device should be established. Can be either
  // - 1: "1GbE" - Ethernet
  // - 2: "USB" - USB
  // - 3: "PCIe" - PCIe
  const char* deviceInterface = "1GbE";

  ZIConnection conn = nullptr;

  if (isError(ziAPIInit(&conn)))
  {
    return 1;
  }

  ziAPISetDebugLevel(0);
  ziAPIWriteDebugLog(0, "Logging enabled.");

  try
  {
    checkError(
        ziAPIConnectEx(conn, dataServer, port, ZI_API_VERSION_6, nullptr));
    ziApiServerVersionCheck(conn);
    checkError(
        ziAPIConnectDevice(conn, deviceAddress, deviceInterface, nullptr));

    // Set a device configuration.
    uint32_t index = 0;
    ZIDoubleData rate = 10e3;
    setDemodRate(conn, &deviceAddress, index, rate);

    // Read it back.
    rate = getDemodRate(conn, &deviceAddress, index);
    std::cout << "[INFO] "
              << "Device " << deviceAddress << " demod " << index
              << " has rate " << rate << ".\n";

    ziAPIDisconnect(conn);
  }
  catch (std::runtime_error& e)
  {
    char extErrorMessage[1024] = "";
    ziAPIGetLastError(conn, extErrorMessage, 1024);
    fprintf(stderr, "[ERROR] %s\ndetails: `%s`\n.", e.what(), extErrorMessage);
    return 1;
  }
  catch (...)
  {
    // Ensure all exceptions are caught.
    fprintf(stderr, "[ERROR] Unexpected error\n.");
    return 1;
  }

  ziAPIDestroy(conn);
  return 0;
}

Parameters:

conn – [in] Pointer to ZIConnection with which the value should be retrieved
path – [in] Path to the node holding the value
real – [out] Pointer to a double in which the real value should be written
imag – [out] Pointer to a double in which the imaginary value should be written

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetValueI(ZIConnection conn, const char *path, ZIIntegerData *value)

gets the integer-type value of the specified node

This function retrieves the numerical value of the specified node as an integer-type value. The value first found is returned if more than one value is available (a wildcard is used in the path).

See also

ziAPISetValueI, ziAPIGetValueAsPollData

Parameters:

conn – [in] Pointer to ZIConnection with which the value should be retrieved
path – [in] Path to the node holding the value
value – [out] Pointer to an 64bit integer in which the value should be written

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetDemodSample(ZIConnection conn, const char *path, ZIDemodSample *value)

Gets the demodulator sample value of the specified node.

This function retrieves the value of the specified node as an DemodSample struct. The value first found is returned if more than one value is available (a wildcard is used in the path). This function is only applicable to paths matching DEMODS/[0-9]+/SAMPLE.

See also

ziAPIGetValueAsPollData

Parameters:

conn – [in] Pointer to ZIConnection with which the value should be retrieved
path – [in] Path to the node holding the value
value – [out] Pointer to a ZIDemodSample struct in which the value should be written

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetDIOSample(ZIConnection conn, const char *path, ZIDIOSample *value)

Gets the Digital I/O sample of the specified node.

This function retrieves the newest available DIO sample from the specified node. The value first found is returned if more than one value is available (a wildcard is used in the path). This function is only applicable to nodes ending in “/DIOS/[0-9]+/INPUT”.

See also

ziAPIGetValueAsPollData

Parameters:

conn – [in] Pointer to the ZIConnection with which the value should be retrieved
path – [in] Path to the node holding the value
value – [out] Pointer to a ZIDIOSample struct in which the value should be written

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by MaxLen is too small for all elements
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetAuxInSample(ZIConnection conn, const char *path, ZIAuxInSample *value)

gets the AuxIn sample of the specified node

This function retrieves the newest available AuxIn sample from the specified node. The value first found is returned if more than one value is available (a wildcard is used in the path). This function is only applicable to nodes ending in “/AUXINS/[0-9]+/SAMPLE”.

See also

ziAPIGetValueAsPollData

Parameters:

conn – [in] Pointer to the ziConnection with which the Value should be retrieved
path – [in] Path to the Node holding the value
value – [out] Pointer to an ZIAuxInSample struct in which the value should be written

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by MaxLen is too small for all elements
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetValueB(ZIConnection conn, const char *path, unsigned char *buffer, unsigned int *length, unsigned int bufferSize)

gets the Bytearray value of the specified node

This function retrieves the newest available DIO sample from the specified node. The value first found is returned if more than one value is available (a wildcard is used in the path).

See also

ziAPISetValueB, ziAPIGetValueAsPollData

Parameters:

conn – [in] Pointer to the ziConnection with which the value should be retrieved
path – [in] Path to the Node holding the value
buffer – [out] Pointer to a buffer to store the retrieved data in
length – [out] Pointer to an unsigned int which after the call, contains the length of the retrieved data. If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.
bufferSize – [in] The length of the passed buffer

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by MaxLen is too small for all elements.
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetValueString(ZIConnection conn, const char *path, char *buffer, unsigned int *length, unsigned int bufferSize)

gets a null-terminated string value of the specified node

This function retrieves the newest string value for the specified node. The value first found is returned if more than one value is available (a wildcard is used in the path).

Parameters:

conn – [in] Pointer to the ziConnection with which the value should be retrieved
path – [in] Path to the Node holding the value
buffer – [out] Pointer to a buffer to store the retrieved null-terminated string
length – [out] Pointer to an unsigned int which after the call, contains the length of the retrieved data (including the null terminator). If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.
bufferSize – [in] The length of the passed buffer

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by MaxLen is too small for all elements.
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

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

gets a null-terminated string value of the specified node

This function retrieves the newest unicode string value for the specified node. The value first found is returned if more than one value is available (a wildcard is used in the path).

Parameters:

conn – [in] Pointer to the ziConnection with which the value should be retrieved
path – [in] Path to the Node holding the value
wbuffer – [out] Pointer to a buffer to store the retrieved null-terminated string
length – [out] Pointer to an unsigned int which after the call, contains the length of the retrieved data (including the null terminator). If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.
bufferSize – [in] The length of the passed buffer

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by MaxLen is too small for all elements.
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the node
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISetValueD(ZIConnection conn, const char *path, ZIDoubleData value)

asynchronously sets a double-type value to one or more nodes specified in the path

This function sets the values of the nodes specified in path to Value. More than one value can be set if a wildcard is used. The function sets the value asynchronously which means that after the function returns you have no security to which value it is finally set nor at what point in time it is set.

See also

ziAPIGetValueD. ziAPISyncSetValueD

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set.
path – [in] Path to the Node(s) for which the value(s) will be set to Value.
value – [in] The double-type value that will be written to the node(s).

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN.
ZI_ERROR_WRITEONLY on attempt to get a wrtie-only node.
ZI_ERROR_COMMAND on an incorrect answer of the server.
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_ERROR_TIMEOUT when communication timed out.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISetComplexData(ZIConnection conn, const char *path, ZIDoubleData real, ZIDoubleData imag)

asynchronously sets a double-type complex value to one or more nodes specified in the path

This function sets the values of the nodes specified in path to the complex value (real, imag). More than one value can be set if a wildcard is used. The function sets the value asynchronously which means that after the function returns you have no security to which value it is finally set nor at what point in time it is set. If the node does not support complex values only the real value will be updated.

See also

ziAPIGetComplexData. ziAPISyncSetComplexData

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set.
path – [in] Path to the Node(s) for which the value(s) will be set to Value.
real – [in] The real value that will be written to the node(s).
imag – [in] The imag value that will be written to the node(s).

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN.
ZI_ERROR_READONLY on attempt to set a read-only node.
ZI_ERROR_COMMAND on an incorrect answer of the server.
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_ERROR_TIMEOUT when communication timed out.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISetValueI(ZIConnection conn, const char *path, ZIIntegerData value)

asynchronously sets an integer-type value to one or more nodes specified in a path

See also

ziAPIGetValueI. ziAPISyncSetValueI

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
value – [in] The int-type value that will be written to the node(s)

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN.
ZI_ERROR_READONLY on attempt to set a read-only node.
ZI_ERROR_COMMAND on an incorrect answer of the server.
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_ERROR_TIMEOUT when communication timed out.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISetValueB(ZIConnection conn, const char *path, unsigned char *buffer, unsigned int length)

asynchronously sets the binary-type value of one or more nodes specified in the path

This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. The function sets the value asynchronously which means that after the function returns you have no security to which value it is finally set nor at what point in time it is set.

See also

ziAPIGetValueB. ziAPISyncSetValueB

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
buffer – [in] Pointer to the byte array with the data
length – [in] Length of the data in the buffer

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN.
ZI_ERROR_READONLY on attempt to set a read-only node.
ZI_ERROR_COMMAND on an incorrect answer of the server.
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values.
ZI_ERROR_TIMEOUT when communication timed out.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISetValueString(ZIConnection conn, const char *path, const char *str)

asynchronously sets a string value of one or more nodes specified in the path

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
str – [in] Pointer to a null terminated string (max 64k characters)

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN.
ZI_ERROR_READONLY on attempt to set a read-only node.
ZI_ERROR_COMMAND on an incorrect answer of the server.
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values.
ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
ZI_ERROR_TIMEOUT when communication timed out.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISetValueStringUnicode(ZIConnection conn, const char *path, const wchar_t *wstr)

asynchronously sets a unicode encoded string value of one or more nodes specified in the path

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
wstr – [in] Pointer to a null terminated unicode string (max 64k characters)

Returns:

ZI_INFO_SUCCESS on success.
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN.
ZI_ERROR_READONLY on attempt to set a read-only node.
ZI_ERROR_COMMAND on an incorrect answer of the server.
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server.
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values.
ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
ZI_ERROR_TIMEOUT when communication timed out.
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISyncSetValueD(ZIConnection conn, const char *path, ZIDoubleData *value)

synchronously sets a double-type value to one or more nodes specified in the path

This function sets the values of the nodes specified in path to Value. More than one value can be set if a wildcard is used. The function sets the value synchronously. After returning you know that it is set and to which value it is set.

See also

ziAPIGetValueD, ziAPISetValueD

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set to value
value – [in] Pointer to a double-type containing the value to be written. When the function returns value holds the effectively written value.

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN
ZI_ERROR_READONLY on attempt to set a read-only node
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISyncSetValueI(ZIConnection conn, const char *path, ZIIntegerData *value)

synchronously sets an integer-type value to one or more nodes specified in a path

This function sets the values of the nodes specified in path to value. More than one value can be set if a wildcard is used. The function sets the value synchronously. After returning you know that it is set and to which value it is set.

See also

ziAPIGetValueI, ziAPISetValueI

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the node(s) for which the value(s) will be set
value – [in] Pointer to a int-type containing then value to be written. when the function returns value holds the effectively written value.

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN
ZI_ERROR_READONLY on attempt to set a read-only node
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISyncSetValueB(ZIConnection conn, const char *path, uint8_t *buffer, uint32_t *length, uint32_t bufferSize)

Synchronously sets the binary-type value of one ore more nodes specified in the path.

This function sets the values at the nodes specified in a path. More than one value can be set if a wildcard is used. This function sets the value synchronously. After returning you know that it is set and to which value it is set.

See also

ziAPIGetValueB, ziAPISetValueB

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
buffer – [in] Pointer to the byte array with the data
length – [in] Length of the data in the buffer
bufferSize – [in] Length of the data in the buffer

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN
ZI_ERROR_READONLY on attempt to set a read-only node
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISyncSetValueString(ZIConnection conn, const char *path, const char *str)

Synchronously sets a string value of one or more nodes specified in the path.

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
str – [inout] Pointer to a null terminated string (max 64k characters)

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN
ZI_ERROR_READONLY on attempt to set a read-only node
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISyncSetValueStringUnicode(ZIConnection conn, const char *path, const wchar_t *wstr)

Synchronously sets a unicode string value of one or more nodes specified in the path.

Parameters:

conn – [in] Pointer to the ziConnection for which the value(s) will be set
path – [in] Path to the Node(s) for which the value(s) will be set
wstr – [inout] Pointer to a null terminated unicode string (max 64k characters)

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred
ZI_ERROR_LENGTH if the Path’s Length exceeds MAX_PATH_LEN
ZI_ERROR_READONLY on attempt to set a read-only node
ZI_ERROR_COMMAND on an incorrect answer of the server
ZI_ERROR_SERVER_INTERNAL if an internal error occurred in the Data Server
ZI_WARNING_NOTFOUND if the given path could not be resolved or no node given by path is able to hold values
ZI_WARNING_INVALID_KEYWORD if the given keyword could not be resolved
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPISync(ZIConnection conn)

Synchronizes the session by dropping all pending data.

This function drops any data that is pending for transfer. Any data (including poll data) retrieved afterwards is guaranteed to be produced not earlier than the call to ziAPISync. This ensures in particular that any settings made prior to the call to ziAPISync have been propagated to the device, and the data retrieved afterwards is produced with the new settings already set to the hardware. Note, however, that this does not include any required settling time.

Parameters:

conn – [in] Pointer to the ZIConnection that is to be synchronized

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIEchoDevice(ZIConnection conn, const char *deviceSerial)

Sends an echo command to a device and blocks until answer is received.

This is useful to flush all buffers between API and device to enforce that further code is only executed after the device executed a previous command. Per device echo is only implemented for HF2. For other device types it is a synonym to ziAPISync, and deviceSerial parameter is ignored.

Parameters:

conn – [in] Pointer to the ZIConnection that is to be synchronized
deviceSerial – [in] The serial of the device to get the echo from, e.g., dev2100

Returns:

ZI_INFO_SUCCESS on success
ZI_ERROR_TIMEOUT when communication timed out
Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.