Transformer SDK For C
8.0.1.209428-2690cd2c
|
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_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. 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, tf_finalize_cb finalize, 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, tf_finalize_cb finalize) |
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, 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... | |
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:
This is a simple example of how to register for updates to a single symbol.
#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 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.
val | - User registered integer |
data | - User registered pointer |
handle | - Deleted handle. This is provided for reference only. |
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.
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 |
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.
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 |
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.
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 |
0 | - Remove this handle from the system (i.e. cancel the subscription) |
1 | - Don't remove this handle from the system |
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.
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 |
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.
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.
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 |
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:
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.
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.
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 |
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.
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.
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 |
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.
void tf_handle_delete | ( | tf_handle_t * | handle | ) |
Delete a handle to a listener or a provider.
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.
handle | - Handle |
id | - New callback value |
data | - New callback pointer |
int tf_handle_set_listener_finalize_cb | ( | tf_handle_t * | handle, |
tf_finalize_cb | finalize | ||
) |
Associate a callback for handle deletion with a listener.
handle | - The listener handle |
finalize | - The callback for handle deletion |
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.
handle | - Handle |
update | - New update function |
nodata | - New nodata function |
status | - New status function |
val | - New callback value |
data | - New callback pointer |
int tf_handle_set_nodata_cb | ( | tf_handle_t * | handle, |
tf_nodata_cb | nodata | ||
) |
Set the nodata callback on a listener.
handle | - Handle |
nodata | - New nodata function |
int tf_handle_set_status_cb | ( | tf_handle_t * | handle, |
tf_status_cb | status | ||
) |
Set the status callback on a listener.
handle | - Handle |
status | - New status function |
int tf_handle_set_update_cb | ( | tf_handle_t * | handle, |
tf_update_cb | update | ||
) |
Set the update callback on a listener.
handle | - Handle |
update | - New update function |