Data Streaming#

group DataHandling

This section describes how to perform data streaming. It allows for recording at high data rates without sample loss.

Typedefs

typedef struct ZIEvent ZIEvent#

Functions

ZIEvent *ziAPIAllocateEventEx(void)

Allocates ZIEvent structure and returns the pointer to it. Attention!!! It is the client code responsibility to deallocate the structure by calling ziAPIDeallocateEventEx!

This function allocates a ZIEvent structure and returns the pointer to it. Free the memory using ziAPIDeallocateEventEx.

void ziAPIDeallocateEventEx(ZIEvent *ev)

Deallocates ZIEvent structure created with ziAPIAllocateEventEx().

This function is the compliment to ziAPIAllocateEventEx()

Parameters:

ev[in] Pointer to ZIEvent structure to be deallocated..

ZIResult_enum ziAPISubscribe(ZIConnection conn, const char *path)

subscribes the nodes given by path for ziAPIPollDataEx

This function subscribes to nodes so that whenever the value of the node changes the new value can be polled using ziAPIPollDataEx. By using wildcards or by using a path that is not a leaf node but contains sub nodes, more than one leaf can be subscribed to with one function call.

See Data Handling for an example

Parameters:
  • conn[in] Pointer to the ziConnection for which to subscribe for

  • path[in] Path to the nodes to subscribe

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 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 ziAPIUnSubscribe(ZIConnection conn, const char *path)

unsubscribes to the nodes given by path

This function is the complement to ziAPISubscribe. By using wildcards or by using a path that is not a leaf node but contains sub nodes, more than one node can be unsubscribed with one function call.

See Data Handling for an example

Parameters:
  • conn[in] Pointer to the ziConnection for which to unsubscribe for

  • path[in] Path to the Nodes to unsubscribe

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 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 ziAPIPollDataEx(ZIConnection conn, ZIEvent *ev, uint32_t timeOutMilliseconds)

checks if an event is available to read

This function returns immediately if an event is pending. Otherwise it waits for an event for up to timeOutMilliseconds. All value changes that occur in nodes that have been subscribed to or in children of nodes that have been subscribed to are sent from the Data Server to the ziAPI session. For a description of how the data are available in the struct, refer to the documentation of struct ziEvent. When no event was available within timeOutMilliseconds, the ziEvent::Type field will be ZI_DATA_NONE and the ziEvent::Count field will be zero. Otherwise these fields hold the values corresponding to the event that occurred.

See Data Handling for an example

Parameters:
  • conn[in] Pointer to the ZIConnection for which events should be received

  • ev[out] Pointer to a ZIEvent struct in which the received event will be written

  • timeOutMilliseconds[in] Time to wait for an event in milliseconds. If -1 it will wait forever, if 0 the function returns immediately.

Returns:

  • ZI_INFO_SUCCESS on success

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIGetValueAsPollData(ZIConnection conn, const char *path)

triggers a value request, which will be given back on the poll event queue

Use this function to receive the value of one or more nodes as one or more events using ziAPIPollDataEx, even when the node is not subscribed or no value change has occurred.

See Data Handling for an example

Parameters:
  • conn[in] Pointer to the ZIConnection with which the value should be retrieved

  • path[in] Path to the Node holding the value. Note: Wildcards and paths referring to streamimg nodes are not permitted.

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.

struct ZIEvent
#include <ziAPI.h>

This struct holds event data forwarded by the Data Server.

ZIEvent is used to give out events like value changes or errors to the user. Event handling functionality is provided by ziAPISubscribe and ziAPIUnSubscribe as well as ziAPIPollDataEx.

Public Members

uint32_t valueType#

Specifies the type of the data held by the ZIEvent, see ZIValueType_enum.

uint32_t count#

Number of values available in this event.

uint8_t path[256]#

The path to the node from which the event originates.

void *untyped#

For convenience. The void field doesn’t have a corresponding data type.

ZIDoubleData *doubleData#

when valueType == ZI_VALUE_TYPE_DOUBLE_DATA

ZIDoubleDataTS *doubleDataTS#

when valueType == ZI_VALUE_TYPE_DOUBLE_DATA_TS

ZIIntegerData *integerData#

when valueType == ZI_VALUE_TYPE_INTEGER_DATA

ZIIntegerDataTS *integerDataTS#

when valueType == ZI_VALUE_TYPE_INTEGER_DATA_TS

ZIComplexData *complexData#

when valueType == ZI_VALUE_TYPE_COMPLEX_DATA

ZIByteArray *byteArray#

when valueType == ZI_VALUE_TYPE_BYTE_ARRAY

ZIByteArrayTS *byteArrayTS#

when valueType == ZI_VALUE_TYPE_BYTE_ARRAY_TS

ZICntSample *cntSample#

when valueType == ZI_VALUE_TYPE_CNT_SAMPLE

ZITrigSample *trigSample#

when valueType == ZI_VALUE_TYPE_TRIG_SAMPLE

ZITreeChangeData *treeChangeData#

when valueType == ZI_VALUE_TYPE_TREE_CHANGE_DATA

TreeChange *treeChangeDataOld#

when valueType == ZI_VALUE_TYPE_TREE_CHANGE_DATA_OLD

ZIDemodSample *demodSample#

when valueType == ZI_VALUE_TYPE_DEMOD_SAMPLE

ZIAuxInSample *auxInSample#

when valueType == ZI_VALUE_TYPE_AUXIN_SAMPLE

ZIDIOSample *dioSample#

when valueType == ZI_VALUE_TYPE_DIO_SAMPLE

ZIScopeWave *scopeWave#

when valueType == ZI_VALUE_TYPE_SCOPE_WAVE

ZIScopeWaveEx *scopeWaveEx#

when valueType == ZI_VALUE_TYPE_SCOPE_WAVE_EX

ScopeWave *scopeWaveOld#

when valueType == ZI_VALUE_TYPE_SCOPE_WAVE_OLD

ZIPWAWave *pwaWave#

when valueType == ZI_VALUE_TYPE_PWA_WAVE

ZISweeperWave *sweeperWave#

when valueType == ZI_VALUE_TYPE_SWEEPER_WAVE

ZISpectrumWave *spectrumWave#

when valueType == ZI_VALUE_TYPE_SPECTRUM_WAVE

ZIAdvisorWave *advisorWave#

when valueType == ZI_VALUE_TYPE_ADVISOR_WAVE

ZIAsyncReply *asyncReply#

when valueType == ZI_VALUE_TYPE_ASYNC_REPLY

ZIVectorData *vectorData#

when valueType == ZI_VALUE_TYPE_VECTOR_DATA

ZIImpedanceSample *impedanceSample#

when valueType == ZI_VALUE_TYPE_IMPEDANCE_SAMPLE

uint64_t alignment#

ensure union size is 8 bytes

union ZIEvent::[anonymous] value#

Convenience pointer to allow for access to the first entry in Data using the correct type according to ZIEvent.valueType field.

uint8_t data[0x400000]#

The raw value data.