DataSource for C SDK  7.1.28.98838-0467ac22
Deprecated: Sending Object Status Information

Macros

#define S_FAILOVER   0x1101 /* Failover implies S_STALE|S_UPDCLR */
 Indicates the object may not be receiving updates any more. More...
 
#define S_INFO   0x0000
 This is an information only status message. More...
 
#define S_NOTSTALE   0x0004
 This indicates that an object is no longer stale and is receiving updates again. More...
 
#define S_STALE   0x0001
 This indicates the object may not be receiving updates any more. More...
 
#define S_UPDCLR   0x0100
 This indicates an update to this object should clear the previously-sent S_STALE or S_NOTSTALE message. More...
 

Functions

void ds_send_status (const char *subject, unsigned short flags, unsigned short code, const char *msgstr)
 Sends a user defined status message about a particular object. More...
 
void ds_send_status_direct (const char *subject, unsigned short flags, unsigned short code, const char *msgstr)
 Sends a user defined status message about a particular object. More...
 
void ds_send_status_to_peer (int peer, const char *subject, unsigned short flags, unsigned short code, const char *msgstr)
 Sends a user defined status message about a particular object. More...
 

Detailed Description

DataSource applications can send or receive data, or both at the same time. Status messages can also be sent or received. This this section is about sending and receiving status messages about individual objects.

You can use DataSource to notify your application's peers about the status of individual objects. These functions are used by a DataSource to let its peers know the status of individual objects. The information sent can be intepreted in different ways and by different applications. The flags used indicate the state of the object, the two extra arguments to these functions allow further data to be passed. In the case of sending information to a Caplin Liberator, the flags will be interpreted by the Liberator and the extra data passed through to the client. This could be used by a DataSource to give a code or a reason string that the client can understand or present to the end user.

When sending an S_FAILOVER flag the DataSource may or may not get a discard message come back. If it does it means the peer managed to request the object from another DataSource. If it does not receive a discard message then the subscription is still live and if the object becomes live again this DataSource should continue to send updates for it.

When a DataSource application is one that makes requests and receives data it is at the other end of these status messages. The application will get its recv_object_status_t callback called when the DataSource library receives a status message from a peer or when the library issues a status itself.

See also
ds_init_t
ds_set_status_up()
ds_set_status_down()
ds_set_status_msg()

Macro Definition Documentation

#define S_FAILOVER   0x1101 /* Failover implies S_STALE|S_UPDCLR */

Indicates the object may not be receiving updates any more.

  • use an alternative DataSource if possible.

    This status is one that can be sent by an application that sends data, however on the receiving side it is handled by the DataSource library, before being passed on to the application.

    This define is used as the flags parameter for ds_send_status() and ds_send_status_to_peer().

#define S_INFO   0x0000

This is an information only status message.

This status is one that can be sent by an application that sends data, or handled by an application that receives data.

This define is used as the flags parameter for ds_send_status() and ds_send_status_to_peer() or received in a recv_object_status() callback

#define S_NOTSTALE   0x0004

This indicates that an object is no longer stale and is receiving updates again.

This status is one that can be sent by an application that sends data, or handled by an application that receives data.

This define is used as the flags parameter for ds_send_status() and ds_send_status_to_peer().

#define S_STALE   0x0001

This indicates the object may not be receiving updates any more.

This status is one that can be sent by an application that sends data, or handled by an application that receives data.

This define is used as the flags parameter for ds_send_status() and ds_send_status_to_peer().

#define S_UPDCLR   0x0100

This indicates an update to this object should clear the previously-sent S_STALE or S_NOTSTALE message.

The S_UPDCLR flag should be sent at the same time as the S_STALE or S_NOTSTALE message.

This status is one that can be sent by an application that sends data, or handled by an application that receives data.

This define is used as the flags parameter for ds_send_status() and ds_send_status_to_peer().

Function Documentation

void ds_send_status ( const char *  subject,
unsigned short  flags,
unsigned short  code,
const char *  msgstr 
)

Sends a user defined status message about a particular object.

Parameters
subjectName of the object
flagsIndicates the type of the message
codeUser-definable status code
msgstrUser-definable status message
1 ds_send_status("/OBJ1", S_STALE|S_UPDCLR, 0, "");
void ds_send_status_direct ( const char *  subject,
unsigned short  flags,
unsigned short  code,
const char *  msgstr 
)

Sends a user defined status message about a particular object.

Parameters
subjectName of the object
flagsIndicates the type of the message
codeUser-definable status code
msgstrUser-definable status message
Note
This function will send the object directly bypassing the active cache
1 ds_send_status_direct("/OBJ1", S_STALE|S_UPDCLR, 0, "");
void ds_send_status_to_peer ( int  peer,
const char *  subject,
unsigned short  flags,
unsigned short  code,
const char *  msgstr 
)

Sends a user defined status message about a particular object.

Parameters
peerPeer number to send the status mesage to
subjectName of the object
flagsIndicates the type of the message
codeUser-definable status code
msgstrUser-definable status message
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.
For the purpose of easy integration with the active cache, sending to peer -1 is the equivalent of calling ds_send_status().

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