Data Structures
struct	ds_arguments_t
	Structure defining the arguments for Monitoring methods. More...

struct	ds_array_t
	The container object for monitoring array types. More...

struct	ds_monauth_t
	Monitoring credentials object. More...

struct	ds_monitor_t
	The container object for all monitoring values. More...

Macros
#define	TYPE_ACTIVE 64
	Indicates whether the datatype is "active". More...

#define	TYPE_ACTIVE2 128
	Indicates whether the active type isn't a callback. More...

#define	TYPE_ARRAY 32
	Indicates whether the datatype is an array. More...

#define	TYPE_BINARY 1
	Binary property type. More...

#define	TYPE_BOOLEAN 11
	Boolean property type. More...

#define	TYPE_DOUBLE 9
	Double property type. More...

#define	TYPE_HIERARCHY 1024
	Indicates whether this data forms part of a heirarchy. More...

#define	TYPE_KEY 512
	Indicates whether this datatype forms part of the primary key. More...

#define	TYPE_LLONG 7
	Long long property type. More...

#define	TYPE_LONG 5
	Long property type. More...

#define	TYPE_METHOD 256
	Indicates whether this datatype is a method. More...

#define	TYPE_NONE 0
	A place marker. More...

#define	TYPE_OPTIONAL 2048

#define	TYPE_PRIMITIVE_MASK 31
	Mask to isolate the primitive data type. More...

#define	TYPE_RELATION 20
	Indicates that the property is a relation. More...

#define	TYPE_SHORT 3
	Short property type. More...

#define	TYPE_STRING 2
	String property type. More...

#define	TYPE_TIMESTAMP 10
	Timestamp property type. More...

#define	TYPE_ULLONG 8
	Unsigned long long property type. More...

#define	TYPE_ULONG 6
	Unsigned long property type. More...

#define	TYPE_USHORT 4
	Unsigned short property type. More...

Typedefs
typedef ds_monitor_t (	ds_monitor_active_cb) (char templatename, char key, char *propertyname)
	Definition of the function type used for active request callbacks. More...

typedef int(*	ds_monitor_authenticator_t) (ds_monauth_t *credentials)
	Definition of the function type used for monitoring authentication callback. More...

typedef ds_monitor_t (	ds_monitor_method_cb) (char templatename, char key, char property, int argc, char argv[])
	Definition of the function type used for method calls. More...

Functions
void	ds_monitor_add_data (ds_monitor_t data, const void datum)
	Add an element to an array within a ds_monitor_t. More...

void	ds_monitor_add_relation (const char templatename, const char key, const char propertyname, const char targetkey)
	Add a relationship between two groups. More...

void	ds_monitor_add_server_type (const char type, const char root)
	Define The Server Type. More...

void	ds_monitor_add_subscription (const char templatename, const char key, const char propertyname, const char value)
	Add a subscription between two groups. More...

void	ds_monitor_add_template_member (const char templatename, const char propertyname, const char description, int typeflags, ds_arguments_t args, void *ptr)
	Add a memeber to a template. More...

void	ds_monitor_add_template_relation (const char templatename, const char propertyname, const char targettemplate, const char description, int thisend, int thatend)
	Add a relationship to a template. More...

void	ds_monitor_add_template_subscription (const char templatename, const char propertyname, const char targettemplate, const char description, const char *singleton, ds_monitor_active_cb callback_fn)
	Add a subscription info into the template. More...

void	ds_monitor_create_group (const char templatename, const char key, const char brief, const char description)
	Create a new monitoring group. More...

void	ds_monitor_del_relation (const char templatename, const char key, const char propertyname, const char targetkey)
	Delete a relationship between two groups. More...

void	ds_monitor_del_subscription (const char templatename, const char key, const char propertyname, const char value)
	Delete a subscription between two groups. More...

void	ds_monitor_delete_group (const char templatename, const char key)
	Delete a group from the monitoring system. More...

void	ds_monitor_end_template (const char *templatename)
	End the definition of a template. More...

void	ds_monitor_free (ds_monitor_t *data)
	Deallocate memory used by a ds_monitor_t object. More...

void	ds_monitor_free_data (ds_monitor_t *data)
	Deallocate memory used by the contents of a ds_monitor_t object. More...

ds_monitor_t *	ds_monitor_new (const char propertyname, int type, int datasize, const void datum)
	Create a new ds_monitor_t object from input parameters. More...

ds_monitor_t *	ds_monitor_new_array (const char *propertyname, int type)
	Create a new ds_monitor_t of an array type. More...

ds_monitor_t *	ds_monitor_new_boolean (const char templatename, const char key, const char *propertyname, unsigned char value)
	Create a new ds_monitor_t object from an input boolean value. More...

ds_monitor_t *	ds_monitor_new_double (const char templatename, const char key, const char *propertyname, double value)
	Create a new ds_monitor_t object from an input double. More...

ds_monitor_t *	ds_monitor_new_llong (const char templatename, const char key, const char *propertyname, int64_t value)
	Create a new ds_monitor_t object from an input long long. More...

ds_monitor_t *	ds_monitor_new_long (const char templatename, const char key, const char *propertyname, int32_t value)
	Create a new ds_monitor_t object from an input long. More...

ds_monitor_t *	ds_monitor_new_short (const char templatename, const char key, const char *propertyname, int16_t value)
	Create a new ds_monitor_t object from an input short. More...

ds_monitor_t *	ds_monitor_new_string (const char templatename, const char key, const char propertyname, const char value)
	Create a new ds_monitor_t object from an input string. More...

ds_monitor_t *	ds_monitor_new_timestamp (const char templatename, const char key, const char *propertyname, int64_t value)
	Create a new ds_monitor_t object from an input timestamp. More...

ds_monitor_t *	ds_monitor_new_ullong (const char templatename, const char key, const char *propertyname, uint64_t value)
	Create a new ds_monitor_t object from an input unsigned long long. More...

ds_monitor_t *	ds_monitor_new_ulong (const char templatename, const char key, const char *propertyname, uint32_t value)
	Create a new ds_monitor_t object from an input unsigned long. More...

ds_monitor_t *	ds_monitor_new_ushort (const char templatename, const char key, const char *propertyname, uint16_t value)
	Create a new ds_monitor_t object from an input unsigned short. More...

ds_monitor_authenticator_t	ds_monitor_set_auth (ds_monitor_authenticator_t auth_cb)
	Register a new authentication handler. More...

void	ds_monitor_start_template (const char templatename, const char description)
	Start the defintion of a template. More...

void	ds_monitor_update (const char templatename, const char key, ds_monitor_t *monitor)
	Post an update to the monitoring system for a string value. More...

void	ds_monitor_update_boolean (const char templatename, const char key, const char *propertyname, unsigned char value)
	Post an update to the monitoring system for a boolean value. More...

void	ds_monitor_update_double (const char templatename, const char key, const char *propertyname, double value)
	Post an update to the monitoring system for a double value. More...

void	ds_monitor_update_llong (const char templatename, const char key, const char *propertyname, int64_t value)
	Post an update to the monitoring system for a long long value. More...

void	ds_monitor_update_long (const char templatename, const char key, const char *propertyname, int32_t value)
	Post an update to the monitoring system for a long value. More...

void	ds_monitor_update_short (const char templatename, const char key, const char *propertyname, int16_t value)
	Post an update to the monitoring system for a short value. More...

void	ds_monitor_update_string (const char templatename, const char key, const char propertyname, const char value)
	Post an update to the monitoring system for a string value. More...

void	ds_monitor_update_timestamp (const char templatename, const char key, const char *propertyname, int64_t value)
	Post an update to the monitoring system for a timestamp value. More...

void	ds_monitor_update_ullong (const char templatename, const char key, const char *propertyname, uint64_t value)
	Post an update to the monitoring system for an unsigned long long value. More...

void	ds_monitor_update_ulong (const char templatename, const char key, const char *propertyname, uint32_t value)
	Post an update to the monitoring system for an unsigned long value. More...

void	ds_monitor_update_ushort (const char templatename, const char key, const char *propertyname, uint16_t value)
	Post an update to the monitoring system for an unsigned short value. More...

Detailed Description

DSDK provides an abstracted monitoring API in order for applications to write to a single API without having to concern themselves with how the information is being used.

Key Concepts:

Properties are individual name/value pairs.
Templates are collections of properties.
Links provide a way of navigating between templates.

The monitoring API supports the following types:

Always on properties (which are always emitted by the application)
Request properties (which are generated on demand by the application)
Methods (which permit an operation to be performed)
Relations (which link to separate templates together)
Subscriptions (which construct a link between a template and a singleton template).

Properties can consist of the following datatypes:

Strings
Short integers (signed and unsigned)
Long integers (signed and unsigned)
Long long integers (signed and unsigned)
Floating point (doubles)
Booleans
Timestamps (milliseconds since 1 Jan 1970)
Arrays of the above datatypes

Setting the server type

Each DataSource component exposes a property on a well-defined name and containing well-defined property names that provide hints to any monitoring application what monitoring data and management features the application provides. These values can be controlled by the DataSource application by calling the ds_monitor_add_server_type() function.

The Caplin JMX monitoring console uses the values set by this function to load the appropriate display-templates for the application that it is connected to.

Defining the template

Monitoring and management items are grouped into templates consisting of information relating to a common object type, e.g. cache objects are associated with one type of template, datasource peers are associated with another.

A template declaration is begin with a call to ds_monitor_new_template(), items are added with ds_monitor_add_template_member() and a template declaration is ended with ds_monitor_end_template(). Ending the template definition will push the template definition to any monitoring plugin that has been loaded.

ds_monitor_start_template("datasrcname.object","Information about published objects");
ds_monitor_add_template_member("datasrcname.object","name","Name of the object",TYPE_STRING,NULL,NULL);
ds_monitor_add_template_member("datasrcname.object","last-update","Time of last update",TYPE_TIMESTAMP,NULL,NULL);
ds_monitor_end_template("datasrcname.object");

Creating Template Instances (groups)

A template definition needs to be instantiated and a monitorable group created for each item that is required to be monitored. For example, if an application wishes to provide monitorable information for a the objects that it is publishing, then it needs to call ds_monitor_create_group() for each individual object.

ds_monitor_create_group("datasrcname.object","/OBJECT1","Object info", "Monitorable information about /OBJECT1");

ds_monitor_create_group("datasrcname.object","/OBJECT2","Object info", "Monitorable information about /OBJECT2");

Deleting Groups

Groups should be deleted when no longer required, the function ds_monitor_delete_group() is provided for this purpose. All links should be removed prior to the deleting the group.

ds_monitor_delete_group("datasrcname.object","/OBJECT1");

Populating values

Initial values and subsequent updates should be published to the monitoring system using either the ds_monitor_update group of functions, or alternatively using the ds_monitor_new group of functions and the ds_monitor_update() function.

ds_monitor_update_timestamp("datasrcname.object","/OBJECT1", "last-update", (unsigned long long)time(NULL) * 1000);

or:

ds_monitor_t *mon;
mon = ds_monitor_new_timestamp("datasrcname.object","/OBJECT1", "last-update", (unsigned long long)time(NULL) * 1000);
ds_monitor_update("datasrcname.object","/OBJECT1", "last-update",mon);

Responding to requests for data

Method execution

The monitoring subsystem of DSDK permits management tools to affect the state of the DataSource, for example in the Caplin platform, methods are used to expose the following actions:

Force logfiles to wrap
Set the status of peer connections
Eject users from the Liberator
Cancel object subscriptions

Methods can take any number of arguments and return any type of data as a result.

Defining a method uses the ds_monitor_add_template_member() function. In order to indicate that a method is being added, the type type is or'd with TYPE_METHOD:

ds_monitor_add_template_member("datasrcname.object", "status", "Method to set object status",

TYPE_STRING|TYPE_METHOD, method_args, (void *) object_mon_status_cb);

The types of the arguments are defined using an array of ds_arguments_t. This array should be 0/NULL terminated as below:

static ds_arguments_t  method_args[] = {
    { TYPE_BOOL,  "status", "Object status (0 = stale)" },
    { TYPE_STRING|TYPE_OPTIONAL, "Status message", "Status message" },
    { 0, NULL, NULL }
};

Arguments can be specified as being optional in which case they do not need to be supplied by monitoring application. All arguments after the first optional argument should be marked as being optional.

Parameters are delivered the the DataSource application in the form of an array of strings. This permits implementation details to be shared between UDP events and management methods.

ds_monitor_t *object_mon_status_cb(char *template, char *key, char *methodname, int argc, argv[])
{
    /* argv[0] = methodname
     * argv[1] = object status
     * argv[2] = object status text
     */
}

Links

DSDK supports two sorts of links between objects, relations that bind templates together and subscriptions that bind templates together and implement a virtual group.

Relations

Relations are defined using the ds_monitor_add_template_relation() function. The multiplicity at each end can be set to either 0 (single) or 1 (many). For example a one to many relationship might be used to link all published objects to a single group containing statistical information about the objects the application is publishing (eg updates per seconds).

Relationships can be updated or removed using the ds_monitor_add_relation() and ds_monitor_del_relation() functions.

Subscriptions

Subscriptions are of use when the creation of an individual group for an item would result in a large number of groups being created. For example, subscriptions are used by the Liberator to obtain details of what objects a client is subscribed to. If we consider the case where a Liberator has a 1,000 clients each subscribing to 1,000 objects, if we were to create a group for each subscription then there would be 1,000,000 groups within the monitoring system which clearly isn't scalable.

Subscriptions are defined in the template using the ds_monitor_add_subscription() function, contents may be updated and removed using the ds_monitor_add_subscription() and ds_monitor_del_subscription() functions.

Macro Definition Documentation

#define TYPE_ACTIVE 64

Indicates whether the datatype is "active".

#define TYPE_ACTIVE2 128

Indicates whether the active type isn't a callback.

There are two forms of active monitoring types:

A function callback is supplied that provides that data
An address is supplied where the data can be obtained

If TYPE_ACTIVE2 then the same value is supplied for all groups of the template type

#define TYPE_ARRAY 32

Indicates whether the datatype is an array.

#define TYPE_BINARY 1

Binary property type.

#define TYPE_BOOLEAN 11

Boolean property type.

The Boolean value has the value 0 or 1

#define TYPE_DOUBLE 9

Double property type.

#define TYPE_HIERARCHY 1024

Indicates whether this data forms part of a heirarchy.

#define TYPE_KEY 512

Indicates whether this datatype forms part of the primary key.

#define TYPE_LLONG 7

Long long property type.

#define TYPE_LONG 5

Long property type.

#define TYPE_METHOD 256

Indicates whether this datatype is a method.

#define TYPE_NONE 0

A place marker.

#define TYPE_OPTIONAL 2048

For the type of the argument within a ds_arguments_t, this value can be or'd to indicate to the monitoring system that this argument is optional. All arguments after this particular argument should naturally be optional.

#define TYPE_PRIMITIVE_MASK 31

Mask to isolate the primitive data type.

#define TYPE_RELATION 20

Indicates that the property is a relation.

#define TYPE_SHORT 3

Short property type.

#define TYPE_STRING 2

String property type.

#define TYPE_TIMESTAMP 10

Timestamp property type.

The timestamp should be supplied in milliseconds

#define TYPE_ULLONG 8

Unsigned long long property type.

#define TYPE_ULONG 6

Unsigned long property type.

#define TYPE_USHORT 4

Unsigned short property type.

Typedef Documentation

typedef ds_monitor_t*(* ds_monitor_active_cb) (char *templatename, char *key, char *propertyname)

Definition of the function type used for active request callbacks.

Parameters

templatename	The templatename of the property being requested
key	The primarykey of the property being requested
propertyname	The propertyname being requested

Returns: ds_monitor_t A populated ds_monitor_t object

typedef int(* ds_monitor_authenticator_t) (ds_monauth_t *credentials)

Definition of the function type used for monitoring authentication callback.

Parameters

credentials User credentials to be authenticated

Return values

0	- User is not permitted to connect
1	- User is permitted to connect

See also: ds_monitor_set_auth()

typedef ds_monitor_t*(* ds_monitor_method_cb) (char *templatename, char *key, char *property, int argc, char *argv[])

Definition of the function type used for method calls.

Parameters

templatename	The templatename of the method being called
key	The primarykey of the method being called
propertyname	The propertyname of the method being requested
argc	Number of arguments
argv	Array of arguments

Returns: ds_monitor_t A populated ds_monitor_t object

argv[0] contains the propertyname this method is being called for

Function Documentation

void ds_monitor_add_data	(	ds_monitor_t *	data,
		const void *	datum
	)

Add an element to an array within a ds_monitor_t.

Parameters

data	The ds_monitor_t container
datum	The data to be added

This function treats the data added as the type specified by the initial data_new_array call

void ds_monitor_add_relation	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		const char *	targetkey
	)

Add a relationship between two groups.

Parameters

templatename	Templatename of "this" end of the relationship
key	Primarykey of "this" end of the relationship
propertyname	Name the property at "this" end of the relationship
targetkey	Primarykey of the group at "that" end

A relationship is defined by ds_monitor_add_template_relation() which defines the templatename of "that" end, hence it does not need to be specified here.

This flexibility facilitates the relationship between unrelated group such that they do not need to know the contents of each other

void ds_monitor_add_server_type	(	const char *	type,
		const char *	root
	)

Define The Server Type.

Parameters

type	Type name of this application
root	The root name of monitoring objects

The type name indicates the type of the server that this program is. For example, Caplin products identify themselves as 'liberator', 'transformer', 'demosrc' etc. This is used to provide a hint to the console as to which templates should be used to display the monitoring data.

The root defaults to the application-name, eg 'rttpd' and is the prefix for all monitoring objects in the system.

By default, type is 'datasrc' and 'root' is given by the configuration option application-name.

void ds_monitor_add_subscription	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		const char *	value
	)

Add a subscription between two groups.

Parameters

templatename	Templatename of "this" end of the subscription
key	Primarykey of "this" end of the subscription
propertyname	Name the property at "this" end of the subscription
value	Value of the subscription

A subscription is defined by ds_monitor_add_template_subscription()

The value that is added is in triplet form:

Singleton Value!Key At remote end[!Display name]
 *

Where the display name is optional.

Note: Subscriptions are specialised optimisation of relations, it is improbably that they would need to be used in a datasource application.

void ds_monitor_add_template_member	(	const char *	templatename,
		const char *	propertyname,
		const char *	description,
		int	typeflags,
		ds_arguments_t *	args,
		void *	ptr
	)

Add a memeber to a template.

Parameters

templatename
propertyname
description	Description/doc string
typeflags
args	A list of arguments (For methods)
ptr	Callback for active or methods. Or address of data for ACTIVE2 things

void ds_monitor_add_template_relation	(	const char *	templatename,
		const char *	propertyname,
		const char *	targettemplate,
		const char *	description,
		int	thisend,
		int	thatend
	)

Add a relationship to a template.

Parameters

templatename
propertyname
targettemplate	The template at the other end of a relationship
description	A description of this relationship
thisend	The multiplicity at this of the relationship
thatend	The multiplicity at the other end of the relationship

void ds_monitor_add_template_subscription	(	const char *	templatename,
		const char *	propertyname,
		const char *	targettemplate,
		const char *	description,
		const char *	singleton,
		ds_monitor_active_cb	callback_fn
	)

Add a subscription info into the template.

Parameters

templatename
propertyname
targettemplate	The template at the other end of this subscription
description	A description of this relationship
singleton	The template used for operations of this subscription
callback_fn	The callback function

A subscription implements a virtual-group within the monitoring system. The virtual-group is of the type singleton.

The singleton template should only expose methods which can be used to obtain the values. This means that monitorable values on the template can not automatically update.

The parameter callback_fn is used by the monitoring system to obtain a list of all elements of the subscription. For reasons of performance and resource conservation, the monitoring subsystem cannot/should not cache any published information.

A call to ds_monitor_add_template_subscription() on templatename should be accompanied by a call on targettemplate.

See also: ds_monitor_add_subscription(); ds_monitor_del_subscription()

void ds_monitor_create_group	(	const char *	templatename,
		const char *	key,
		const char *	brief,
		const char *	description
	)

Create a new monitoring group.

Parameters

templatename	Template name to be used for this group
key	The primary key
brief	The prettyname for this group
description	A longer description

The pretty name will be presented by the JMX console in tree view mode. The longer description will be presented as "mouseover" text

void ds_monitor_del_relation	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		const char *	targetkey
	)

Delete a relationship between two groups.

Parameters

templatename	Templatename of "this" end of the relationship
key	Primarykey of "this" end of the relationship
propertyname	Name the property at "this" end of the relationship
targetkey	Primarykey of the group at "that" end

void ds_monitor_del_subscription	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		const char *	value
	)

Delete a subscription between two groups.

Parameters

templatename	Templatename of "this" end of the subscription
key	Primarykey of "this" end of the subscription
propertyname	Name the property at "this" end of the subscription
value	Value of the subscription

void ds_monitor_delete_group	(	const char *	templatename,
		const char *	key
	)

Delete a group from the monitoring system.

Parameters

templatename
key

void ds_monitor_end_template ( const char * templatename )

End the definition of a template.

Parameters

templatename This sends a notification to the module to do whatever it likes with the definition. It should be called whenever a template definition has reached its end.

void ds_monitor_free ( ds_monitor_t * data )

Deallocate memory used by a ds_monitor_t object.

Parameters

data	The ds_monitor_t object

This function is most likely to be used by a monitoring module

void ds_monitor_free_data ( ds_monitor_t * data )

Deallocate memory used by the contents of a ds_monitor_t object.

Parameters

data	The ds_monitor_t object

This function frees the contents of the ds_monitor_t, it does not deallocate the base ds_monitor_t

This function is most likely to be used by a monitoring module

ds_monitor_t* ds_monitor_new	(	const char *	propertyname,
		int	type,
		int	datasize,
		const void *	datum
	)

Create a new ds_monitor_t object from input parameters.

Parameters

propertyname	Name of the property
type	Datatype that the data is
datasize	Number of elements in array/size of binary data
datum	(sic) The data to be stored within the ds_monitor_t entry

Returns: a ds_monitor_t that can be used as one wishes

This function makes a copy of all the input data and as such the originating data can be disposed of.

ds_monitor_t* ds_monitor_new_array	(	const char *	propertyname,
		int	type
	)

Create a new ds_monitor_t of an array type.

Parameters

propertyname	The name of the property this ds_monitor_t is being created for
type	The fundamental type

Returns: ds_monitor_t The ds_monitor_t container

ds_monitor_t* ds_monitor_new_boolean	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		unsigned char	value
	)

Create a new ds_monitor_t object from an input boolean value.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The value to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_double	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		double	value
	)

Create a new ds_monitor_t object from an input double.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The double to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_llong	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		int64_t	value
	)

Create a new ds_monitor_t object from an input long long.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The long long to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_long	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		int32_t	value
	)

Create a new ds_monitor_t object from an input long.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The long to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_short	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		int16_t	value
	)

Create a new ds_monitor_t object from an input short.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The short to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_string	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		const char *	value
	)

Create a new ds_monitor_t object from an input string.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The string to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function makes a copy of all the input string.

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_timestamp	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		int64_t	value
	)

Create a new ds_monitor_t object from an input timestamp.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The long long to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_ullong	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		uint64_t	value
	)

Create a new ds_monitor_t object from an input unsigned long long.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The unsigned long long to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_ulong	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		uint32_t	value
	)

Create a new ds_monitor_t object from an input unsigned long.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The unsigned long to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_t* ds_monitor_new_ushort	(	const char *	templatename,
		const char *	key,
		const char *	propertyname,
		uint16_t	value
	)

Create a new ds_monitor_t object from an input unsigned short.

Parameters

templatename
key
propertyname	Property that this ds_monitor_t is being created for
value	The unsigned short to populate the ds_monitor_t with

Returns: a ds_monitor_t that can be used as one wishes

This function wraps up ds_monitor_new() and is provided for convience

ds_monitor_authenticator_t ds_monitor_set_auth ( ds_monitor_authenticator_t auth_cb )

Register a new authentication handler.

Parameters

auth_cb The authentication routine to use

Returns: The previous authentication routine

A datasrc application may register a function to perform basic authentication on an incoming monitoring connection. This will override the inbuilt authentication mechanism (add-monuser) and provides the application with a greater degree of control

void ds_monitor_start_template	(	const char *	templatename,
		const char *	description
	)

Start the defintion of a template.

Parameters

templatename	Name of the template
description	Description used for documentation purposes

Note: Does not check to see if template already exists

void ds_monitor_update	(	const char *	templatename,
		const char *	key,
		ds_monitor_t *	monitor
	)

Post an update to the monitoring system for a string value.

Parameters

templatename
key
monitor	A populated ds_monitor_t object

A ds_monitor_t object can be creating using the ds_monitor_new() group of functions.