pips_namespace_create_publication()

Create a publication for all topics in a namespace

Synopsis:

#include <pips/publication.h>
pips_publication_t* pips_namespace_create_publication(pips_namespace_t *const nmspace,
                            const int max_depth,
                            void *const opt_usr_data,
                            pips_publication_new_data_handler_t *const opt_new_data_handler)

Arguments:

nmspace
The namespace containing the topics to be added to the group for the new publication
max_depth
The maximum depth to recurse to when collecting topics in the current namespace. A negative value means unlimited depth.
opt_usr_data
A pointer to optional user data to attach to the publication instance. This data can be retrieved later using pips_publication_get_data().
opt_new_data_handler
An optional pointer to a callback function that will be invoked by the framework whenever a new data sample event is received for the publication. This function will be called after any event handlers registered globally with the provider are called.

Library:

pips-client

Description:

This function collects all topics that are children of the current namespace into a new group, then creates a publication for this group. The topics in the namespace will be added in a depth-first order up to the given maximum depth.

The publication will be configured with the PIPS_SUBSCRIBE flag set to receive samples (updates) from publishers of the grouped topics. Other publication modes are not supported with groups (e.g., PIPS_PUBLISH, PIPS_EXCL).

Postrequisites

The caller is responsible for retrieving the group topic by calling pips_publication_get_topic() before deleting the publication, so they can also delete the group itself by calling pips_delete_topic(); otherwise, memory will be leaked.

Returns:

On success, a pointer to a new publication for the new group whose members are the topics contained in the current namespace. The publication instance becomes owned by the caller, who is responsible for requesting the PiPS middleware to finalize the data and for deleting the publication. On error, NULL (errno is set by the provider implementation).

Errors:

  • ENODEV: The namespace is invalid.