DataSource for C SDK  6.2.20.310828
DataSource Library Initialisation

Data Structures

struct  ds5_connectionlistener_t
 Implement this interface to receive connection status information when using the DSv5 API. More...
 

Macros

#define DS_MSG_CONNECT   0x0100
 Defines the connect message type. More...
 
#define DS_MSG_DISCONNECT   0x0200
 Defines the disconnect message type. More...
 
#define SVC_STATUS_DOWN   0x0002
 The status of a data service is down. More...
 
#define SVC_STATUS_LIMITED   0x0008
 The status of a data service is limited. More...
 
#define SVC_STATUS_OK   0x0001
 The status of a data service is OK. More...
 

Functions

void ds5_add_connectionlistener (ds5_connectionlistener_t *connection_listener, void *context)
 Adds a connection listener. The listener receives status events about the state of the DataSource application's connection to other peers. More...
 
void ds5_config_init (const char *configfile, int argc, char **argv)
 Sets up the configuration of the DataSource. More...
 
int ds5_init (int argc, char **argv)
 Parses the DataSource configuration files and initialises the DataSource library. The configuration is that supplied in the configuration file passed to ds5_config_init() with the addition of any configureation items supplied within argv. More...
 
ds_log_tds_get_event_log (void)
 Returns a handle to the event log used by Datasource for C. More...
 
void ds_loop ()
 Start the DataSource event loop. More...
 
void ds_reserve_std_fds ()
 Reserves the standard sockets for the std streams. More...
 
void ds_stop ()
 
void ds_thread_init (int event_module, int flags)
 Initialise the event loop for this thread. 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 ds5_config_init() will parse the given file and the command line arguments passed in.

The next step is to register any event listeners using ds5_add_connectionlistener(), subscriptions using ds5_create_broadcast_subscription() or ds5_create_active_subscription() and ds5_publisher_t using ds5_create_active_publisher() etc

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"
int main(int argc, char *argv[])
{
ds5_config_init("demo1.conf", argc, argv);
ds5_init(argc,argv);
return 0;
}

Sample code demonstrating how to register a connection listener.

#include "datasrc.h"
static ds5_connectionlistener_t conn_listener;
static ds_log_t *event_log;
static void peer_status(void *context, int peer_index, const char *peer_name, int state)
{
ds_log(event_log, DS_LOG_NOTIFY, "Peer %d (%s) has %s\n",peer_index, peer_name,
state == DS_MSG_CONNECT ? "connected" : "disconnected");
}
static void service_status(void *context, const char *service_name, int state)
{
const char *state;
switch (state) {
state = "OK";
break;
case SVC_STATUS_STALE:
state = "STALE";
break;
state = "LIMITED";
break;
}
ds_log(event_log,DS_LOG_NOTIFY,"Service %s has status %s\n", service_name, state);
}
int main(int argc, char *argv[])
{
ds5_config_init("demo1.conf", argc, argv);
ds5_init(argc,argv);
/* Save the event log for later */
event_log = ds_get_event_log();
/* Setup and register the connection listener */
conn_listener.peer_status = peer_status;
conn_listener.service_status = service_status;
ds5_add_connectionlistener(&conn_listener, NULL);
return 0;
}

Macro Definition Documentation

#define DS_MSG_CONNECT   0x0100

Defines the connect message type.

This parameter is sent to the ds5_connectionlistener_t::peer_status() callback function when a DataSource peer connection has been established.

#define DS_MSG_DISCONNECT   0x0200

Defines the disconnect message type.

This parameter is sent to the ds5_connectionlistener_t::peer_status() callback function when a DataSource peer connection has been lost.

#define SVC_STATUS_DOWN   0x0002

The status of a data service is down.

One or more required sources for this data service are down.

This is a status used by the DataSource library for the ds5_connectionlistener_t::service_status() callback. All applications will receive these status callbacks.

#define SVC_STATUS_LIMITED   0x0008

The status of a data service is limited.

One or more non-required sources for this data service are down.

This is a status used by the DataSource library for the ds5_connectionlistener_t::service_status() callback. All applications will receive these status callbacks.

#define SVC_STATUS_OK   0x0001

The status of a data service is OK.

All required sources for this data service are connected.

This is a status used by the DataSource library for the ds5_connectionlistener_t::service_status() callback. All applications will receive these status callbacks.

Function Documentation

void ds5_add_connectionlistener ( ds5_connectionlistener_t connection_listener,
void *  context 
)

Adds a connection listener. The listener receives status events about the state of the DataSource application's connection to other peers.

Parameters
connection_listener- The connection listener to be registered.
context- A context that is passed to the callback functions of the connection listener. The structure and content of this context is application specific.
You can register more than one connection listener with DataSource. Each
registered connection listener  receives events about changes to the connection
statuses of allpeers.
void ds5_config_init ( const char *  configfile,
int  argc,
char **  argv 
)

Sets up the configuration of the DataSource.

Parameters
configfileFilename of the main configuration file
argcNumber of arguments (as passed to main())
argvArgument array (as passed to main())

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

This must be the first DataSource function that is called by your application.

The command line arguments passed in here will not be altered by this function, however, options to override the configuration file specified with this function and the application-name will be extracted.

int ds5_init ( int  argc,
char **  argv 
)

Parses the DataSource configuration files and initialises the DataSource library. The configuration is that supplied in the configuration file passed to ds5_config_init() with the addition of any configureation items supplied within argv.

Parameters
argcNumber of arguments (as passed to main())
argvArgument array (as passed to main())
Returns
The new value for argc

This function should be called after any local configuration options have been added to the configuration context.

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.

Note
The use of this function (as opposed to ds_init()) is required in order to use the new DataSource v5 features of DataSource for C.
ds_log_t* ds_get_event_log ( void  )

Returns a handle to the event log used by Datasource for C.

Returns
The log file object that refers to the DataSource for C event log.
void ds_loop ( )

Start the DataSource event loop.

This function should be the last function to be called in the application's main function. It will enter the DataSource library's event manager loop and not return. Any necessary read events or timed events should therefore be registered before ds_loop() is called.

See also
ds_thread_init()
void ds_reserve_std_fds ( )

Reserves the standard sockets for the std streams.

This function reserves sockets for the standard input, output and error streams by redirecting them to to /dev/null.

Note
If the fd's normally associated with the std streams are allocated before this routine is called and the daemon-enable option is configured to be on, unusual behaviour may occur.
This routine should be called before any code that may allocate fd's. ds5_config_init() calls this routine so it does not need to be called explicitly unless code that allocates fd's is called before ds5_config_init().
void ds_stop ( )

Stop the event loop

Note
The event should not normally be stopped. This functionality is provided for development purposes only.
void ds_thread_init ( int  event_module,
int  flags 
)

Initialise the event loop for this thread.

This function should only be called if your application is multi-threaded and wants to use DataSource with more than one thread. Each thread should call ds_thread_init() once it has been started and call ds_loop() to enter the event loop.

Note
These threads should be active for the full lifetime of the process and should not be created and deleted dynamically.
Parameters
event_moduleEvent Module to use (use 0 as default)
flagsFlags (use 0 as default)

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