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

subject	Name of the object
flags	Indicates the type of the message
code	User-definable status code
msgstr	User-definable status message

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

subject	Name of the object
flags	Indicates the type of the message
code	User-definable status code
msgstr	User-definable status message

Note

This function will send the object directly bypassing the active cache

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

peer	Peer number to send the status mesage to
subject	Name of the object
flags	Indicates the type of the message
code	User-definable status code
msgstr	User-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().