DataSource for C SDK  7.1.28.98838-0467ac22
Deprecated: DataSource Library Initialisation

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"
/* 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) {
printf("Peer %d is up\n",peer);
break;
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;
}
}
/* 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++ ) {
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);
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
peerThe number of the DataSource peer
countNumber of objects in this request
subjectsArray of the object names in this request
flagsFlags 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
fromThe subject requested
toThe 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
peerThe number of the DataSource peer
subjectName of the object this message is being sent for
flagsThe 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
peerThe number of the DataSource peer
subjectName of the object referred to in this status message
statusIndicates the type of the status message
codeUser-definable status code
msgstrUser-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
peerThe number of the DataSource peer
statusStatus type
valPeer ID
dataPeer 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
peerThe number of the DataSource peer
pktThe update packet containing the new data
tmThe 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
peerThe number of the DataSource peer
countNumber of objects in this request
subjectsArray of the object names in this request
flagsFlags 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
serviceThe name of the service
statusThe 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
peerThe number of the DataSource peer
pktThe 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
fileFilename of the main configuration file
argcNumber of arguments (as passed to main())
argvArgument 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
initThe initialisation object
argcNumber of arguments (as passed to main())
argvArgument 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()

Generated on Fri Jan 20 2023 17:49:17 for DataSource for C SDK