Data Structures
struct	ds5_dataprovider_t
	Interface that must be implemented in order to receive subscirption request and subscription discard events for DataSource subjects from connected DataSource peers. the implementation sends data to connected peers in response to subscription requests. More...

Macros
#define	F_DELETEOBJECT 0x0004
	Instruction to delete this object. More...

#define	F_IGNOREREQTIMEOUT 0x0008
	Allow nodata to be propagated. More...

#define	F_NOTFOUND 0x0001
	The object is not found. More...

#define	F_READDENY 0x0002
	You do not have permission to read this object. More...

#define	F_UNAVAILABLE 0x0005
	The object is unavailable at this time. More...

#define	F_WRITEDENY 0x0003
	You do not have permission to write to this object. More...

Typedefs
typedef struct _ds5_publisher_s	ds5_publisher_t
	Represents a data publisher that publishers to remote DataSource peers on behalf of a ds5_dataprovider_t. More...

Functions
ds5_publisher_t *	ds5_create_active_publisher (ds5_namespace_t nspace, ds5_dataprovider_t provider, void *context)
	Creates a data publisher that for a given subject sends multiple subscription requests and a single subscription discard to a ds5_dataprovider_t. More...

ds5_publisher_t *	ds5_create_broadcast_publisher (ds5_namespace_t *nspace)
	Creates a data publisher that allows a DataSource application to broadcast updates to remote DataSource peers regardless of whether they have requested (subscribed to) the subject. More...

ds5_publisher_t *	ds5_create_compatibility_publisher (ds5_namespace_t nspace, ds5_dataprovider_t provider, void *context)
	Creates a data publisher that, for a given subject sends multiple subscription requests and multiple subscription discards to a ds5_dataprovider_t. More...

void	ds5_publish_response (ds5_publisher_t publisher, ds_data_t dsdata)
	Publish an initial response (for example, an image of the subject's data) following a request for a subscription request from a peer. More...

void	ds5_publish_response_no_free (ds5_publisher_t publisher, ds_data_t dsdata)
	Publish an initial response (for example, an image of the subject's data) following a request for a subscription request from a peer. The response will not be freed. More...

void	ds5_publish_status (ds5_publisher_t publisher, const char subject, int status, const char *message)
	Publishes a subscription status event for a subject. More...

void	ds5_publish_subject_error (ds5_publisher_t publisher, const char subject, int flags)
	Publishes a subscription error event for a subject. More...

void	ds5_publish_subject_map (ds5_publisher_t publisher, const char subject, const char *mapped_to, int flags)
	Publishes a subscription map event for a subject. More...

void	ds5_publish_to_peer (ds5_publisher_t publisher, int peernum, ds_data_t dsdata)
	Publish an update for a subject to the specified peer. More...

void	ds5_publish_to_peer_no_free (ds5_publisher_t publisher, int peernum, ds_data_t dsdata)
	Publish an update for a subject to the specified peer. The update will not be freed. More...

void	ds5_publish_to_subscribed_peers (ds5_publisher_t publisher, ds_data_t dsdata)
	Publish an update for a subject to all peers that have subscribed. More...

void	ds5_publish_to_subscribed_peers_no_free (ds5_publisher_t publisher, ds_data_t dsdata)
	Publish an update for a subject to all peers that have subscribed. The update will not be freed. More...

Detailed Description

DataSource applications can publish data to remote DataSource peers by using a ds5_publisher_t interface. This interface keeps track of which peers are subscribed of subjects and notifies the user implemented ds5_dataprovider_t interface when the subscription state of a subject changes.

DataSource for C SDK supplies the following ds5_publisher_t implementations:

Compatibility publisher. This publisher type is created using ds5_create_compatibility_publisher() and passes all requests and discards from remote DataSource peers to the ds5_dataprovider_t. The ds5_dataprovider_t implementation is responsible for keeping track of the number of requests received; it must only stop supplying data for a subject when there are no peers subscribing to it.
Active publisher. This publisher type is created using ds5_create_active_publisher() and passes all requests but only the final discard from remote DataSource peers to the ds5_dataprovider_t. The ds5_dataprovider_t implementation need not keep track of the number of requests received; it should stop supplying data for a subject when the ds5_dataprovider_t::receive_discard() callback is received.
Broadcast publisher. This publisher type is created using ds5_create_broadcast_publisher(). For a broadcast publisher there is no associated ds5_dataprovider_t - the user application can supply data at any time. The use of a broadcast publisher is not recommended due to the detrimental effects that braodcast data has on reliable and predictable failover and data recovery between DataSource components.

Example: Sample code demonstrating a ds5_dataprovider_t implementation supplying updates for a single subject.

static ds5_publisher_t    *pub;
static char               *tev_subject;
static ds_timed_event_t   *tev;
static int send_update(int id, int val, void *data)
{
    ds_data_t   *dsdata = ds_init_data(tev_subject, DS_RECORD_TYPE, F_CREATEOBJECT|F_CREATEPARENT);
    ds_add_record_int(dsdata, "Value", rand());
    ds5_publish_to_subscribed_peers(pub, dsdata);
    return 1; /* Keep the timed event going */
}
static void receive_request(void *context, int peer, const char *subject)
{
    /* In this example we will only service a single subject */
    if ( tev == NULL ) {
        ds_data_t   *dsdata = ds_init_data(subject, DS_RECORD_TYPE, F_CREATEOBJECT|F_CREATEPARENT);
        ds_add_record_str(dsdata, "Value", rand());
        ds5_publish_response(pub, dsdata);
        /* Add a timer to periodically (every 5 seconds) send values */
        tev = ds_add_timed_event(0, 5.0, send_update, 0, NULL);
        tev_subject = strdup(subject);
    } else {
        /* We're already delivering updates for a subject, so send an error for this new request */
        ds5_publish_subject_error(pub, subject, F_NOTFOUND);
    }
}
static void receive_discard(void *context, int peer, const char *subject)
{
    /* Process a discard, in this example we only supply a single subject, so check and cancel the timed event if it matches */
    if ( tev_subject && strcmp(tev_subject, subject) == 0 ) {
        free(tev_subject);
        ds_del_timed_event(tev);
        tev = NULL;
        tev_subject = NULL;
    }
}
int main(int argc, char *argv)
{
    static ds5_dataprovider_t *my_dataprovider;
    ds5_namespace_t           *my_nspace;
    ds5_config_init("demo1.conf", argc, argv);
    ds5_init(argc,argv);
    /* Register a data provider for a namespace */
    my_dataprovider.receive_request = receive_request;
    my_dataprovider.receive_discard = receive_discard;
    my_nspace = ds5_create_prefix_namespace("/MYDATA");
    pub = ds5_create_mrsd_publisher(my_nspace, &my_dataprovider, NULL);
    ds_loop();
    return 0;
}

Macro Definition Documentation

#define F_DELETEOBJECT 0x0004

Instruction to delete this object.

This define is used as the flags argument to ds5_publish_subject_error().

#define F_IGNOREREQTIMEOUT 0x0008

Allow nodata to be propagated.

This define is used as the flags argument to ds5_publish_subject_error().

#define F_NOTFOUND 0x0001

The object is not found.

This define is used as the flags argument to ds5_publish_subject_error().

#define F_READDENY 0x0002

You do not have permission to read this object.

This define is used as the flags argument to ds5_publish_subject_error().

#define F_UNAVAILABLE 0x0005

The object is unavailable at this time.

This define is used as the flags argument to ds5_publish_subject_error().

#define F_WRITEDENY 0x0003

You do not have permission to write to this object.

This define is used as the flags argument to ds5_publish_subject_error().

Typedef Documentation

typedef struct _ds5_publisher_s ds5_publisher_t

Represents a data publisher that publishers to remote DataSource peers on behalf of a ds5_dataprovider_t.

Note: It is not intended that DataSource applications provide their own implementation of ds5_publisher_t and as such the interface definition is not public.

Function Documentation

ds5_publisher_t* ds5_create_active_publisher	(	ds5_namespace_t *	nspace,
		ds5_dataprovider_t *	provider,
		void *	context
	)

Creates a data publisher that for a given subject sends multiple subscription requests and a single subscription discard to a ds5_dataprovider_t.

Parameters

nspace	- The namespace that defines the subjects this Publisher handles.
provider	- The data provider that receives subscription requests and discards. You must implement this data provider.
context	- A context that is passed to the callback functions of the provider (ds5_dataprovider_t). The structure and content of this context is application specific.

Return values

NULL	- One or more of the callback functions for the supplied ds5_dataprovider_t have not been implemented.

Returns: A publisher that can be used to publish data.

This type of ds5_publisher_t only publishes updates to DataSource peers that have requested the subject of the update.

In contrast to the publisher returned by ds5_create_compatibility_publisher(), this publisher only calls the ds5_dataprovider_t::receive_discard() function once for a particular subject when the last peer has discarded that subject. The ds5_dataprovider_t therefore does not have to keep track of the numbers of subscription requests and discards relating to each subject; this is done by the instance of ds5_publisher_t itself.

Note: You are recommended to use data publishers returned by this function in preference to those returned by ds5_create_compatibility_publisher().

ds5_publisher_t* ds5_create_broadcast_publisher ( ds5_namespace_t * nspace )

Creates a data publisher that allows a DataSource application to broadcast updates to remote DataSource peers regardless of whether they have requested (subscribed to) the subject.

Parameters

nspace - The namespace that defines the subjects this Publisher handles.

Returns: A publisher that can be used to publish data.

This type of ds5_publisher_t will publish updates to all connected DataSource peers.

In general, the use of broadcast publishing is not recommended, because it presents difficulties when handling failover of the DataSource application instance to another instance; the new DataSource instance may not know what data needs to be updated on the DataSource peers. However, broadcast messaging can be useful in situations where messages are transient and the data in them does not need to be always available to peers.

ds5_publisher_t* ds5_create_compatibility_publisher	(	ds5_namespace_t *	nspace,
		ds5_dataprovider_t *	provider,
		void *	context
	)

Creates a data publisher that, for a given subject sends multiple subscription requests and multiple subscription discards to a ds5_dataprovider_t.

Parameters

nspace	- The namespace that defines the subjecs this Publisher handles.
provider	- The data provider that receives subscription requests and discards. You must implement this data provider.
context	- A context that is passed to the callback functions of the provider (ds5_dataprovider_t). The structure and content of this context is application specific.

Return values

NULL	- One or more of the callback functions for the supplied ds5_dataprovider_t have not been implemented.

Returns: A publisher that can be used to publish data.

This type of ds5_publisher_t will only publish updates to DataSource peers that have requested the subject of the update. It calls the ds5_dataprovider_t::receive_request() function once for each peer that subscribes to the subject and the the ds5_dataprovider_t::receive_discard() functiion once for each peer that discards the subject.

The ds5_dataprovider_t must keep track of the numbers of subscription requests and discards relating to each subject, so that it can stop sending updates for a particular subject when there are no more peers subscribed to that subject.

Note: This publisher type is provided for backwards compatibility with earlier (4.x) versions of DataSource for C where this subscription semantic was used. New DataSource applications should create instances of ds5_publisher_t by calling ds5_create_active_publisher() instead which reduces the contract obligations of your ds5_dataprovider_t.

void ds5_publish_response	(	ds5_publisher_t *	publisher,
		ds_data_t *	dsdata
	)

Publish an initial response (for example, an image of the subject's data) following a request for a subscription request from a peer.

Parameters

publisher	- The data publisher to use to publish this response.
dsdata	- The data to be sent.

void ds5_publish_response_no_free	(	ds5_publisher_t *	publisher,
		ds_data_t *	dsdata
	)

Publish an initial response (for example, an image of the subject's data) following a request for a subscription request from a peer. The response will not be freed.

Parameters

publisher	- The data publisher to use to publish this response.
dsdata	- The data to be sent.

void ds5_publish_status	(	ds5_publisher_t *	publisher,
		const char *	subject,
		int	status,
		const char *	message
	)

Publishes a subscription status event for a subject.

Parameters

publisher	- The data publisher to use to publish this status message.
subject	- The subject of the status message.
status	- The new status of the subject, for example OBJ_STATUS_STALE, OBJ_STATUS_OK.
message	- A message giving more information about the status event.

void ds5_publish_subject_error	(	ds5_publisher_t *	publisher,
		const char *	subject,
		int	flags
	)

Publishes a subscription error event for a subject.

Parameters

publisher	- The data publisher to use to publish this error event.
subject	- The subject of the status message.
flags	- The type of error to publish, for example F_NOTFOUND.

void ds5_publish_subject_map	(	ds5_publisher_t *	publisher,
		const char *	subject,
		const char *	mapped_to,
		int	flags
	)

Publishes a subscription map event for a subject.

Parameters

publisher	- The data publisher to use to publish this error event.
subject	- The subject of the map message.
mapped_to	- The subject that "subject" is mapped to
flags	- Reserved

void ds5_publish_to_peer	(	ds5_publisher_t *	publisher,
		int	peernum,
		ds_data_t *	dsdata
	)

Publish an update for a subject to the specified peer.

Parameters

publisher	- The data publisher to use to publish this response.
peernum	- The peer to publish this response to.
dsdata	- The data to be sent.

void ds5_publish_to_peer_no_free	(	ds5_publisher_t *	publisher,
		int	peernum,
		ds_data_t *	dsdata
	)

Publish an update for a subject to the specified peer. The update will not be freed.

Parameters

publisher	- The data publisher to use to publish this response.
peernum	- The peer to publish this response to.
dsdata	- The data to be sent.

void ds5_publish_to_subscribed_peers	(	ds5_publisher_t *	publisher,
		ds_data_t *	dsdata
	)

Publish an update for a subject to all peers that have subscribed.

Parameters

publisher	- The data publisher to use to publish this response.
dsdata	- The data to be sent.

void ds5_publish_to_subscribed_peers_no_free	(	ds5_publisher_t *	publisher,
		ds_data_t *	dsdata
	)

Publish an update for a subject to all peers that have subscribed. The update will not be freed.

Parameters

publisher	- The data publisher to use to publish this response.
dsdata	- The data to be sent.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation