H5D_GATHER retrieves data from a selection within the supplied buffer
src_buf and passes it to the supplied callback function
op in a contiguous form.
src_space_id is a dataspace which defines the extent of
src_buf and the selection within it to gather the data from.
type_id is the datatype of the data to be gathered in both the source and destination buffers.
src_buf must be at least as large as the number of elements in the extent of
src_space_id times the size in bytes of
The data is gathered into
dst_buf, which needs to be large enough to hold all the data if the callback function
op is not provided.
If no callback function is provided, H5D_GATHER simply gathers the data into
dst_buf and returns. If a callback function is provided, H5D_GATHER repeatedly gathers up to
op to process the serialized data. The prototype of the callback function
op is as follows (as defined in the source code file
(*H5D_gather_func_t)( const void *
dst_buf_bytes_used, void *
The parameters of this callback function have the following values or meanings:
|Pointer to the destination buffer which has been filled with the next set of elements gathered. This will always be identical to the |
dst_buf passed to H5D_GATHER.
|Pointer to the number of valid bytes in |
dst_buf. This number must be a multiple of the datatype size.
|User-defined pointer to data required by the callback function; a pass-through of the |
op_data pointer provided with the H5D_GATHER function call.
The callback function should process, store, or otherwise make use of the data returned in
dst_buf before it returns, because the buffer will be overwritten unless it is the last call to the callback. This function will be repeatedly called until all gathered elements have been passed to the callback in
dst_buf. The callback function should return zero (
0) to indicate success, and a negative value to indicate failure.