API for creating server objects

Defines
#define	UV_LOGICAL   0
	logical
#define	UV_BYTE   1
	byte
#define	UV_INTEGER   2
	integer
#define	UV_LONG   3
	long
#define	UV_DOUBLE   4
	double
#define	UV_STRING   5
	string
#define	UV_LOGICAL_VECTOR   6
	vector of logical
#define	UV_BYTE_VECTOR   7
	vector of byte
#define	UV_INTEGER_VECTOR   8
	vector of integer
#define	UV_LONG_VECTOR   9
	vector of long
#define	UV_DOUBLE_VECTOR   10
	vector of double
#define	UV_STRING_VECTOR   11
	vector of string
#define	UV_OBJECT   12
	file has a object value
#define	UV_READONLY   0x01
	the file is readonly
#define	UV_READWRITE   0x02
	the file is readwrite
#define	UV_MUTABLE   0x04
	the file value is mutable i.e. it can be subscribed for
#define	UV_ROOT   0
	folder id of the root folder
Typedefs
typedef unsigned int	uv_folder_t
typedef unsigned int	uv_queue_t
typedef unsigned int	uv_mount_t
typedef unsigned int	uv_file_t
typedef unsigned int	uv_value_t
typedef void *	UV_VALUE
typedef int(*)	UV_CHANGE_CB (char *adr, int type, UV_VALUE val, int cnt, void *userarg)
typedef int(*)	UV_ADD_CB (char *path, char *filename)
typedef int(*)	UV_RM_CB (char *fileadr)
typedef int(*)	UV_FILE_CB (char *filepath, uv_file_t file, void *userarg)
Enumerations
enum	uv_loglevel_e {   UV_LOG = 0x01, UV_ERROR = 0x02, UV_INFO = 0x04, UV_DEBUG = 0x08,   UV_TIMER = 0x10, UV_TREE = 0x20 }
	log level
Functions
int	uv_init (char *mive, UV_CHANGE_CB cb)
int	uv_set_structure_cbs (UV_ADD_CB add_cb, UV_RM_CB rm_cb)
int	uv_burst_delay (int ms)
int	uv_online (void)
int	uv_offline (void)
int	uv_tree (char *path, char *fn, uv_folder_t folder_id)
uv_folder_t	uv_folder_new (char *mive, int major, int minor)
int	uv_folder_free (uv_folder_t folder_id)
uv_queue_t	uv_queue_new (char *mive, int major, int minor)
uv_mount_t	uv_mount_ip_new (char *host, int port, char *filepath)
uv_mount_t	uv_mount_name_new (char *service_name, char *filepath)
int	uv_file_new (uv_folder_t folder_id, char *name, int mode, char *description, int type, void *val, int cnt, void *userarg)
int	uv_file_add (char *foldername, char *filename, int mode, char *description, int type, UV_VALUE pval, int cnt, void *userarg)
int	uv_file_rm (char *filepath)
int	uv_queue_push (char *queuepath, char *name, char *description, int type, void *val, int cnt)
int	uv_file_set_arg (char *filepath, void *arg)
int	uv_file_set (char *filepath, int idx, int type, UV_VALUE val)
int	uv_file_val (char *filepath, int type, UV_VALUE val, int count)
int	uv_file_set_logical (char *adr, unsigned char *pval)
	wrapper function of uv_file_set for logicals
int	uv_file_set_byte (char *adr, char *pval)
	wrapper function of uv_file_set for byte
int	uv_file_set_int (char *adr, int *pval)
	wrapper function of uv_file_set for integer
int	uv_file_set_long (char *adr, long long int *pval)
	wrapper function of uv_file_set for long long
int	uv_file_set_double (char *adr, double *pval)
	wrapper function of uv_file_set for double
int	uv_file_set_string (char *adr, char *pval)
	wrapper function of uv_file_set for string
int	uv_file_set_logical_vector (char *adr, int idx, unsigned char *pval)
	wrapper function of uv_file_set for vector of logical
int	uv_file_set_byte_vector (char *adr, int idx, char *pval)
	wrapper function of uv_file_set for vector of byte
int	uv_file_set_int_vector (char *adr, int idx, int *pval)
	wrapper function of uv_file_set for vector of integer
int	uv_file_set_long_vector (char *adr, int idx, long long int *pval)
	wrapper function of uv_file_set for vector of long long
int	uv_file_set_double_vector (char *adr, int idx, double *pval)
	wrapper function of uv_file_set for vector of double
int	uv_file_set_string_vector (char *adr, int idx, char *pval)
	wrapper function of uv_file_set for vector of string
int	uv_traverse (uv_file_t root_folder, char *anchor, UV_FILE_CB cb, void *userarg)
int	uv_read_fs (char *fsrootpath)
uv_folder_t	uv_value_root (void)
uv_file_t	uv_value_root_file (void)

---

Detailed Description

This API contains the functionality to set up an uv server. You construct a file system like tree structure of values. Changes of the value tree resulting from client write commands are distributed by a change callback to the API caller. Vice versa, setting of the values locally in the server will result in messaging to subscribed clients.

---

Define Documentation

#define UV_LOGICAL   0

logical

file value types this corresponds to xvalue.xml union members, so keep it compatible

#define UV_READONLY   0x01

the file is readonly

file modes

---

Typedef Documentation

typedef int(*) UV_ADD_CB(char *path, char *filename)

callback function which is called when file is added externally by some client

Parameters:

	path	the parentfolder of the added file as string
	filename

typedef int(*) UV_CHANGE_CB(char *adr, int type, UV_VALUE val, int cnt, void *userarg)

callback function which is called when file value is changed externally by some client

Parameters:

	adr	the adress of the changed value as string
	type	the value type
	val	pointer to value
	cnt	in case of vector value this is the number of elements
	userarg	argument supplied by user during creation of the file

typedef int(*) UV_FILE_CB(char *filepath, uv_file_t file, void *userarg)

callback function which is called during tree traversal

Parameters:

	filepath	path of the file object
	file	file object
	userarg	user supplied data

typedef int(*) UV_RM_CB(char *fileadr)

callback function which is called when file is removed externally by some client

Parameters:

fileadr

the adress of the removed file as string

---

Function Documentation

int uv_burst_delay

(

int

ms

)

set burst mode time delay, default is 250 ms

Parameters:

ms

time delay between triggering and flushing of output queue 10 <= ms <= 1000

Returns:

• 0: OK
• else: Error

int uv_file_add	(	char *	foldername,
		char *	filename,
		int	mode,
		char *	description,
		int	type,
		UV_VALUE	pval,
		int	cnt,
		void *	userarg
	)

add a file to a folder (folder has to exist) and send a structurechange notification to all subscribers of the folder

Parameters:

	foldername	name of the folder the file is created in
	name	name of the file (path not(!) included)
	mode	read/write/mutable
	type	the type of the file (byte,int,double,...)
	val	pointer to filevalue (if the filevalue is a folder, the value is the folder_id)
	cnt	number of elements in case of an vector
	userarg	callback due to client-write is called with this argument see UV_CHANGE_CB

Returns:

• 0: OK
• else: Error

int uv_file_new	(	uv_folder_t	folder_id,
		char *	name,
		int	mode,
		char *	description,
		int	type,
		void *	val,
		int	cnt,
		void *	userarg
	)

Create a file in a folder (the value may be a folder). The creation has to be done before server communication starts. All provided information is copied.

Parameters:

	folder_id	id of the folder the file shall be created in (returned by uv_folder_new())
	name	name of the file (path not included)
	mode	read/write/mutable
	description	character string information to describe this file
	type	the type of the file (byte,int,double,...)
	val	pointer to filevalue (if the filevalue is a folder, the filevalue is the folder_id returned by uv_folder_new())
	cnt	number of elements in case of vectorvalue
	userarg	callback due to client-write is called with this argument see UV_CHANGE_CB

Returns:

• 0: OK
• else: Error

int uv_file_rm

(

char *

filepath

)

remove file recursively (if file is folder, all files and folders beyond will be removed too). A structure change notification is send to any subscriber of parent folder

Parameters:

filepath

absolute path name of file to remove

Returns:

• 0: OK
• else: Error

int uv_file_set	(	char *	filepath,
		int	idx,
		int	type,
		UV_VALUE	val
	)

set local value of a scalar data object or an array-member Any subscriber (client) of the object will be informed about value change

Parameters:

	filepath	name of data object
	idx	if filevalue is array, this is the index
	type	the type of filevalue
	val	pointer to value to set

Returns:

• 0: OK
• else: Error

int uv_file_set_arg	(	char *	filepath,
		void *	arg
	)

set callers argument

Parameters:

	filepath	name of data object
	userarg	callback due to client-write is called with this argument

Returns:

• 0: OK
• else: Error

int uv_file_val	(	char *	filepath,
		int	type,
		UV_VALUE	val,
		int	count
	)

replace local value of a data object (arrays are completely replaced). Any subscriber (client) of the object will be informed about value change

Parameters:

	filepath	name of data object
	type	the type of value, it must fit to the file's value type
	val	pointer to value to set (for arrays this must be a dynamically allocated array to the data)
	count	if filevalue is array, this is the array count

Returns:

• 0: OK
• else: Error

int uv_folder_free

(

uv_folder_t

folder_id

)

free the memory of a folder which has never been inserted to the root tree e.g. to put to a queue and was created with uv_folder_new()

Parameters:

folder_id

folder which is freed

Returns:

• 0: OK
• else: Error

uv_folder_t uv_folder_new	(	char *	mive,
		int	major,
		int	minor
	)

create a data object container i.e. folder

Parameters:

	mive	the "multipurpose internet value type" of the folder to create (maybe empty ""), it defines just a tagname for the structure (type) of the folder
	major	version major
	minor	version minor

Returns:

• >0: Folder ID
• else: Error

int uv_init	(	char *	mive,
		UV_CHANGE_CB	cb
	)

inits the internal structures

Parameters:

	mive	the "multipurpose internet value type" of this servers tree structure to create (maybe empty ""), it defines a tag for the structure (type) of the root folder or service
	cb	callback is called when value data is changed externally

Returns:

• 0: OK
• else: Error

uv_mount_t uv_mount_ip_new	(	char *	host,
		int	port,
		char *	filepath
	)

Creates a mount object, the information how to reach a subtree of another server is given by hostname/IP-address and port.

Parameters:

	host	internet host of server
	port	port number of server
	filepath	absolute path to subtree on remote server

Returns:

• >0: mount id
• else: Error

uv_mount_t uv_mount_name_new	(	char *	service_name,
		char *	filepath
	)

Creates a mount object, information how to reach a subtree of another server is given by name

Parameters:

	service_name	name of the service
	filepath	absolute path to subtree on remote server

Returns:

• >0: mount id
• else: Error

int uv_offline

(

void

)

set service offline, disable communication with clients

Returns:

• 0: OK
• else: Error

int uv_online

(

void

)

set service online, enable communication with clients

Returns:

• 0: OK
• else: Error

uv_queue_t uv_queue_new	(	char *	mive,
		int	major,
		int	minor
	)

Creates a data object sink, i.e. queue (first in first out). File objects added to this container are immediately send to subscribers.

Parameters:

	mive	"multipurpose internet value type" of queue to create (maybe empty "")
	major	version major
	minor	version minor

Returns:

• >0: Fifo ID
• else: Error

int uv_queue_push	(	char *	queuepath,
		char *	name,
		char *	description,
		int	type,
		void *	val,
		int	cnt
	)

push a file in queue. The file is sent to any subscriber of the queue, the files value may be a folder.

Parameters:

	filepath	absolute path name of queue
	name	name of the file to put to queue (path not included)
	type	the type of the file (byte,int,double,...)
	val	pointer to filevalue (if the filevalue is a folder, the value is the folder_id)
	cnt	number of elements in case of an vector

Returns:

• 0: OK
• else: Error

int uv_read_fs

(

char *

fsrootpath

)

Reads uv file values from file system

Parameters:

fsrootpath

file system entry point uv file values are searched in

Returns:

• 0: OK
• else: Error

int uv_set_structure_cbs	(	UV_ADD_CB	add_cb,
		UV_RM_CB	rm_cb
	)

sets the callbacks to be called for external structure change requests (file adding or removing)

Parameters:

	add_cb	callback is called when file is added externally
	rm_cb	callback is called when file is remooved externally

Returns:

• 0: OK
• else: Error

int uv_traverse	(	uv_file_t	root_folder,
		char *	anchor,
		UV_FILE_CB	cb,
		void *	userarg
	)

Traverse a uv-tree and call callback with path and file

Parameters:

	proot	start point of traversal (if NULL, uv-root is taken)
	anchor	uv-pathname of start point (if NULL, "/" is taken)
	cb	callback function which is called for each file object and userag
	userarg	user argument to call callback with

Returns:

• 0: OK
• else: Error

int uv_tree	(	char *	path,
		char *	fn,
		uv_folder_t	folder_id
	)

reads server structure from a file in filesystem and adds it to folder

Parameters:

	path	path to file on filesystem containing structure information
	fn	name of file on filesystem containing structure information
	folder_id	uv folder to which the structure will be added

Returns:

• 0: OK
• <0: Error

uv_folder_t uv_value_root

(

void

)

get root folder handle

Returns:

root folder id

uv_file_t uv_value_root_file

(

void

)

get root file handle

Returns:

root file id

---