Transformer SDK For C
6.2.9.307380
|
Functions | |
tf_handle_t * | tf_add_provider (const char *pattern, int provider_typeflags, tf_request_cb request, tf_discard_cb discard, int val, void *data, void *reserved) |
Registers the specified data provider with the Transformer core. More... | |
tf_handle_t * | tf_add_provider_nspace (ds5_namespace_t *nspace, int provider_typeflags, tf_request_cb request, tf_discard_cb discard, int val, void *data, void *reserved) |
Registers the specified data provider with the Transformer core. More... | |
int | tf_handle_set_discard_cb (tf_handle_t *handle, tf_discard_cb discard) |
Set the discard callback on a provider. More... | |
int | tf_handle_set_provider_params (tf_handle_t *handle, tf_request_cb request, tf_discard_cb discard, int val, void *data) |
Set the the callback parameters for a provider. More... | |
int | tf_handle_set_request_cb (tf_handle_t *handle, tf_request_cb request) |
Set the request callback on a provider. More... | |
A transformer module can register itself with the Transformer core as a provider (source) of data.
When a request is made for an object that matches the object name pattern the data provider was registered with, the user supplied callback is called, and the callback should either publish data for the object, or configure it self to publish data.
When a peer requests data matching a provider, if the data has been cached by the Transformer it will be sent to the peer before calling the provider's request callback, so a complete image may not be needed to be distributed by the module.
Using a provider mechanism rather than always publishing data has several advantages:
For example, a Transformer module could subscribe to some objects and calculate time intervalised data (used for producing charts) for periods of 5 minutes, 30 minutes, 1 day and 7 days. This could potentially create a very large amount of type 3 record data. Each time intervalised period for each object could be stored in a database, and would only be published to the Transformer if the particular object and time period was requested from the module.
Simplified Subscription management
Although the Transformer will take care to ensure that data is distributed to all listening peers and modules, by default the request() callbacks may be called multiple times (however the discard() callback will only be called the once). This allows a module to publish cached data directly to the peer bypassing the Transformer's cache. By specifying the TF_LISTENER_PROVIDEONCE flag to the tf_add_provider() function, the request() and discard() callbacks will only be called once, thus obviating the need for a module to perform reference counting.
Example:
This is a simple example of how to provide data upon request. In this example for clarity, only a single update is sent.
tf_handle_t* tf_add_provider | ( | const char * | pattern, |
int | provider_typeflags, | ||
tf_request_cb | request, | ||
tf_discard_cb | discard, | ||
int | val, | ||
void * | data, | ||
void * | reserved | ||
) |
Registers the specified data provider with the Transformer core.
pattern | - Object pattern |
provider_typeflags | - Flags for the provider |
request | - Callback function to handle requests |
discard | - Callback function to handle discards |
val | - Callback parameter |
data | - Callback parameter |
reserved | - Reserved for future use, assign to NULL |
NULL | - Handle couldn't be added (usually a result of a malformed regex) |
tf_handle_t* tf_add_provider_nspace | ( | ds5_namespace_t * | nspace, |
int | provider_typeflags, | ||
tf_request_cb | request, | ||
tf_discard_cb | discard, | ||
int | val, | ||
void * | data, | ||
void * | reserved | ||
) |
Registers the specified data provider with the Transformer core.
nspace | - The namespace for which the supplied provider should be called. |
provider_typeflags | - Flags for the provider |
request | - Callback function to handle requests |
discard | - Callback function to handle discards |
val | - Callback parameter |
data | - Callback parameter |
reserved | - Reserved for future use, assign to NULL |
NULL | - Handle couldn't be added (usually a result of a malformed regex) |
int tf_handle_set_discard_cb | ( | tf_handle_t * | handle, |
tf_discard_cb | discard | ||
) |
Set the discard callback on a provider.
handle | - Handle |
discard | - New discard function |
int tf_handle_set_provider_params | ( | tf_handle_t * | handle, |
tf_request_cb | request, | ||
tf_discard_cb | discard, | ||
int | val, | ||
void * | data | ||
) |
Set the the callback parameters for a provider.
handle | - Handle |
request | - New request function |
discard | - New discard function |
val | - New callback value |
data | - New callback pointer |
int tf_handle_set_request_cb | ( | tf_handle_t * | handle, |
tf_request_cb | request | ||
) |
Set the request callback on a provider.
handle | - Handle |
request | - New request function |