Function dds_take 

pub unsafe extern "C" fn dds_take(
    reader_or_condition: dds_entity_t,
    buf: *mut *mut c_void,
    si: *mut dds_sample_info_t,
    bufsz: usize,
    maxs: u32,
) -> dds_return_t

@brief Take data from the data reader, read or query condition @ingroup reading @component read_data

Reads and removes samples from the reader history cache. It starts with an arbitrary (matching) instance, reading (matching) samples from the oldest to the most recent, then continues with another arbitrarily selected (matching) instance, etc. This continues until it has traversed the entire history cache or has gathered maxs samples.

The @ref dds_read operation can be used to read samples without removing them from the history cache but marking them as “read”; the @ref dds_peek operation can be used to read samples from the cache without changing any internal state.

For the plain dds_take operation, all instances and samples match. This is different for the more selective variants, where the documentation refers to this function and only gives detailed information where it differs.

The buf parameter is used as follows:

• If buf[0] on entry is a null pointer:

  • on return buf[0] .. buf[k-1] will point to middleware-owned memory (a.k.a. loans); and
  • buf[k] will be a null pointer if 0 <= k < bufsz; and
  • 0 <= k <= maxs is the number of samples read (a.k.a. the return value).

• If buf[0] on entry is an outstanding sample loan (i.e., resulting from a previous call to, e.g., read), then:

  • all of buf[0] .. buf[k-1] must be pointers to outstanding loans; and
  • k = bufsz or buf[k] is a null pointer; where
  • 1 <= k < bufsz; and
  • all these outstanding loans are returned as-if through @ref dds_return_loan; and
  • the result will be as if buf[0] had been a null pointer on entry.

• If buf[0] on entry is any other address, then:

  • all of buf[0] .. buf[bufsz-1] must point to memory suitable for storing samples; and
  • the C binding requires that this memory must be initialized such that all embedded strings, externals, optionals and sequences are initialized (null pointers are ok, sequences may also be all-0)

The loans returned by dds_take operation are potentially shared copies of the data and the contents may not be modified. If a private copy is required, pass in non-null pointers to memory as in the third case above.

The si array is filled with sample information on all returned samples. If the valid_data flag is set in the sample info for a particular sample, all fields of that sample are valid. Otherwise, only the key value is valid. For the C binding, all other fields will be set to 0.

@param[in] reader_or_condition Reader, readcondition or querycondition entity. @param[in,out] buf An array of bufsz pointers to samples (see above). @param[out] si Pointer to an array of @ref dds_sample_info_t returned for each data value. @param[in] bufsz The size of buffer provided. @param[in] maxs Maximum number of samples to read.

@returns A dds_return_t with the number of samples read or an error code.

@retval >=0 Number of samples read. @retval DDS_RETCODE_ERROR An internal error has occurred. @retval DDS_RETCODE_BAD_PARAMETER One of the given arguments is not valid. @retval DDS_RETCODE_ILLEGAL_OPERATION The operation is invoked on an inappropriate object. @retval DDS_RETCODE_ALREADY_DELETED The entity has already been deleted.