pips_publication

Read a data sample from a publication's topic

Synopsis:

#include <pips/publication.h>

int pips_publication_read(pips_publication_t *const publication,
                          const int wait_ms,
                          const pips_encoding_e encoding,
                          pips_data_t *buffer,
                          size_t buffer_size,
                          pips_guid_t *opt_writer_guid)

Arguments:

publication: A pointer to the publication whose topic data is to be read
wait_ms: The number of milliseconds to wait for a sample (update). For positive values, the function waits up to the given number of milliseconds for a sample to arrive. For negative values, the function waits indefinitely. For a zero value, the read is non-blocking.
encoding: The desired encoding of the topic's data, as a pips_encoding_e constant.
buffer: A pointer to a buffer where the encoded data will be written. This buffer must be large enough to store the sample's data. If this argument is NULL, the function allocates a contiguous buffer of the correct size. The caller becomes the owner of the buffer, and is responsible for freeing it.
buffer_size: The size, in bytes, of the memory area referenced by the buffer argument. The buffer_size argument is ignored if buffer is NULL.
opt_writer_guid: An optional pointer to a buffer where the GUID of the data's publisher is stored

Library:

pips-client

Description:

This function reads the latest data sample for the topic associated with the given publication, optionally blocking until the first sample arrives. Then, it writes the data into the specified buffer using the requested encoding.

Prerequisites

When reading the built-in types of Number, Boolean, and MultiMap, the caller must allocate a storage buffer before invoking the read operation. The buffer must be of a fixed size (e.g., sizeof(double)).

For other data types, if no buffer is provided, the framework allocates one and returns it to the caller. When reading MultiMap data, attributes are added to the provided structure.

Postrequisites

The data returned from the read operation must be cleaned up to avoid leaking memory.

Returns:

>=0: The number of bytes of topic data successfully read

-1: An error occured (errno is set)

Errors:

The following errors can be reported by this function:

EINVAL: The buffer argument wasn't provided.
ENODEV: The publication doesn't have a valid provider associated with it.
ENOSR: The publication is invalid.
ENOSYS: The provider doesn't implement the read function.

pips_publication_read()