Create a publication for a named topic within a provider
Synopsis:
#include <pips/publication.h>
pips_publication_t* pips_provider_create_publication(pips_provider_t *const provider,
const char *const topic_name,
const char *const type,
const unsigned flags,
void *const opt_usr_data,
pips_publication_new_data_handler_t *const opt_new_data_cb)
Arguments:
- provider
- A handle to the provider in which the topic is defined (or will be created). If this argument is NULL, the default provider will be used.
- topic_name
- The name of the topic that will be the object of the publication. The topic will be created if it doesn't exist in the specified provider.
- type
- The type of data expressed by the topic. If the topic exists, this argument's value must match the topic's associated type. If the topic gets created, this value is used to set its type.
- flags
- The direction flags, which indicate whether the publication can receive updates to the topic and/or publish 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 later using pips_publication_get_data().
- 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 queries the specified provider to retrieve the named topic and creates a publication for it. The topic will be created if it doesn't already exist in the provider's root namespace. This function is a shortcut that performs actions similar to the following, in one operation:
pips_topic_t* topic;
pips_provider_t* provider = pips_get_provider( NULL );
pips_namespace_t* root = pips_provider_root( provider );
if ( !(topic = pips_namespace_find_topic( root, "topic-name" )) ) {
topic = pips_namespace_create_topic( root, "topic-name", "Number" );
}
pips_topic_create_publication( topic, PIPS_SUBSCRIBE, usr_data, new_data_cb );
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 named 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).
Errors:
- EEXIST: The named topic already exists with a different type.
- EINVAL: The topic name or its type is invalid.
- ENODEV: The provider's state is invalid (e.g., it hasn't been initialized).
- ENOENT: The given type wasn't registered with the current provider.
- ENOSYS: The provider doesn't support topic creation.