transformer.h File Reference

Go to the source code of this file.

Data Structures
struct	_authfuncs
	Define the callback functions that should be implemented by a permissioning module. More...
struct	_userinfo
	Defines the functions required to support userdata preservation. More...

Macros
#define	CMD_DUMP_MEMORY
	UDP command sent to sync internal database with disc file. More...
#define	CMD_RESTORE_MEMORY
	UDP command sent to read the database on disc. More...
#define	CMD_SOURCE_DOWN
	Message sent when a source is no longer available. More...
#define	CMD_SOURCE_UP
	Message sent when a source is available. More...
#define	CMD_SYMBOL_DEL_PKTS
	Delete a symbol from the cache. More...
#define	CMD_SYMBOL_PUBLISH
	Republish a symbol to any interested peers. More...
#define	PACKET_FREE
	After processing, the ds_data_t should be freed. More...
#define	PACKET_NOFEEDTIME
	Do not update the last-update-time for this symbol. More...
#define	PACKET_NOLISTEN
	Indicate that this update should not be passed to modules. More...
#define	PACKET_OWRITE
	This update should be treated as an image. More...
#define	PACKET_PUBLISH
	This update should be (potentially) sent to interested peers. More...
#define	PACKET_STORE
	This update should be saved within the in-memory databse. More...
#define	PACKET_UPDATE
	An alias for PACKET_STORE. More...
#define	PROVIDER_DENY   -1
	Return value to indicate that the callback can't satisfy this request. More...
#define	PROVIDER_OK   0
	Return value to indicate that the callback can satisfy this request - data will follow. More...
#define	SYMBOL_NOLISTEN
	Indicate that the updates for the symbol should not be passed to modules. More...
#define	SYMBOL_NOSAVE
	Indicate that the symbol should not be saved to disc. More...
#define	SYMBOL_PUBLISH
	Automatically publish all updates for this symbol to peers. More...
#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_PROVIDEONCE
	A provider should only be called once to supply data. More...
#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 enum _authdirection	authdirection_t
	Define the mapping direction used for the authfuncs_t::map_object() call. More...
typedef int(*	provider_cb) (int peer, char *name, int isrequest)
	Definition of the function type used for provider callbacks. More...
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 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 struct _tfhandle	tf_handle_t
	Opaque handle for operations. 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_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...
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...
typedef void(*	udpcmd_t) (int argc, char *argv[])
	Definition of the function type used for udp command callbacks. More...
typedef void(*	update_cb) (int peer, ds_data_t *dsdata, time_t update_time, int val, void *data)
	Definition of the function type used for update callbacks. More...

Enumerations

Functions
TRANSFORMER_EXPORT void	auth_deregister_functions ()
	Disable the auth API. More...
TRANSFORMER_EXPORT void	auth_invalidate_peer_perms (int peernum)
	Invalidate permissions for an individual peer. More...
TRANSFORMER_EXPORT void	auth_invalidate_perms ()
	Invalidate permissions for all peers. More...
TRANSFORMER_EXPORT void	auth_register_functions (authfuncs_t *auth)
	Register a set of functions for handling auth capabilities. More...
TRANSFORMER_EXPORT int	deregister_interest (const char *name, update_cb update, int id, void *data)
	Deregister an interest in a particular group of symbols. More...
TRANSFORMER_EXPORT void	deregister_provider (const char *wildcard, provider_cb provider)
	Deregisters the data provider with the Transformer core for the specified object name pattern. The data provider will no longer be informed of any requests for objects with names that match the pattern. More...
TRANSFORMER_EXPORT int	deregister_type_interest (int typ, update_cb update, int id, void *data)
	Deregister an interest in a particular DataSource type. More...
TRANSFORMER_EXPORT void	deregister_userdata_funcs (unsigned int id)
	Deregister a set of functions that handled a specific id. More...
TRANSFORMER_EXPORT void	free_array (int argc, char *argv[])
	Frees a classical array of pointers to chars. More...
TRANSFORMER_EXPORT void	mod_config_parse_file (const char *file)
	Parse a mandatory module configuration file. More...
TRANSFORMER_EXPORT void	mod_config_parse_optional_file (const char *file)
	Parse an optional module configuration file. More...
TRANSFORMER_MODULE_EXPORT void	mod_init (char *module_name)
	Module initialisation function. More...
TRANSFORMER_EXPORT char *	mon_module_setup (const char *name, const char *description, const char *version)
	Function to allow modules to set up their monitoring strings. More...
TRANSFORMER_EXPORT ds_data_t *	packet_clone (ds_data_t *src)
	Duplicate a DataSource packet. More...
TRANSFORMER_EXPORT void	packet_contrib (ds_data_t *pkt, void *data, int storeflags)
	Contribute an update to the memory core/DataSource. More...
TRANSFORMER_EXPORT int	packet_delete_field (ds_data_t *pkt, int index)
	Remove a field in a dsdata. More...
TRANSFORMER_EXPORT char *	packet_get_field (ds_data_t *pkt, int fid)
	Find a field within a packet. More...
TRANSFORMER_EXPORT char *	packet_get_field_byname (ds_data_t *pkt, const char *field)
	Find a field within a packet. More...
TRANSFORMER_EXPORT void	packet_log_dump (ds_log_t *log, const char *label, ds_data_t *pkt)
	Write a ds_data_t to a log file in a human readable format. More...
TRANSFORMER_EXPORT int	packet_merge (ds_data_t *dest, ds_data_t *src, int *newfields)
	Merge the contents of one packet into the other. More...
TRANSFORMER_EXPORT int	packet_update (ds_data_t *dest, ds_data_t *src)
	Update the contents of one packet based on the contents of the other. More...
TRANSFORMER_EXPORT int	packet_update_field (ds_data_t *dest, int fid, const char *value)
	Update a field within a packet. More...
TRANSFORMER_EXPORT int	packet_update_field_byname (ds_data_t *dest, const char *field, const char *value)
	Update a field within a packet by name. More...
TRANSFORMER_EXPORT int	register_interest (const char *name, update_cb update, int id, void *data)
	Register an interest in a particular group of symbols. More...
TRANSFORMER_EXPORT int	register_interest_check (const char *name, update_cb update, int id, void *data)
	Register an interest in a particular group of symbols checking the provider if necessary. More...
TRANSFORMER_EXPORT void	register_provider (const char *wildcard, provider_cb provider)
	Registers the specified data provider with the Transformer core for the specified object name pattern. The data provider will be informed of any requests for objects with names that match the pattern. More...
TRANSFORMER_EXPORT int	register_type_interest (int typ, update_cb update, int id, void *data)
	Register an interest in a particular DataSource type. More...
TRANSFORMER_EXPORT void	register_userdata_funcs (userinfo_t *user)
	Register a set of functions to handle a specific id. More...
TRANSFORMER_EXPORT void	symbol_delete_all_mmaker (const char *name)
	Delete all the Type 2 data associated with a symbol. More...
TRANSFORMER_EXPORT void	symbol_delete_all_permission_keys (const char *name)
	Delete all the data associated with a permission object. More...
TRANSFORMER_EXPORT void	symbol_delete_mmaker (const char *symname, const char *mmaker)
	Delete the data associated with a type 2 index. More...
TRANSFORMER_EXPORT void	symbol_delete_permission_key (const char *name, const char *index)
	Delete the data associated with a permission key. More...
TRANSFORMER_EXPORT void	symbol_delete_type2 (const char *name, const char *index, int fieldnum)
	Delete the data associated with a type 2 index. More...
TRANSFORMER_EXPORT int	symbol_get_type (const char *objname)
	Return the type of a particular object. More...
TRANSFORMER_EXPORT void *	symbol_get_userdata (const char *name, unsigned int id)
	Retrieve module specific data for a given symbol and unique id. More...
TRANSFORMER_EXPORT char **	symbol_historic_field (const char *name, int fid, int *number)
	Get all data for a particular field number within a symbol. More...
TRANSFORMER_EXPORT char *	symbol_last_field (const char *name, int fid)
	Return the last received fieldvalue for a symbol. More...
TRANSFORMER_EXPORT char *	symbol_last_field_byname (const char *name, const char *field)
	Return the last recieved fieldvalue for a symbol. More...
TRANSFORMER_EXPORT ds_data_t *	symbol_last_mmaker_update (const char *name, const char *mmaker)
	Returns the currently cached Type 2 data for a symbol/Type 2 index. More...
TRANSFORMER_EXPORT ds_data_t *	symbol_last_permission_update (const char *name, const char *key)
	Returns the currently cached permission object data. More...
TRANSFORMER_EXPORT ds_data_t *	symbol_last_update (const char *name)
	Returns the currently cached Type 1 data for a symbol. More...
TRANSFORMER_EXPORT time_t	symbol_last_updatetime (const char *name)
	Return the time that the last update was received for this symbol. More...
TRANSFORMER_EXPORT char **	symbol_match (const char *name, int *num)
	Return a list of symbols matching the specifier. More...
TRANSFORMER_EXPORT char **	symbol_match_bytype (const char *name, int type, int *number)
	Return a list of symbols matching the pattern and of the specified type. More...
TRANSFORMER_EXPORT void	symbol_remove_alluserdata (const char *wildcard, unsigned int id, void(*dataremover)(void *data))
	Delete all userdata associated with a particular id for a group of symbols. More...
TRANSFORMER_EXPORT void	symbol_remove_userdata (const char *name, unsigned int id)
	Remove userdata for a given symbol and unique id. More...
TRANSFORMER_EXPORT char **	symbol_return_mmakers (const char *name, int *num)
	Returns a list of all the cached Type 2 market makers. More...
TRANSFORMER_EXPORT char **	symbol_return_permission_keys (const char *name, int *num)
	Returns a list of all the cached permission object keys. More...
TRANSFORMER_EXPORT void	symbol_send_nodata (const char *symname, u_short flags)
	Send a "nodata" message to the cache and to interested peers. More...
TRANSFORMER_EXPORT void	symbol_set_userdata (const char *name, unsigned int id, void *ptr)
	Register a piece of data against a particular symbol and unique id. More...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT ds5_namespace_t *	tf_create_globbed_namespace (const char *globbed)
	Creates a DataSource namespace which will match subject names using globbing. More...
TRANSFORMER_EXPORT ds5_namespace_t *	tf_create_regex_namespace (const char *expr)
	Creates a DataSource namespace which will match subject names using a regular expression. More...
TRANSFORMER_EXPORT void *	tf_find_function (const char *name)
	Lookup an extension function. More...
TRANSFORMER_EXPORT void	tf_handle_delete (tf_handle_t *handle)
	Delete a handle to a listener or a provider. More...
TRANSFORMER_EXPORT int	tf_handle_set_callback_params (tf_handle_t *handle, int id, void *data)
	Set the callback parameters on a handle. More...
TRANSFORMER_EXPORT int	tf_handle_set_discard_cb (tf_handle_t *handle, tf_discard_cb discard)
	Set the discard callback on a provider. More...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT int	tf_handle_set_nodata_cb (tf_handle_t *handle, tf_nodata_cb nodata)
	Set the nodata callback on a listener. More...
TRANSFORMER_EXPORT 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...
TRANSFORMER_EXPORT int	tf_handle_set_request_cb (tf_handle_t *handle, tf_request_cb request)
	Set the request callback on a provider. More...
TRANSFORMER_EXPORT int	tf_handle_set_status_cb (tf_handle_t *handle, tf_status_cb status)
	Set the status callback on a listener. More...
TRANSFORMER_EXPORT int	tf_handle_set_update_cb (tf_handle_t *handle, tf_update_cb update)
	Set the update callback on a listener. More...
TRANSFORMER_EXPORT int	tf_regex_namespace_add_expr (ds5_namespace_t *nspace, const char *expr, int exclude)
	Adds a regular expression to a namespace. More...
TRANSFORMER_EXPORT int	tf_register_function (const char *name, void *function)
	Register a new function against the extension system. More...
TRANSFORMER_EXPORT int	tf_symbol_get_status (const char *name, char **status_message_ptr)
	Return the status for an object within the cache. More...
TRANSFORMER_EXPORT int	tf_symbol_get_type (const char *objname)
	Return the type of a particular object. More...
TRANSFORMER_EXPORT char **	tf_symbol_match (const char *pattern, int *number)
	Return a list of symbols matching the specifier. More...
TRANSFORMER_EXPORT char **	tf_symbol_match_bytype (const char *pattern, int type, int *number)
	Return a list of symbols matching the pattern and of the specified type. More...
TRANSFORMER_EXPORT void	tf_symbol_send_status (const char *name, int status, const char *message)
	Send a status message for an object within the cache. More...

Variables
TRANSFORMER_EXPORT ds_log_t *	rtas_log
	Name of the Transformer's event log. More...

Detailed Description

Transformer API Definitions

Macro Definition Documentation

#define CMD_DUMP_MEMORY

UDP command sent to sync internal database with disc file.

This message may be sent by a module to force the Transformer to write its database to disc. The Transformer will be unreponsive to updates during the period that it is writing.

Example: Force database write

ds_udpsignal_send(CMD_DUMP_MEMORY)

#define CMD_RESTORE_MEMORY

UDP command sent to read the database on disc.

This message may be sent by a module to force the Transformer to read its database to disc. The Transformer will be unreponsive to updates during the period that it is writing.

The current in-memory cache will not be cleared prior to reading in the file, thus the result of this could be inconsitent.

Example: Force database read

ds_udpsignal_send(CMD_RESTORE_MEMORY)

#define SYMBOL_NOLISTEN

Indicate that the updates for the symbol should not be passed to modules.

This flag will prevent updates for this symbol being propogated through to any modules that may have registered any kind of interest in this symbol.

See also

PACKET_NOLISTEN

#define SYMBOL_NOSAVE

Indicate that the symbol should not be saved to disc.

This flag will prevent a symbol being written to the persistent database file (configuration option memory-file)

See also

symbol_create()

#define SYMBOL_PUBLISH

Automatically publish all updates for this symbol to peers.

This will force every update for this symbol to published to DataSource peers regardless of whether PACKET_PUBLISH has been specified for an individual update

See also

symbol_create()

Examples:

demo-modify.c.

Typedef Documentation

typedef struct _tfhandle tf_handle_t

Opaque handle for operations.

Function Documentation

TRANSFORMER_EXPORT void free_array	(	int	argc,
		char *	argv[]
	)

Frees a classical array of pointers to chars.

Frees an array of pointers such as that returned by symbol_match()

Parameters

argc	- Number of array members
argv	- Pointer to the array

TRANSFORMER_EXPORT char* mon_module_setup	(	const char *	name,
		const char *	description,
		const char *	version
	)

Function to allow modules to set up their monitoring strings.

TRANSFORMER_EXPORT void packet_log_dump	(	ds_log_t *	log,
		const char *	label,
		ds_data_t *	pkt
	)

Write a ds_data_t to a log file in a human readable format.

The log message is emitted at DEBUG level

Parameters

log	- Logfile to write the packet to
label	- Identifying label within the log file
pkt	- Packet to write to the logfile