Macros
#define	DS_AND(p1, p2, a)
	Combine two peersets using bitwise and. More...

#define	DS_AND3_ISZERO(p1, p2, p3)
	Test if the bitwise and of 3 peersets is 0. More...

#define	DS_AND_EQ(a1, a2, eq)
	Test if the bitwise and of 2 peersets is equal to peerset. More...

#define	DS_AND_ISZERO(p1, p2)
	Test if the bitwise and of 2 peersets is 0. More...

#define	DS_CACHE_DATASRC
	Peer index of cache datasrc. More...

#define	DS_CLR(n, p)
	Clears peer n in peerset p. More...

#define	DS_INTERNAL_DATASRC
	Peer index of internal datasrc. More...

#define	DS_ISEQUAL(p1, p2)
	Test if 2 peersets are equal. More...

#define	DS_ISSET(n, p)
	Tests whether peer n in peerset p. More...

#define	DS_ISZERO(p)
	Checks if all peers in peerset p are cleared. More...

#define	DS_MAX_PEERS
	Maximum number of peers. More...

#define	DS_MIN_PEER
	Minimum index for configured peer. More...

#define	DS_MSG_AFFINITY_REMOVED
	Indiccates that any affinity entries foe the peer have been removed. More...

#define	DS_NONZERO(p)
	Sets all peers in peerset p. More...

#define	DS_NOT(p)
	Applies logical not to all peers in peerset p. More...

#define	DS_OR(p1, p2, o)
	Combine two peersets using bitwise or. More...

#define	DS_SET(n, p)
	Sets peer n in peerset p. More...

#define	DS_T_ACTIVE
	Defines the active source peer type, which can accept requests for objects. This flag could be set on the DataSource initialisation object ds_init_t or set in the `add-peer` sections of a configuration file. More...

#define	DS_T_CONTRIB
	Defines the contribution peer type. This source should automatically receive data updates for objects that it has updated itself. This flag could be set on the DataSource initialisation object ds_init_t or set in the `add-peer` sections of a configuration file. More...

#define	DS_ZERO(p)
	Unsets all peers in peerset p. More...

#define	F_NOCONNECT
	Suppresses the automatic connection to DataSource peers on startup. The connection can then be made later using ds_set_status_up(). More...

#define	F_RECVAUTOREPLAY
	Defines the Receive Auto Replay peer flag (indicating that, when restarting, this peer should accept replay updates). More...

#define	F_SENDFROMSEQ
	Defines the Send From Sequence peer flag (indicating that, when reconnecting, missed packets should be requested based on the last sequence number). More...

Typedefs
typedef struct _ds_peer_set	ds_set_t
	Defines a set of DataSource peers. More...

Functions
int	ds_peer_all_type (int flag)
	Checks if a DataSource peer of the given type is in your configuration file. More...

int	ds_peer_details (int peer, char **name)
	Gets the ID and name of a peer. More...

int	ds_peer_details_r (int peer, char *buffer, size_t buflen)
	Gets the ID and name of a peer. User must provide buffer for the name. More...

int	ds_peer_enabled_state (int peer)
	Gets the enabled/disabled state of a DataSource peer. More...

int	ds_peer_flags (int peer)
	Gets the flags of a peer. More...

int	ds_peer_host_details (int peer, char **addr)
	Gets details of the remote side of a peer. More...

int	ds_peer_host_details_r (int peer, char *buffer, size_t buflen)
	Gets details of the remote side of a peer. User must provide buffer for the address. More...

int	ds_peer_id (int peer)
	Gets the ID of a peer. More...

char *	ds_peer_label_byindex (int index)
	Return the peer label for a peer index. More...

char *	ds_peer_label_byindex_r (int peer, char *buffer, size_t buflen)
	Get the peer label for a peer index. More...

int	ds_peer_local_type (int peer)
	Gets the local type of a DataSource peer. More...

char *	ds_peer_name (int peer)
	Gets the name of a peer. More...

char *	ds_peer_name_r (int peer, char *buffer, size_t buflen)
	Gets the name of a peer. More...

int	ds_peer_type (int peer)
	Gets the type of a DataSource peer. More...

int	ds_peer_up (int peer)
	Check to see if a peer is up. More...

void	ds_set_status_down ()
	Causes the DataSource to disconnect and stop listening for connections. More...

void	ds_set_status_down_to_peer (int peer)
	Causes the DataSource to disconnect and not accept connections for this peer. More...

void	ds_set_status_msg (unsigned short msgid, const char *msgstr)
	Send a user-defined status message to all connected peers. More...

void	ds_set_status_msg_to_peer (int peer, unsigned short msgid, const char *msgstr)
	Send a user-defined status message to peer. More...

void	ds_set_status_up ()
	Causes the DataSource to connect and listen for connections. More...

void	ds_set_status_up_to_peer (int peer)
	Causes the DataSource to connect and accept connections. More...

Variables
int	ds_num_peers
	The number of DataSource peers in your configuration. If discovery is enabled then this is set to be 1023. More...

Detailed Description

What Is A DataSource Peer?

As well as being a source of data, DataSource can act as a destination for data sent from other DataSource applications, as illustrated in the diagram below:

DataSource acting as data source and a data sink

A DataSource peer is another DataSource installed remotely, which your DataSource can receive data from and send to.

As this means the link between DataSources is bidirectional, the true relationship between DataSources is shown in Figure 6.2 below.

Bidirectional links between DataSources

Objects can be requested from individual DataSource peers or groups of peers. This can be configured using the add-source-mapping configuration option.

What is an active DataSource?

An active DataSource is one that will accept requests for objects. The opposite of this is a broadcast DataSource, which simply sends all objects and updates to its peers.

It is an active DataSource's responsibility to keep track of which objects have been requested and send updates for those objects only.

Objects may be discarded as well as requested. This tells the source that we no longer wish to receive updates for this object.

When a user requests an object, and Caplin Liberator does not already have it, it will request it from one or more of its active sources. If another user requests that object Caplin Liberator will already have all the information it needs, and will respond to the user immediately.

When a user logs out or discards an object, Caplin Liberator will send a discard message to the active DataSource (as long as no other user is viewing that object). This discard will actually take place one minute after the user discarded the object; this prevents objects being requested and discarded from the source unnecessarily.

Making DataSource applications active

For a DataSource to receive requests from a DataSource peer or Caplin Liberator, the type member of the initialisation object ds_init_t must be set to DS_T_ACTIVE.

Macro Definition Documentation

#define DS_AND	(	p1,
		p2,
		a
	)

Combine two peersets using bitwise and.

#define DS_AND3_ISZERO	(	p1,
		p2,
		p3
	)

Test if the bitwise and of 3 peersets is 0.

#define DS_AND_EQ	(	a1,
		a2,
		eq
	)

Test if the bitwise and of 2 peersets is equal to peerset.

#define DS_AND_ISZERO	(	p1,
		p2
	)

Test if the bitwise and of 2 peersets is 0.

#define DS_CACHE_DATASRC

Peer index of cache datasrc.

#define DS_CLR	(	n,
		p
	)

Clears peer n in peerset p.

#define DS_INTERNAL_DATASRC

Peer index of internal datasrc.

#define DS_ISEQUAL	(	p1,
		p2
	)

Test if 2 peersets are equal.

#define DS_ISSET	(	n,
		p
	)

Tests whether peer n in peerset p.

#define DS_ISZERO ( p )

Checks if all peers in peerset p are cleared.

#define DS_MAX_PEERS

Maximum number of peers.

#define DS_MIN_PEER

Minimum index for configured peer.

#define DS_MSG_AFFINITY_REMOVED

Indiccates that any affinity entries foe the peer have been removed.

#define DS_NONZERO ( p )

Sets all peers in peerset p.

#define DS_NOT ( p )

Applies logical not to all peers in peerset p.

#define DS_OR	(	p1,
		p2,
		o
	)

Combine two peersets using bitwise or.

#define DS_SET	(	n,
		p
	)

Sets peer n in peerset p.

#define DS_T_ACTIVE

Defines the active source peer type, which can accept requests for objects. This flag could be set on the DataSource initialisation object ds_init_t or set in the add-peer sections of a configuration file.

#define DS_T_CONTRIB

Defines the contribution peer type. This source should automatically receive data updates for objects that it has updated itself. This flag could be set on the DataSource initialisation object ds_init_t or set in the add-peer sections of a configuration file.

#define DS_ZERO ( p )

Unsets all peers in peerset p.

#define F_NOCONNECT

Suppresses the automatic connection to DataSource peers on startup. The connection can then be made later using ds_set_status_up().

This flag should be set on the DataSource initialisation object ds_init_t. It can also be set in the add-peer sections of a configuration file rather than hardcoded for all peers, although hardcoding it is more likely as this is usually used when the application depends on making its own connections or other initialisation before DataSource connections are made.

#define F_RECVAUTOREPLAY

Defines the Receive Auto Replay peer flag (indicating that, when restarting, this peer should accept replay updates).

The datasrc-auto-replay option must be set in your configuration file for replay to occur. This flag could be set on the DataSource initialisation object ds_init_t, however it is more typically used in the add-peer sections of a configuration file rather than hardcoded for all peers.

#define F_SENDFROMSEQ

Defines the Send From Sequence peer flag (indicating that, when reconnecting, missed packets should be requested based on the last sequence number).

This flag could be set on the DataSource initialisation object ds_init_t or set in the add-peer sections of a configuration file. It is set on the side that will receive the missed messages, as it instructs DataSource to send the last received sequence number to the peer, which will then flush any queued messages since that sequence number.

Typedef Documentation

typedef struct _ds_peer_set ds_set_t

Defines a set of DataSource peers.

Function Documentation

int ds_peer_all_type ( int flag )

Checks if a DataSource peer of the given type is in your configuration file.

Parameters

flag	Peer flags to check for

Return values

1	- A peer of that type is configured
0	- A peer of that type is not configured

Type can be a combination DS_T_ACTIVE and DS_T_CONTRIB

int ds_peer_details	(	int	peer,
		char **	name
	)

Gets the ID and name of a peer.

Parameters

[in]	peer	The peer number
[out]	name	Name of the peer or NULL for an invalid peer number

Returns: The peer ID or -1 for an invalid peer number

Note: The peer number 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.

int ds_peer_details_r	(	int	peer,
		char *	buffer,
		size_t	buflen
	)

Gets the ID and name of a peer. User must provide buffer for the name.

Parameters

peer	- The peer number
buffer	- Buffer to hold the peer name. Set to the name of the peer or an empty string for an invalid peer number
buflen	- Length of buffer for name

Returns: The peer ID or -1 for an invalid peer number

Note: The peer number 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.

int ds_peer_enabled_state ( int peer )

Gets the enabled/disabled state of a DataSource peer.

Parameters

peer	The peer number

Return values

0	- The peer is disabled
1	- The peer is enabled

The peer state can be adjusted by using ds_set_status_up() and ds_set_status_down()

Note: The peer number 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.

int ds_peer_flags ( int peer )

Gets the flags of a peer.

Parameters

peer	The peer number

Returns: The peer flags or 0 for an invalid peer number

Note: The peer number 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 return value is defined by a logical or of F_SENDFROMSEQ F_RECVAUTOREPLAY.

int ds_peer_host_details	(	int	peer,
		char **	addr
	)

Gets details of the remote side of a peer.

Parameters

[in]	peer	The peer number
[out]	addr	Remote hostname of the peer or NULL for an invalid peer number

Returns: The port number or 0 for an invalid peer number

Note: The peer number 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.

Deprecated:: ds_peer_host_details_r() should be used.

int ds_peer_host_details_r	(	int	peer,
		char *	buffer,
		size_t	buflen
	)

Gets details of the remote side of a peer. User must provide buffer for the address.

Parameters

peer	- The peer number
buffer	- Buffer to hold the hostname. Set to the hostname of the peer or an empty string for an invalid peer number
buflen	- Length of buffer for hostname.

Note: The peer number 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.

int ds_peer_id ( int peer )

Gets the ID of a peer.

Parameters

peer	The peer number or -1 for an invalid peer number

Returns: The peer ID

Note: The peer number 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.

char* ds_peer_label_byindex ( int index )

Return the peer label for a peer index.

Parameters

index Peer index

Return values

peer	label
NULL	for an invalid peer index
null-peer	for an empty peer slot when discovery is enabled

Note: The peer index 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.

Deprecated:: ds_peer_label_byindex_r() should be used.

char* ds_peer_label_byindex_r	(	int	peer,
		char *	buffer,
		size_t	buflen
	)

Get the peer label for a peer index.

Parameters

peer	- Peer index
buffer	- Buffer to hold the label. Set to the peer label for a valid existing peer Set to "null-peer" for a valid peer index which has no peer Set to "invalid-peer" for an invalid index
buflen	- Length of buffer

Note: The peer number 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.

int ds_peer_local_type ( int peer )

Gets the local type of a DataSource peer.

Parameters

peer	The peer number

Returns: The peer type or -1 for an invalid peer number

Note: The peer number 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.

char* ds_peer_name ( int peer )

Gets the name of a peer.

Parameters

peer	The peer number

Returns: The peer name or NULL for an invalid peer number

Note: The peer number 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.

Deprecated:: ds_peer_name_r() should be used.

char* ds_peer_name_r	(	int	peer,
		char *	buffer,
		size_t	buflen
	)

Gets the name of a peer.

Parameters

peer	The peer number
buffer	Buffer to hold the name. Set to the name of the peer or an empty string for an invalid peer number
buflen	Length of buffer

Returns: The buffer passed in

Note: The peer number 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.

int ds_peer_type ( int peer )

Gets the type of a DataSource peer.

Parameters

peer	The peer number

Returns: The peer type or -1 for an invalid peer number

Note: The peer number 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.

int ds_peer_up ( int peer )

Check to see if a peer is up.

Parameters

peer

Return values

1	- the peer is connected

Returns: 0 - the peer is not connected

Note: The peer number 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.

void ds_set_status_down ( void )

Causes the DataSource to disconnect and stop listening for connections.

void ds_set_status_down_to_peer ( int peer )

Causes the DataSource to disconnect and not accept connections for this peer.

Parameters

peer	Peer number

void ds_set_status_msg	(	unsigned short	msgid,
		const char *	msgstr
	)

Send a user-defined status message to all connected peers.

Parameters

msgid	User-definable status code
msgstr	User-definable status message

void ds_set_status_msg_to_peer	(	int	peer,
		unsigned short	msgid,
		const char *	msgstr
	)

Send a user-defined status message to peer.

Parameters

peer	Peer number to send the status message to
msgid	User-definable status code
msgstr	User-definable status message

void ds_set_status_up ( void )

Causes the DataSource to connect and listen for connections.

void ds_set_status_up_to_peer ( int peer )

Causes the DataSource to connect and accept connections.

Parameters

peer	- Peer index

Variable Documentation

int ds_num_peers

The number of DataSource peers in your configuration. If discovery is enabled then this is set to be 1023.

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation