pips_topic_create_publication()

Create a publication for the current topic

Synopsis:

#include <pips/publication.h>
pips_publication_t* pips_topic_create_publication(pips_topic_t *const topic,
                                 const unsigned flags,
                                 void *const opt_usr_data,
                                 pips_publication_new_data_handler_t *const opt_new_data_cb)

Arguments:

topic
A pointer to the topic that will be the object of the publication
flags
The direction flags, which indicate whether the publication can read updates to the topic and/or write updates to it (for details, see below)
opt_usr_data
An optional pointer to user data to attach to the publication instance. This data can be retrieved with the pips_publication_get_data() function.
opt_new_data_cb
An optional pointer to a callback function that will be invoked by the framework whenever it receives a new data sample event. This function will be called after any event handlers registered with the provider are called. Any user data is passed as the first argument to the callback function.

Library:

pips-client

Description:

This function creates a new publication for the current topic. The publish/subscribe provider that will create the publication is the same one that's managing the topic.

Through the direction flags, the publication can be configured so that clients can subscribe to updates to the topic and/or publish updates to other subscribers.

  • PIPS_SUBSCRIBE: The publication will receive samples (updates) from publishers of the associated topic. This flag is required for enabling clients to read data from the publication.
  • PIPS_PUBLISH: The publication will send samples to other subscribers of the topic. This flag is required for enabling clients to write data to the publication.
  • PIPS_EXCL: The publication will be exclusive for the topic. This means that data written for the topic will be received by a subscriber only if it shares a key with the publisher. Conversely, subscribers of the topic will receive a sample only if they share a key with the publisher.
  • PIPS_OWNER: The publication will receive samples that are not targetted to any particular subscriber. This flag can be used with PIPS_EXCL to create a peer that receives untargetted samples and samples targetted to its GUID, but not samples targetted to other subscribers.

Returns:

On success, a pointer to a new publication for the given topic. The caller owns the publication instance and is responsible for asking the PiPS framework to finalize the data and for deleting the publication. On error, NULL (errno is set by the provider implementation).