Transformer SDK For C
6.2.9.307380
|
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... | |
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.
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.
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 |
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, | ||
void * | reserved, | ||
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 |
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 |
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, | ||
void * | reserved | ||
) |
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 |
reserved | - Reserved for future use, assign to NULL |
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, | ||
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.
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 |
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 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.
handle | - Handle |
val | - New callback value |
data | - New callback pointer |
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 |