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_t *	ds_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);
    ds_loop();
    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) {
    case SVC_STATUS_OK:
        state = "OK";
        break;
    case SVC_STATUS_STALE:
        state = "STALE";
        break;
    case SVC_STATUS_LIMITED:
        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);
    ds_loop();
    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

configfile	Filename of the main configuration file
argc	Number of arguments (as passed to main())
argv	Argument 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

argc	Number of arguments (as passed to main())
argv	Argument 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 ( void )

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 ( void )

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 ( void )

Stop the event loop that is running on the current thread.

Note: The event loop should not normally be stopped. This functionality is provided for development purposes only. Restarting the event after calling ds_stop() causes undefined behaviour.

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_module	Event Module to use (use 0 as default)
flags	Flags (use 0 as default)

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation