Function ziAPIModGetChunk#

ZIResult_enum ziAPIModGetChunk(ZIConnection conn, ZIModuleHandle handle, uint64_t chunkIndex, ZIModuleEventPtr *ev)#

Get the specified data chunk from the current node.

Data is read out node-by-node and then chunk-by-chunk. This function can be used to obtain specific data chunks from the current node that data is being read from. More precisely, it ppreallocates space for an event structure big enough to hold the node’s data at the specified chunk index, updates ZIModuleEventPtr to point to this space and then copies the chunk data to this space.

Note, before the very first call to ziAPIModGetChunk, the ZIModuleEventPtr should be initialized to NULL and then left untouched for all subsequent calls (even after calling ziAPIModNextNode to get data from the next node). This is because ziAPIModGetChunk internally manages the required space allocation for the event and then in subsequent calls only reallocates space when it is required. It is optimized to reduce the number of required space reallocations for the event.

The ZIModuleEventPtr should be deallocated using ziAPIModEventDeallocate, otherwise the lifetime of the ZIModuleEventPtr is the same as the lifetime of the module. Indeed, the same ZIModuleEventPtr can be used, even for subsequent reads. It is also possible to work with multiple ZIModuleEventPtr so that some pointers can be kept for later processing.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • chunkIndex[out] The index of the data chunk to update the pointer to.

  • ev[out] The module’s ZIModuleEventPtr that points to the currently available data chunk.

Returns:

  • ZI_INFO_SUCCESS On success.

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

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

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