DataSource for C SDK  6.2.20.310828
Acting as a source of data

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_tds5_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_tds5_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_tds5_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:

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_add_record_int(dsdata, "Value", rand());
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_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 */
}
}
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);
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);
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.

Generated on Wed Jan 24 2018 12:22:46 for DataSource for C SDK