Subscribing to updates from other peers

Data Structures
struct	ds5_subscriptionlistener_t
	An implementation of this interface allows applications to receive events raised for a ds5_subscription_t. More...

Macros
#define	OBJ_STATUS_INFO   0x0000
	Status information message only. More...
#define	OBJ_STATUS_LIMITED   0x0008
	The status of an object is limited. More...
#define	OBJ_STATUS_OK   0x0001
	The status of an object is OK. More...
#define	OBJ_STATUS_STALE   0x0002
	The status of an object is Stale. More...

Typedefs
typedef struct _ds5_subscription_s	ds5_subscription_t
	Represents a subscription to a DataSource subject (see ds_create_active_subscription()) or to a namespace of DataSource subjects (See ds_create_broadcast_subscription()). More...

Functions
ds5_subscription_t *	ds5_create_active_subscription (const char *subject, ds5_subscriptionlistener_t *listener, void *context)
	Create a subscription that matches a single subject. More...
ds5_subscription_t *	ds5_create_broadcast_subscription (ds5_namespace_t *nspace, ds5_subscriptionlistener_t *listener, void *context)
	Create a subscription that matches multiple subjects. More...
void	ds5_unsubscribe (ds5_subscription_t *sub)
	Unsubscribe from the DataSource subject or namespace of DataSource subjects. More...

Detailed Description

DataSource applications can subscribe and receive updates to data from remote DataSources using the ds5_create_active_subscription() or ds5_create_broadcast_subscription() and your implementation of the ds5_subscriptionlistener_t interface.

Example: Sample code demonstrating subscribing to a single subject and implementing ds5_subscriptionlistener_t::record_updated().

static ds5_subscriptionlistener_t    sublistener;
static ds_log_t                     *event_log;

static void record_updated(void *context, ds5_subscription_t *sub, int peer, ds_data_t *dsdata)
{
    ds_log(event_log, DS_LOG_INFO,"Record updated for %s\n",dsdata->subject);
}

int main(int argc, char *argv)
{
    ds5_susbcription_t    *sub;

    ds5_config_init("demo1.conf", argc, argv);
    ds5_init(argc,argv);

    /* Get the event log */
    event_log = ds_get_event_log();

    /* Subscribe to a single object - we expect it to be a record so we only
     * implement the record updated member of the interface 
     */
    memset(sublistener, 0, sizeof(sublistener));
    sublistener.record_updated = record_updated;

    sub = ds5_create_active_subscription("/DEMO/MSFT", &sublistener, NULL);


    ds_loop();
    return 0;
}

Macro Definition Documentation

#define OBJ_STATUS_INFO   0x0000

Status information message only.

This is a status used by the DataSource library for the ds5_subscriptionlistener_t::subscription_status() callback. An application that requests and receives data will receive this status.

#define OBJ_STATUS_LIMITED   0x0008

The status of an object is limited.

One or more of the non-required source for this object are down or have sent an explicit stale status message.

This is a status used by the DataSource library for the ds5_subscriptionlistener_t::subscription_status() callback. An application that requests and receives data will receive this status.

#define OBJ_STATUS_OK   0x0001

The status of an object is OK.

This is a status used by the DataSource library for the ds5_subscriptionlistener_t::subscription_status() callback. An application that requests and receives data will receive this status.

#define OBJ_STATUS_STALE   0x0002

The status of an object is Stale.

One or more of the required sources for this object are down or have sent an explicit stale status messsage. This is a status used by the DataSource library for the ds5_subscriptionlistener_t::subscription_status() callback. An application that requests and receives data will receive this status.

Typedef Documentation

typedef struct _ds5_subscription_s ds5_subscription_t

Represents a subscription to a DataSource subject (see ds_create_active_subscription()) or to a namespace of DataSource subjects (See ds_create_broadcast_subscription()).

Note

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

Function Documentation

ds5_subscription_t* ds5_create_active_subscription	(	const char *	subject,
		ds5_subscriptionlistener_t *	listener,
		void *	context
	)

Create a subscription that matches a single subject.

Parameters

subject	- The subject that this subscription will receive updates for.
listener	- The subscription listener that will receive updates to subjects with the supplied ds5_namespace_t.
context	- A context that is passed to the callback functions of the subscription listener (ds5_subscriptionlistener_t). The structure and contents of this context is application specific.

Returns

A subscription handle that can be used to cancel this subscription using ds5_unsubscribe().

Note

This function will issue a subscription request to any connected active DataSource peers for the supplied subject.

ds5_subscription_t* ds5_create_broadcast_subscription	(	ds5_namespace_t *	nspace,
		ds5_subscriptionlistener_t *	listener,
		void *	context
	)

Create a subscription that matches multiple subjects.

Parameters

nspace	- The namespace that defines the subjects this subscription will receive.
listener	- The subscription listener that will receive updates to subjects with the supplied ds5_namespace_t.
context	- A context that is passed to the callback functions of the subscription listener (ds5_subscriptionlistener_t). The structure and contents of this context is application specific.

Returns

A subscription handle that can be used to cancel this subscription using ds5_unsubscribe().

Note

As a broadcast subscription will potentially match many subjects, a request will not be issued to connected peers.

void ds5_unsubscribe

(

ds5_subscription_t *

sub

)

Unsubscribe from the DataSource subject or namespace of DataSource subjects.

Parameters

sub	- The subscription to unsubscribe from.

Following a call to this function, the associated listener will not recieve any further events to its ds5_subscriptionlistener_t.