Transformer SDK For C  6.2.11.309924
Acting as a source of data

Macros

#define TF_LISTENER_PROVIDEONCE
 A provider should only be called once to supply data. More...
 

Typedefs

typedef int(* tf_discard_cb) (tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data)
 Definition of the function type used to handle provider discards. More...
 
typedef int(* tf_request_cb) (tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data)
 Definition of the function type used to handle provider requests. More...
 

Functions

tf_handle_ttf_add_provider (const char *pattern, int provider_typeflags, tf_request_cb request, tf_discard_cb discard, int val, void *data, void *finalize)
 Registers the specified data provider with the Transformer core. More...
 
tf_handle_ttf_add_provider_nspace (ds5_namespace_t *nspace, int provider_typeflags, tf_request_cb request, tf_discard_cb discard, int val, void *data, void *finalize)
 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...
 

Detailed Description

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:

#include "transformer.h"
static int demo_recv_request(tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data);
static int demo_recv_discard(tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data);
static tf_handle_t *provider_handle;
void mod_init(char *name)
{
provider_handle = tf_add_provider("^/TEST", TF_LISTENER_PROVIDEONCE, demo_recv_request, demo_recv_discard, 0, NULL, NULL);
}
static int demo_recv_request(tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data)
{
ds_data_t *dsdata;
char *name = (char *)subject; /* DSDK isn't constified */
dsdata = ds_init_data(name,DS_RECORD_TYPE,F_CREATEOBJECT|F_CREATEPARENT);
ds_add_data(dsdata,3,name);
return 1;
}
static int demo_recv_discard(tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data)
{
/* Stop sending update */
return 1;
}

This is a simple example of how to provide data upon request. In this example for clarity, only a single update is sent.

Macro Definition Documentation

#define TF_LISTENER_PROVIDEONCE

A provider should only be called once to supply data.

This flag can be used when adding providers to ensure that only a single request and discard is passed to the provider callbacks. Without this flag, the callbacks can be called many times.

Typedef Documentation

typedef int(* tf_discard_cb) (tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data)

Definition of the function type used to handle provider discards.

Parameters
handle- The handle for which we are being called for
peer- The peer that is discarding the symbol
subject- Symbol name
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
1- Don't remove this handle from the system
typedef int(* tf_request_cb) (tf_handle_t *handle, int peer, const char *subject, int flags, int id, void *data)

Definition of the function type used to handle provider requests.

Parameters
handle- The handle for which we are being called for
peer- The peer that is requesting the symbol
subject- Symbol name
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
1- Don't remove this handle from the system

Function Documentation

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 *  finalize 
)

Registers the specified data provider with the Transformer core.

Parameters
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
finalize- The callback for handle deletion
Returns
A handle for this provider
Return values
NULL- Handle couldn't be added (usually a result of a malformed regex)
See also
tf_handle_delete()
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 *  finalize 
)

Registers the specified data provider with the Transformer core.

Parameters
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
finalize- The callback for handle deletion
Returns
A handle for this provider
Return values
NULL- Handle couldn't be added (usually a result of a malformed regex)
See also
tf_handle_delete()
int tf_handle_set_discard_cb ( tf_handle_t handle,
tf_discard_cb  discard 
)

Set the discard callback on a provider.

Parameters
handle- Handle
discard- New discard function
Returns
0 - Success
-1 - Failure (handle is not a provider)
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.

Parameters
handle- Handle
request- New request function
discard- New discard function
val- New callback value
data- New callback pointer
Returns
0 - Success
-1 - Failure (handle is not a listener)
int tf_handle_set_request_cb ( tf_handle_t handle,
tf_request_cb  request 
)

Set the request callback on a provider.

Parameters
handle- Handle
request- New request function
Returns
0 - Success
-1 - Failure (handle is not a provider)

Generated on Sat Aug 26 2017 12:36:32 for Transformer SDK For C