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_t *	tf_add_provider (const char pattern, int provider_typeflags, tf_request_cb request, tf_discard_cb discard, int val, void data, tf_finalize_cb finalize)
	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, tf_finalize_cb 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:

The number of objects cached by the core which are not subscribed to is reduced.
The number of updates for objects which are not subscribed to is reduced.
The module itself may be able to reduce the number of calculations it needs to perform since it only needs to publish the data which has been requested.

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);
    packet_contrib(dsdata,NULL,PACKET_PUBLISH|PACKET_STORE);
    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,
		tf_finalize_cb	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,
		tf_finalize_cb	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)

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation