Receiving updates

Macros
#define	TF_LISTENER_ACCESSORY
	Listener is an accessory. More...

Functions
tf_handle_t *	tf_add_listener (const char *pattern, int listener_typeflags, tf_update_cb update, tf_nodata_cb nodata, tf_status_cb status, int val, void *data, void *reserved)
	Create a new object listener. More...
tf_handle_t *	tf_add_listener_get_cache (const char *pattern, int listener_typeflags, tf_update_cb update, tf_nodata_cb nodata, tf_status_cb status, int val, void *data, void *reserved, ds_data_t **dsdata_ptr)
	Create a new object listener returning the cache contents. More...
tf_handle_t *	tf_add_listener_nspace (ds5_namespace_t *nspace, int listener_typeflags, tf_update_cb update, tf_nodata_cb nodata, tf_status_cb status, int val, void *data, void *reserved)
	Create a new object listener for subjects that match the supplied namespace. More...
tf_handle_t *	tf_add_type_listener (int data_type, int listener_typeflags, tf_update_cb update, tf_nodata_cb nodata, tf_status_cb status, int val, void *data, void *reserved)
	Register an interest in a particular DataSource type. More...
void	tf_handle_delete (tf_handle_t *handle)
	Delete a handle to a listener or a provider. More...
int	tf_handle_set_callback_params (tf_handle_t *handle, int val, void *data)
	Set the callback parameters on a handle. More...
int	tf_handle_set_listener_params (tf_handle_t *handle, tf_update_cb update, tf_nodata_cb nodata, tf_status_cb status, int val, void *data)
	Set the the callback parameters for a listener. More...
int	tf_handle_set_nodata_cb (tf_handle_t *handle, tf_nodata_cb nodata)
	Set the nodata callback on a listener. More...
int	tf_handle_set_status_cb (tf_handle_t *handle, tf_status_cb status)
	Set the status callback on a listener. More...
int	tf_handle_set_update_cb (tf_handle_t *handle, tf_update_cb update)
	Set the update callback on a listener. More...

Detailed Description

Allow a module to subscribe, and unsubscribe, listeners interested in receiving updates for objects that match a particular name pattern, or are of a specific object type.

A listener can be added for multiple subscriptions, so that it can be called several times for the same object update. For example, an update to the record /LO/VOD will result in the update method being invoked three times for a listener that has been registered for the regex ^/, ^/LO and for the object type record.

Wildcards are particularly useful for listening for broadcast data, which will come into the Transformer core without being actively requested by a module.

Example:

#include "transformer.h"

static int    demo_recv_update(tf_handle_t *handle, int peer, ds_data_t *dsdata, int flags, int id, void *data);

static tf_handle_t   *provider_handle;

void mod_init(char *name)
{
    provider_handle = tf_add_listener("^/TEST", TF_LISTENER_WILDCARD, demo_recv_request, demo_recv_discard, 0, NULL, NULL);
}

static int    demo_recv_update(tf_handle_t *handle, int peer, ds_data_t *dsdata, int flags, int id, void *data)
{
    /* Update received */

    return 1;
}

This is a simple example of how to register for updates to a single symbol.

Macro Definition Documentation

#define TF_LISTENER_ACCESSORY

Listener is an accessory.

An accessory listener will not cause an object to be requested. Similarly it will not prevent an object from being disarded should another listener (or peer) not require the object anymore.

Function Documentation

tf_handle_t* tf_add_listener	(	const char *	pattern,
		int	listener_typeflags,
		tf_update_cb	update,
		tf_nodata_cb	nodata,
		tf_status_cb	status,
		int	val,
		void *	data,
		void *	reserved
	)

Create a new object listener.

Parameters

pattern	- Object name that we're adding this listener for
listener_typeflags	- Any flags that we need on the listener
update	- The callback for update message
nodata	- The callback for nodata message
status	- The callback for status messsages
val	- Callback value
data	- Callback value
reserved	- Reserved for future use, assign to NULL

Returns

A for this subscription

Return values

NULL	- Handle couldn't be added (usually a result of a malformed regex)

This function will create object listeners for individual objects and wildcard subscriptions. The parameter listener_typeflags specify what type of listener is required.

If the subscription is for a single object and the flag TF_LISTENER_NOASKPEERS is defined, then a request will not be made to any connected DataSource peers.

If the subscription is for a single object and the flag TF_LISTENER_NOASKMODULES is defined, then a request will not be made to any providers.

See also

tf_handle_delete()

tf_handle_t* tf_add_listener_get_cache	(	const char *	pattern,
		int	listener_typeflags,
		tf_update_cb	update,
		tf_nodata_cb	nodata,
		tf_status_cb	status,
		int	val,
		void *	data,
		void *	reserved,
		ds_data_t **	dsdata_ptr
	)

Create a new object listener returning the cache contents.

Parameters

pattern	- Object name that we're adding this listener for
listener_typeflags	- Any flags that we need on the listener
update	- The callback for update message
nodata	- The callback for nodata message
status	- The callback for status messsages
val	- Callback value
data	- Callback value
reserved	- Reserved for future use, assign to NULL
dsdata_ptr	- Pointer to a ds_data_t * which will be modified to point to a ds_data_t with the cache contents

Returns

A for this subscription

Return values

NULL	- Handle couldn't be added (usually a result of a malformed regex)

This function will create object listeners for individual objects and wildcard subscriptions. The parameter listener_typeflags specify what type of listener is required.

If the subscription is for a single object and the flag TF_LISTENER_NOASKPEERS is defined, then a request will not be made to any connected DataSource peers.

If the subscription is for a single object and the flag TF_LISTENER_NOASKMODULES is defined, then a request will not be made to any providers.

A cache image will only be returned under the following conditions:

• A subscription is added for a single object, that is not for a wildcard.
• The object is present within the Transformer's cache

If these conditions are not met, then dsdata_ptr will contain NULL following the return from this function. | It is the responsibility of the caller to call ds_free_data() on any returned ds_data_t.

See also

tf_add_listener()

tf_handle_delete()

tf_handle_t* tf_add_listener_nspace	(	ds5_namespace_t *	nspace,
		int	listener_typeflags,
		tf_update_cb	update,
		tf_nodata_cb	nodata,
		tf_status_cb	status,
		int	val,
		void *	data,
		void *	reserved
	)

Create a new object listener for subjects that match the supplied namespace.

Parameters

nspace	- Namespace that we wish to receive updates for.
listener_typeflags	- Any flags that we need on the listener
update	- The callback for update message
nodata	- The callback for nodata message
status	- The callback for status messsages
val	- Callback value
data	- Callback value
reserved	- Reserved for future use, assign to NULL

Returns

A handle for this subscription

Return values

NULL	- Handle couldn't be added (usually a result of a malformed regex)

This function will create object listeners for individual objects and wildcard subscriptions. The parameter listener_typeflags specify what type of listener is required. The use of a namespace implies that the subscription is of type TF_LISTENER_WILDCARD.

See also

tf_handle_delete()

tf_handle_t* tf_add_type_listener	(	int	data_type,
		int	listener_typeflags,
		tf_update_cb	update,
		tf_nodata_cb	nodata,
		tf_status_cb	status,
		int	val,
		void *	data,
		void *	reserved
	)

Register an interest in a particular DataSource type.

Register an interest in symbols with a particular DataSource type. All future updates with the specified type will be propagated through to the requesting module.

Parameters

data_type	- DataSource object type that we wish to receive updates for
listener_typeflags	- Any flags that we need on the listener
update	- The callback for update message
nodata	- The callback for nodata message
status	- The callback for status messsages
val	- Callback value
data	- Callback value
reserved	- Reserved for future use, assign to NULL

Returns

A handle for this subscription

If listener_typeflags has the flag TF_LISTENER_WILDNOW set, then future updates for all objects of type data_type will be delivered to the specified callbacks.

If listener_typeflags has the flag TF_LISTENER_WILDNEXT set, then any future objects of type data_type will be delivered to the specified callbacks.

Note

Unlike the legacy register_type_interest() function, this function applies to the base object type and thus can't be used to just listen to type 2 data.

See also

tf_handle_delete()

void tf_handle_delete

(

tf_handle_t *

handle

)

Delete a handle to a listener or a provider.

Parameters

handle

- Handle to remove

This function will remove the handle from the system.

If the handle being deleted is a wildcard then only the wildcard handle will be remove unless it was created with the TF_LISTENER_WILDREMOVE flag.

int tf_handle_set_callback_params	(	tf_handle_t *	handle,
		int	val,
		void *	data
	)

Set the callback parameters on a handle.

Parameters

handle	- Handle
val	- New callback value
data	- New callback pointer

Returns

0 - Success

int tf_handle_set_listener_params	(	tf_handle_t *	handle,
		tf_update_cb	update,
		tf_nodata_cb	nodata,
		tf_status_cb	status,
		int	val,
		void *	data
	)

Set the the callback parameters for a listener.

Parameters

handle	- Handle
update	- New update function
nodata	- New nodata function
status	- New status function
val	- New callback value
data	- New callback pointer

Returns

0 - Success

-1 - Failure (handle is not a listener)

int tf_handle_set_nodata_cb	(	tf_handle_t *	handle,
		tf_nodata_cb	nodata
	)

Set the nodata callback on a listener.

Parameters

handle	- Handle
nodata	- New nodata function

Returns

0 - Success

-1 - Failure (handle is not a listener)

int tf_handle_set_status_cb	(	tf_handle_t *	handle,
		tf_status_cb	status
	)

Set the status callback on a listener.

Parameters

handle	- Handle
status	- New status function

Returns

0 - Success

-1 - Failure (handle is not a listener)

int tf_handle_set_update_cb	(	tf_handle_t *	handle,
		tf_update_cb	update
	)

Set the update callback on a listener.

Parameters

handle	- Handle
update	- New update function

Returns

0 - Success

-1 - Failure (handle is not a listener)