Transformer SDK For C  7.1.9.29929-d422075
Receiving updates

Macros

#define TF_LISTENER_ACCESSORY
 Listener is an accessory. More...
 
#define TF_LISTENER_DEFAULT
 Default listener type. More...
 
#define TF_LISTENER_NOASKMODULES
 When adding a listener, a request should not be made to providers for the object. More...
 
#define TF_LISTENER_NOASKPEERS
 When adding a listener, a request should not be made to datasources for the object. More...
 
#define TF_LISTENER_NOREGEX
 
#define TF_LISTENER_ONCE
 
#define TF_LISTENER_WILDCARD
 Convenience definition for standard wildcard behaviour. More...
 
#define TF_LISTENER_WILDNEXT
 The subscription regex should be applied to all future symbols. More...
 
#define TF_LISTENER_WILDNOW
 The subscription regex should be applied to all current symbols. More...
 
#define TF_LISTENER_WILDREMOVE
 When removing the wildcard listener, all symbols matching the regex should be removed. More...
 

Typedefs

typedef void(* tf_finalize_cb) (int val, void *data, tf_handle_t *handle)
 Definition of the function type used to call back to application when last callback for a deleted handle has been processed. More...
 
typedef int(* tf_nodata_cb) (tf_handle_t *handle, int peer, const char *subject, short nodata_flags, int flags, int id, void *data)
 Definition of the function type used to process nodata messages. More...
 
typedef int(* tf_status_cb) (tf_handle_t *handle, int peer, const char *subject, int status, u_short code, const char *message, int flags, int id, void *data)
 Definition of the function type used to process status updates. More...
 
typedef int(* tf_update_cb) (tf_handle_t *handle, int peer, ds_data_t *dsdata, int flags, int id, void *data)
 Definition of the function type used to process updates. More...
 

Functions

tf_handle_ttf_add_listener (const char *pattern, int listener_typeflags, tf_update_cb update, tf_nodata_cb nodata, tf_status_cb status, int val, void *data, tf_finalize_cb finalize)
 Create a new object listener. More...
 
tf_handle_ttf_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, tf_finalize_cb finalize, ds_data_t **dsdata_ptr)
 Create a new object listener returning the cache contents. More...
 
tf_handle_ttf_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, tf_finalize_cb finalize)
 Create a new object listener for subjects that match the supplied namespace. More...
 
tf_handle_ttf_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, tf_finalize_cb finalize)
 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 id, void *data)
 Set the callback parameters on a handle. More...
 
int tf_handle_set_listener_finalize_cb (tf_handle_t *handle, tf_finalize_cb finalize)
 Associate a callback for handle deletion with a listener. 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.

#define TF_LISTENER_DEFAULT

Default listener type.

#define TF_LISTENER_NOASKMODULES

When adding a listener, a request should not be made to providers for the object.

#define TF_LISTENER_NOASKPEERS

When adding a listener, a request should not be made to datasources for the object.

#define TF_LISTENER_NOREGEX

If this flag is specified, then regex support will be disabled for the listener and filename style globbing will be used to match wildcards.

#define TF_LISTENER_ONCE

If this flag is specified, then the wildcard listener won't be added to objects that already have identical parameters

#define TF_LISTENER_WILDCARD

Convenience definition for standard wildcard behaviour.

#define TF_LISTENER_WILDNEXT

The subscription regex should be applied to all future symbols.

If this flag is supplied then a subscription will be added for all symbols that are created in the future.

#define TF_LISTENER_WILDNOW

The subscription regex should be applied to all current symbols.

If this flag is supplied then a subscription will be added for all symbols in the cache that match the supplied regex

#define TF_LISTENER_WILDREMOVE

When removing the wildcard listener, all symbols matching the regex should be removed.

This flag is reserved for wildcard listeners, where on removal, it is desired to remove subscriptions with the same parameters that match the wildcard listener.

Typedef Documentation

typedef void(* tf_finalize_cb) (int val, void *data, tf_handle_t *handle)

Definition of the function type used to call back to application when last callback for a deleted handle has been processed.

Parameters
val- User registered integer
data- User registered pointer
handle- Deleted handle. This is provided for reference only.
Note
The handle should not be used in any API calls. It's provided to allow for sanity checking.
typedef int(* tf_nodata_cb) (tf_handle_t *handle, int peer, const char *subject, short nodata_flags, int flags, int id, void *data)

Definition of the function type used to process nodata messages.

Parameters
handle- The handle for which we are being called for
peer- The peer the nodata originated from
subject- Symbol name
nodata_flags- Type of nodata (eg F_DELETEOBJECT)
flags- Unused
id- Callback parameter associated with the handle
data- Callback parameter associated with the handle
Returns
The return value is unused
typedef int(* tf_status_cb) (tf_handle_t *handle, int peer, const char *subject, int status, u_short code, const char *message, int flags, int id, void *data)

Definition of the function type used to process status updates.

Parameters
handle- The handle for which we are being called for
peer- The peer the update originated from
subject- Symbol name
status- Object status (OBJ_STATUS_OK, OBJ_STATUS_STALE, OBJ_STATUS_OK)
code- User-definable status code
msgstr- User-definable status message
id- Callback parameter associated with the handle
data- Callback parameter associated with the handle
Return values
0- Remove this handle from the system (i.e. cancel the subscription)
1- Don't remove this handle from the system
typedef int(* tf_update_cb) (tf_handle_t *handle, int peer, ds_data_t *dsdata, int flags, int id, void *data)

Definition of the function type used to process updates.

Parameters
handle- The handle for which we are being called for
peer- The peer the update originated from
dsdata- The actual update
flags- Unused
id- Callback parameter associated with the handle
data- Callback parameter associated with the handle
Return values
0- Remove this handle from the system (i.e. cancel the subscription)
1- Don't remove this handle from the system

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

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
finalize- The callback for handle deletion
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.

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,
tf_finalize_cb  finalize,
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
finalize- The callback for handle deletion
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,
tf_finalize_cb  finalize 
)

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
finalize- The callback for handle deletion
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,
tf_finalize_cb  finalize 
)

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
finalize- The callback for handle deletion
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 removed unless it was created with the TF_LISTENER_WILDREMOVE flag.

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

Set the callback parameters on a handle.

Parameters
handle- Handle
id- New callback value
data- New callback pointer
Returns
0 - Success
int tf_handle_set_listener_finalize_cb ( tf_handle_t handle,
tf_finalize_cb  finalize 
)

Associate a callback for handle deletion with a listener.

Parameters
handle- The listener handle
finalize- The callback for handle deletion
Returns
A handle for this subscription
See also
tf_handle_delete()
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)

Generated on Mon Jul 20 2020 19:17:22 for Transformer SDK For C