DataSource for C SDK  7.1.28.98838-0467ac22
Using DataSource peers

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_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:

peer1.gif
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.

peer2.gif
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,
 
)

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_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,
 
)

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,
 
)

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,
 
)

Combine two peersets using bitwise or.

#define DS_SET (   n,
 
)

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
flagPeer 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]peerThe peer number
[out]nameName 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
peerThe 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
peerThe 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]peerThe peer number
[out]addrRemote 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
peerThe 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
indexPeer index
Return values
peerlabel
NULLfor an invalid peer index
null-peerfor 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
peerThe 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
peerThe 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
peerThe peer number
bufferBuffer to hold the name. Set to the name of the peer or an empty string for an invalid peer number
buflenLength 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
peerThe 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
peerPeer number
void ds_set_status_msg ( unsigned short  msgid,
const char *  msgstr 
)

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

Parameters
msgidUser-definable status code
msgstrUser-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
peerPeer number to send the status message to
msgidUser-definable status code
msgstrUser-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.


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