Data Structures
struct	ds_init_t
	Defines the DataSource initialisation object. More...

Macros
#define	DS_INITIALISER
	Default initialiser for the ds_init_t object. More...

Typedefs
typedef void(*	recv_discard_t) (int peer, int count, char **subjects, unsigned short flags)
	Definition of the function type used for handling data discard requests. More...

typedef void(*	recv_map_t) (int peer, char from, char to)
	Definition of the function type used for handling map messages. More...

typedef void(*	recv_nodata_t) (int peer, char *subject, unsigned short flags)
	Definition of the function type used for receiving "nodata" messages. More...

typedef void(*	recv_object_status_t) (int peer, char subject, int status, unsigned short code, char msgstr)
	Definition of the function type used for handling objectstatus messages. More...

typedef void(*	recv_peer_status_t) (int peer, int status, int val, void *data)
	Definition of the function type used for receiving peer status messages. More...

typedef void(*	recv_replay_t) (int peer, ds_data_t *pkt, time_t tm)
	Definition of the function type used for receiving updates from a the DataSource library when calling the various replay functions. More...

typedef void(*	recv_request_t) (int peer, int count, char **subjects, unsigned short flags)
	Definition of the function type used for handling data requests. More...

typedef void(*	recv_service_status_t) (char *service, int status)
	Definition of the function type used for handling service status messages. More...

typedef void(*	recv_update_t) (int peer, ds_data_t *pkt)
	Definition of the function type used for receiving updates from a DataSource peer. More...

Functions
void	ds_config_init (const char file, int argc, char *argv)
	Set up the configuration of the DataSource. More...

int	ds_init (ds_init_t init, int argc, char *argv)
	Parse the configuration files and initialise the DataSource library. More...

Detailed Description

The initialisation of a DataSource process is fairly simple. It comprises of setting up configuration, application settings and entering the event loop.

Configuration options can be added, in the application, but even if they are not the DataSource library will add options that need to be parsed. Calling ds_config_init() will parse the given file and the command line arguments passed in.

The next step is to setup and initialise the application settings. This is done by setting the various members of the ds_init_t structure. Defaults for this can be used by initialising the object to the static initialiser DS_INITIALISER as seen in the example. However, some members will need to be set if the application is to do anything useful. For example the application name and callback functions. This object is then passed to the ds_init() function, which also takes the command line arguments, returning any unparsed arguments.

The last step is to call ds_loop() which enters the application into the event loop. If the DataSource needs to make any connections to external applications other than DataSources, adding a timed event before calling ds_loop() is the normal method. The event callback will then be called after ds_loop() has started.

If the DataSource is multi-threaded and wishes to use the DataSource event manager for the extra threads, those threads must call ds_thread_init() before calling ds_loop(). The main thread only needs to call ds_loop() however.

Example: Sample initialisation code.

#include "datasrc.h"
static ds_init_t ds = DS_INITIALISER;
/* Print a message to stdout when we connect/disconnect from peers */
static void recv_peer_status(int peer, int msg, int val, void *data)
{
    switch (msg) {
    case DS_MSG_CONNECT:
        printf("Peer %d is up\n",peer);
        break;
    case DS_MSG_DISCONNECT:
        printf("Peer %d is down\n",peer);
        break;
    }
}
/* Print a message to stdout when we receive an object status message */
static void recv_object_status(int peer, char *subject, int status, u_short code, char *msgstr)
{
   printf("Object '%s' status 0x%x\n",subject,status);
}
/* Print a message to stdout when we receive a service status message */
static void recv_service_status(char *service, int status)
{
   printf("Service '%s' status 0x%x\n",service,status);
}
/* When we receive an update, contribute it back to the originating peer with
 *  the field numbers contained with in the packet offset by 100
 */
static void recv_update(int peer,ds_data_t *dsdata)
{
    int i;
    for ( i = 0; i < dsdata->count; i++ ) {
        dsdata->fields[i].fieldnum += 100;
    }
    ds_send_data_to_peer_no_free(peer,dsdata);
}
/* On request, simply supply a packet with field 3 containing the symbol name */
void recv_request(int peer, int subjects_count, char *subjects[], u_short flags)
{
    ds_data_t *dsdata;
    int i;
    for ( i = 0; i < subjects_count; i++ ) {
        dsdata = ds_init_data(subjects[i],DS_RECORD_TYPE,F_CREATEOBJECT|F_CREATEPARENT);
        ds_add_data(dsdata,3,subjects[i]);
        ds_send_data_to_peer(peer,dsdata);
    }
}
void recv_discard(int peer, int subjects_count, char *subjects[], u_short flags)
{
/* If we were persistently sending updates then we would prevent the
 * datasource from doing so inside this function
 */
}
int main(int argc, char *argv[])
{
    ds_config_init("demo1.conf", argc, argv);
    ds.application_name = "demo1";
    ds.recv_request = recv_request;
    ds.recv_discard = recv_discard;
    ds.recv_peer_status = recv_peer_status;
    ds.recv_object_status = recv_object_status;
    ds.recv_service_status = recv_service_status;
    ds.recv_update = recv_update;
    ds_init(&ds,argc,argv);
    ds_loop();
    return 0;
}

Any callbacks specified in the initialiser may potentially be called on multiple threads, sometimes concurrently, as a result it is important that the application is thread-safe.

Macro Definition Documentation

#define DS_INITIALISER

Default initialiser for the ds_init_t object.

Typedef Documentation

typedef void(* recv_discard_t) (int peer, int count, char **subjects, unsigned short flags)

Definition of the function type used for handling data discard requests.

Parameters

peer	The number of the DataSource peer
count	Number of objects in this request
subjects	Array of the object names in this request
flags	Flags pertaining to this request

This datatype will only be used when the DataSource is active.

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

typedef void(* recv_map_t) (int peer, char *from, char *to)

Definition of the function type used for handling map messages.

Parameters

from	The subject requested
to	The subject that from is mapped to

typedef void(* recv_nodata_t) (int peer, char *subject, unsigned short flags)

Definition of the function type used for receiving "nodata" messages.

Parameters

peer	The number of the DataSource peer
subject	Name of the object this message is being sent for
flags	The nodata message type

A "nodata" message tells you of a failure or exception condition, usually in response to requesting an object (for example an "object not found" message).

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

typedef void(* recv_object_status_t) (int peer, char *subject, int status, unsigned short code, char *msgstr)

Definition of the function type used for handling objectstatus messages.

Parameters

peer	The number of the DataSource peer
subject	Name of the object referred to in this status message
status	Indicates the type of the status message
code	User-definable status code
msgstr	User-definable status message

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

The status parameter takes the values OBJ_STATUS_OK, OBJ_STATUS_STALE or OBJ_STATUS_LIMITED.

typedef void(* recv_peer_status_t) (int peer, int status, int val, void *data)

Definition of the function type used for receiving peer status messages.

Parameters

peer	The number of the DataSource peer
status	Status type
val	Peer ID
data	Peer name

This callback will receive messages notifying the application of when the DataSource libraries have made a connection or disconnected with another DataSource peer.

msg Will have the values DS_MSG_CONNECT or DS_MSG_DISCONNECT

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

typedef void(* recv_replay_t) (int peer, ds_data_t *pkt, time_t tm)

Definition of the function type used for receiving updates from a the DataSource library when calling the various replay functions.

Parameters

peer	The number of the DataSource peer
pkt	The update packet containing the new data
tm	The time at which the update was originally sent

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

typedef void(* recv_request_t) (int peer, int count, char **subjects, unsigned short flags)

Definition of the function type used for handling data requests.

Parameters

peer	The number of the DataSource peer
count	Number of objects in this request
subjects	Array of the object names in this request
flags	Flags pertaining to this request

This datatype will only be used when the DataSource is active.

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

typedef void(* recv_service_status_t) (char *service, int status)

Definition of the function type used for handling service status messages.

Parameters

service	The name of the service
status	The status type

typedef void(* recv_update_t) (int peer, ds_data_t *pkt)

Definition of the function type used for receiving updates from a DataSource peer.

Parameters

peer	The number of the DataSource peer
pkt	The update packet containing the new data

Note: peer is not the DataSource ID specified by datasrc_id parameter in the configuration file, but corresponds to the order of the peer's add-peer entries in the configuration file. The first add-peer is for peer 0, the next peer 1 and so on.

Function Documentation

void ds_config_init	(	const char *	file,
		int	argc,
		char **	argv
	)

Set up the configuration of the DataSource.

Parameters

file	Filename of the main configuration file
argc	Number of arguments (as passed to main())
argv	Argument array (as passed to main())

If file is NULL then the default of "datasrc.conf" is taken.

This should be the first DataSource function that is called by your application. It sets up the configuration of the DataSource.

The command line arguments passed in here will not be altered by this function.

See also: ds5_config_init()

int ds_init	(	ds_init_t *	init,
		int	argc,
		char **	argv
	)

Parse the configuration files and initialise the DataSource library.

Parameters

init	The initialisation object
argc	Number of arguments (as passed to main())
argv	Argument array (as passed to main())

Returns: New value for argc

This function should be called after any local configuration options have been added to the configuration context and the initialisation object has been setup

The command line arguments passed to the application's main() function should also be passed in here. The library will filter out any arguments used by the configuration subsystem and leave only non-matching arguments

See also: ds5_init()

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation