PSI sics-cvs-psi-2008-10-02
This commit is contained in:
Douglas Clowes
431
sicshipadaba.h
Normal file
431
sicshipadaba.h
Normal file
@@ -0,0 +1,431 @@
|
||||
/** @file
|
||||
* This is a set of helper functions for SICS to work with the hierarchical parameter
|
||||
* database hipadaba. In SICS, the calldata associated with any callback will always
|
||||
* be the connection object.
|
||||
*
|
||||
* copyright: GPL
|
||||
*
|
||||
* Mark Koennecke, June 2006
|
||||
*/
|
||||
#ifndef SICSHIPADABA_H_
|
||||
#define SICSHIPADABA_H_
|
||||
#include <hipadaba.h>
|
||||
#include <sics.h>
|
||||
#include <dynstring.h>
|
||||
#include <sicsobj.h>
|
||||
/*======================== callback error codes ===============================*/
|
||||
#define SICSCBRO -607
|
||||
#define SICSCBPERM -608
|
||||
#define SICSCBRANGE -609
|
||||
#define SICSCBBADFIXED -610
|
||||
#define SICSNOPAR -611
|
||||
/*======================== SICS Messages ======================================*/
|
||||
typedef struct {
|
||||
char *type;
|
||||
int ID;
|
||||
}hdbIDMessage, *pHdbIDMessage;
|
||||
/*------------------------------------------------------------------------------*/
|
||||
pHdbIDMessage GetKillIDMessage(pHdbMessage message);
|
||||
pHdbIDMessage GetKillInternalIDMessage(pHdbMessage message);
|
||||
/*-----------------------------------------------------------------------------*/
|
||||
typedef struct {
|
||||
char *type;
|
||||
void *pPtr;
|
||||
}hdbPtrMessage, *pHdbPtrMessage;
|
||||
/*-----------------------------------------------------------------------------*/
|
||||
pHdbPtrMessage GetKillPtrMessage(pHdbMessage message);
|
||||
/*======================== data structure for automatic parameter update =======*/
|
||||
typedef struct {
|
||||
SConnection *pCon;
|
||||
int updateList;
|
||||
int iEnd;
|
||||
}hdbUpdateTask, *pHdbUpdateTask;
|
||||
/*======================== common callbacks =====================================*/
|
||||
/**
|
||||
* make a ReadOnly callback
|
||||
* @return a callback which disallows setting of a parameter.
|
||||
*/
|
||||
pHdbCallback MakeReadOnlyCallback();
|
||||
/**
|
||||
* make a callback which checks permissions. To be used on write
|
||||
* @param priv The privilege to check against
|
||||
* @return a suitably initialized callback structure for
|
||||
* checking permissions.
|
||||
*/
|
||||
pHdbCallback MakeCheckPermissionCallback(int priv);
|
||||
/**
|
||||
* make a callback which directly updates a
|
||||
* paramter after setting. Useful for program parameters.
|
||||
* @return a suitably initialized callback structure setting
|
||||
* program parameters
|
||||
*/
|
||||
pHdbCallback MakeSetUpdateCallback();
|
||||
/**
|
||||
* Remove a SetUpdate callback. This is useful for chaning the
|
||||
* behaviour of a node created with the hmake command
|
||||
* @param node the node
|
||||
*/
|
||||
void RemoveSetUpdateCallback(pHdb node);
|
||||
/**
|
||||
* make a callback which starts a parameter driving.
|
||||
* @param sicsObject The SICS object to drive.
|
||||
* @return a suitably initialized callback structure for
|
||||
* starting a parameter driving.
|
||||
*/
|
||||
pHdbCallback MakeSICSDriveCallback(void *sicsObject);
|
||||
/**
|
||||
* make a callback which reads a SICS drivable object
|
||||
* @param sicsObject The SICS drivable object to read.
|
||||
* @return a suitably initialized callback structure for
|
||||
* reading a drivable parameter
|
||||
*/
|
||||
pHdbCallback MakeSICSReadDriveCallback(void *sicsObject);
|
||||
/**
|
||||
* make a callback which enables automatically
|
||||
* notification of pCon on parameter updates.
|
||||
* @param pCon The connection to notify. The notification
|
||||
* is issued in the context of this connection.
|
||||
* @param id An integer id which can later on be used to remove the
|
||||
* callback.
|
||||
* @return a suitably initialized callback structure for
|
||||
* automatic notification.
|
||||
*/
|
||||
pHdbCallback MakeNotifyCallback(SConnection *pCon, int id);
|
||||
/**
|
||||
* make a callback for checking if a parameter is within a given
|
||||
* range of integers
|
||||
* @param min The minimum value of the range
|
||||
* @param max The maximum value of the range
|
||||
* @return a suitably configured callback or NULL
|
||||
* when out of memory
|
||||
*/
|
||||
pHdbCallback MakeIntRangeCallback(int min, int max);
|
||||
/**
|
||||
* make a callback for checking if a parameter is one out
|
||||
* of a series of permitted integers
|
||||
* @param data An array of permitted integers
|
||||
* @param length The length of the data array.
|
||||
* @return a suitably configured callback or NULL
|
||||
* when out of memory
|
||||
*/
|
||||
pHdbCallback MakeIntFixedCallback(int *data, int length);
|
||||
/**
|
||||
* make a callback for checking if a parameter is within a given
|
||||
* range of floats
|
||||
* @param min The minimum value of the range
|
||||
* @param max The maximum value of the range
|
||||
* @return a suitably configured callback or NULL
|
||||
* when out of memory
|
||||
*/
|
||||
pHdbCallback MakeFloatRangeCallback(double min, double max);
|
||||
/**
|
||||
* make a callback which reads a memory address (perhaps in a
|
||||
* data structure) which is a float value
|
||||
* @param address The address of the parameter
|
||||
* @return a suitable callback for reading this parameter.
|
||||
*/
|
||||
pHdbCallback MakeMemReadCallback(float *address);
|
||||
/**
|
||||
* make a callback which sets a memory address (perhaps in a
|
||||
* data structure) which is a float value. It is assumed that
|
||||
* this is a direct parameter, i.e, UpdateHipadabaPar is
|
||||
* automatically called.
|
||||
* @param address The address of the parameter
|
||||
* @return a suitable callback for setting this parameter.
|
||||
*/
|
||||
pHdbCallback MakeMemSetCallback(float *address);
|
||||
/**
|
||||
* make a tree chnage callback
|
||||
* @param pCon The connection to notfy on tree chnages
|
||||
* @param id The ID of this callback
|
||||
* @return a suitable callback for notififications about tree changes.
|
||||
*/
|
||||
pHdbCallback MakeTreeChangeCallback(SConnection *pCon, int id);
|
||||
/**
|
||||
* make a clalback to invoke a function node
|
||||
*/
|
||||
pHdbCallback MakeSICSFuncCallback(void *obj);
|
||||
|
||||
/*======================== parameter creation ===================================*/
|
||||
/**
|
||||
* make a simple SICS hdb parameter. Setting it will call update immediately. Use
|
||||
* this for program parameters.
|
||||
* @param name The name of the parameter
|
||||
* @param priv The privilege required to change that parameter
|
||||
* @param v The initial value and datatype of this parameter
|
||||
* @return A new suitably configured Hdb parameter or NULL when out of memory.
|
||||
*/
|
||||
pHdb MakeSICSHdbPar(char *name, int priv, hdbValue v);
|
||||
/**
|
||||
* make a SICS hdb drivable parameter. Setting it will start the motor,
|
||||
* virtual motor or environment parameter. This will call StartDevice
|
||||
* eventually
|
||||
* @param name The name of the parameter
|
||||
* @param priv The privilege required to change that parameter
|
||||
* @param sicsObject The object corresponding to this parameter.
|
||||
* @param datatype The datatype of this variable
|
||||
* @return A new suitably configured Hdb parameter or NULL when out of memory.
|
||||
*/
|
||||
pHdb MakeSICSHdbDriv(char *name, int priv,void *sicsObject, int datatype);
|
||||
/**
|
||||
* make SICS hdb variable which is connected to a memory location, perhaps in
|
||||
* an objects data structure.
|
||||
* @param name The name of the variable
|
||||
* @param priv The privilege required to set this parameter
|
||||
* @param address A pointer to the memory location of the variable.
|
||||
*/
|
||||
pHdb MakeSICSMemPar(char *name, int priv, float *address);
|
||||
/**
|
||||
* makes a SICS Hdb read only parameter. Setting such a parameter causes an error.
|
||||
* @param name The name of the parameter
|
||||
* @param v The initial value and datatype of this parameter
|
||||
* @return A new suitably configured Hdb parameter or NULL when out of memory.
|
||||
*/
|
||||
pHdb MakeSICSROPar(char *name, hdbValue v);
|
||||
/**
|
||||
* make a SICS scriptable parameter. I.e. when this parameter is set or read,
|
||||
* appropriate scripts are invoked.
|
||||
* @param name The name of the parameter
|
||||
* @param setScript The script to call when this parameter is being set
|
||||
* @param readScript The script to call when this parameter is being read.
|
||||
* @param v The initial value and datatype of this parameter
|
||||
* @return A new suitably configured Hdb parameter or NULL when out of memory.
|
||||
*/
|
||||
pHdb MakeSICSScriptPar(char *name, char *setScript, char *readScript, hdbValue v);
|
||||
|
||||
/**
|
||||
* remove a SICS paramameter node and its children. In contrast to the
|
||||
* normal DeletHipadabaNode, this function also takes care of
|
||||
* clearing scipted nodes out of the update tasks watch list.
|
||||
* @param node The node to delete
|
||||
* @param callData User data for the tree change callback
|
||||
*/
|
||||
void RemoveSICSPar(pHdb node, void *callData);
|
||||
/*=============== Add par functions =======================================*/
|
||||
/**
|
||||
* add a new simple hdb parameter as child to node
|
||||
* @param parent The parent node to add the new node to.
|
||||
* @param name The name of the new node
|
||||
* @param priv The privilege required to change that parameter
|
||||
* @param v The initial value and datatype of this parameter
|
||||
* @return the created node on success, NULL else
|
||||
*/
|
||||
pHdb AddSICSHdbPar(pHdb parent, char *name, int priv, hdbValue v);
|
||||
/**
|
||||
* add a new read only hdb parameter as child to node
|
||||
* @param parent The parent node to add the new node to.
|
||||
* @param name The name of the new node
|
||||
* @param v The initial value and datatype of this parameter
|
||||
* @return the created node on success, NULL else
|
||||
*/
|
||||
pHdb AddSICSHdbROPar(pHdb parent, char *name, hdbValue v);
|
||||
/**
|
||||
* Add a new hdb parameter as child to node. Updates are synced
|
||||
* to the memory location data. This works for simple variables, fixed size
|
||||
* arrays and fixed sized strings. This does not work for dynamically sized
|
||||
* arrays or strings.
|
||||
* @param parent The parent node to add the new node to.
|
||||
* @param name The name of the new node
|
||||
* @param priv The privilege required to change that parameter
|
||||
* @param data The pointer to map this parameter to. This must be in
|
||||
* dynamically allocated memory.
|
||||
* @param datalength The length of the data area pointed to by data.
|
||||
* @param type The data type of the parameter
|
||||
* @param length The length of the type. Used for array types.
|
||||
* @return the created node on success, NULL else
|
||||
*/
|
||||
pHdb AddSICSHdbMemPar(pHdb parent, char *name, int priv,
|
||||
void *data, int datalength, int type, int length);
|
||||
/*============== access support functions =================================*/
|
||||
/** Find the parent of a node to be created
|
||||
* @param rootpath the root path (where to start). May be NULL for absolute paths
|
||||
* @param relpath an absolute or relative path
|
||||
* @param namePtr (output) a pointer to a name. Will be the last element of
|
||||
* the path if the parent was found. If namePtr is NULL, the routine does
|
||||
* the same as FindHdbNode(root, relpath, pCon)
|
||||
* @param pCon a connection for writing the error messages (may be NULL)
|
||||
* @return the parent node or NULL on failure
|
||||
*
|
||||
* An abolute path starts with a slash, else it is a relative path.
|
||||
* If the node exists already, an error message is emitted (node exists already)
|
||||
* and NULL is returned.
|
||||
*
|
||||
* Nodes anchored in the sics object list are also found when
|
||||
* the path starts with "/sics/"
|
||||
*/
|
||||
pHdb FindHdbParent(char *rootpath, char *relpath, char **namePtr, SConnection *pCon);
|
||||
/** FindHdbNode finds a node
|
||||
* @param rootpath the root path (where to start). May be NULL for absolute paths.
|
||||
* @param relpath an absolute or relative path
|
||||
* @param pCon a connection for writing the error messages (may be NULL)
|
||||
* @return the found node or NULL on failure
|
||||
*
|
||||
* An abolute path starts with a slash, else it is a relative path.
|
||||
* If relpath if a single dot ('.') root is returned.
|
||||
*
|
||||
* Nodes anchored in the sics object list are also found when
|
||||
* the path starts with "/sics/"
|
||||
*/
|
||||
pHdb FindHdbNode(char *rootpath, char *relpath, SConnection *pCon);
|
||||
/** Get the absolute path of a node anchored in the
|
||||
* Hipadaba root or in a sics object
|
||||
* @param nodeArg the input node
|
||||
* @param path the result
|
||||
* @param pathlen length of the result
|
||||
* @return 1 on success, 0 on failure
|
||||
*/
|
||||
int GetHdbPath(pHdb nodeArg, char *path, size_t pathlen);
|
||||
/** Remove all Callbacks rooted in the main root _and_ in sics objects
|
||||
* @param internalID the internalID to be looked for
|
||||
*/
|
||||
void RemoveSICSInternalCallback(void *internalID);
|
||||
/**
|
||||
* SICSHdbGetPar returns the value of a parameter.
|
||||
* @param obj The object for which to get a parameter.
|
||||
* @param pCon The optional connection object to use for reporting errors.
|
||||
* @param path The path to the parameter.
|
||||
* @param v the value
|
||||
* @return 1 on success, a negative error code else.
|
||||
*/
|
||||
int SICSHdbGetPar(void *obj, SConnection *pCon, char *path, hdbValue *v);
|
||||
/**
|
||||
* SICSHdbUpdatePar updates the value of a parameter.
|
||||
* @param obj The object for which to get a parameter.
|
||||
* @param pCon The optional connection object to use for reporting errors.
|
||||
* @param path The path to the parameter.
|
||||
* @param v the value
|
||||
* @return 1 on success, a negative error code else.
|
||||
*/
|
||||
int SICSHdbUpdatePar(void *obj, SConnection *pCon, char *path, hdbValue v);
|
||||
/**
|
||||
* SICSHdbSetPar sets the value of a parameter.
|
||||
* @param obj The object for which to get a parameter.
|
||||
* @param pCon The optional connection object to use for reporting errors.
|
||||
* @param path The path to the parameter.
|
||||
* @param v the value
|
||||
* @return positive on success, a negative error code else.
|
||||
*/
|
||||
int SICSHdbSetPar(void *obj, SConnection *pCon, char *path, hdbValue v);
|
||||
/**
|
||||
* query function if a parameter is read only.
|
||||
* @param node The ndoe to query
|
||||
* @return 1 when RO, 0 else
|
||||
*/
|
||||
int isSICSHdbRO(pHdb node);
|
||||
/*============= common SICS Interactions ===================================*/
|
||||
/**
|
||||
* Install a SICS automatic notification callback on the node. This is
|
||||
* a default callback using the current connection with its current
|
||||
* context for notification.
|
||||
* @param node The parameter on which to install the callback
|
||||
* @param pCon The connection to which this callback is linked.
|
||||
* @param id An int associated with this notification callback. A
|
||||
* precaution for later removal.
|
||||
* @param recurse a flag 0 or 1 which determines if callbacks are
|
||||
* installed to all nodes recursively.
|
||||
* @return 1 on success, 0 when out of memory.
|
||||
*/
|
||||
int InstallSICSNotify(pHdb node, SConnection *pCon, int id, int recurse);
|
||||
/**
|
||||
* remove all Callbacks associated with a given conenction
|
||||
* @param root Where to start removing callbacks
|
||||
* @param pCon The connection for which to remove callbacks
|
||||
*/
|
||||
void RemoveConnectionCallbacks(pHdb root, SConnection *pCon);
|
||||
/**
|
||||
* handles the common task of checking for, and processing a SICS parameter.
|
||||
* @param root The node at which to search for parameters
|
||||
* @param pCon The connection in whichs context the parameter is processed.
|
||||
* @param printPrefix A prefix to prepend before printing this parameter.
|
||||
* Will be ignored if NULL.
|
||||
* @param argc number of arguments to process.
|
||||
* @param argv The arguments to process. argv[0] should be the parameter
|
||||
* name.
|
||||
* @return -1 when argv[0] is no parameter, 0 on failure, 1 on success.
|
||||
*/
|
||||
int ProcessSICSHdbPar(pHdb root, SConnection *pCon, char *printPrefix,
|
||||
int argc, char *argv[]);
|
||||
/**
|
||||
* print a listing of the parameters of node to pCon, using the
|
||||
* specified prefix.
|
||||
* @param node The node to print
|
||||
* @param pCon The connection to print to
|
||||
* @param prefix The prefix to use for printing
|
||||
*/
|
||||
void PrintSICSParList(pHdb node, SConnection *pCon, char *prefix);
|
||||
/**
|
||||
* save the content of the Hipadaba starting at node into a file. This can
|
||||
* be used to save the configuration of an instrument. This routine is
|
||||
* recursive.
|
||||
* @param fd The file to write to
|
||||
* @param node The node to print from
|
||||
* @param prefix A prefix to use for printing.
|
||||
*/
|
||||
void SaveSICSHipadaba(FILE *fd, pHdb node, char *prefix);
|
||||
/**
|
||||
* A SICS task which scans a Hipadaba and reads and updates all parameters,
|
||||
* one per invocation. TODO: how to distinguish between automatic pars which
|
||||
* do not need this and pars which need this? Idea 1: make a root point at an
|
||||
* artificial tree of parameters which need to be checked like this.
|
||||
* @param pData The root to start scanning at.
|
||||
* @return 0 when ends, 1 else
|
||||
*/
|
||||
int SICSHipadabaTask(void *pData);
|
||||
void SICSHipadabaSignal(void *pData, int iSignal, void *pSigData);
|
||||
/*================== value helpers ========================================*/
|
||||
/**
|
||||
* format a Hdb Value into a string using SICS defaults.
|
||||
* @param v The Hdb value to format
|
||||
* @param node The Hdb node (for format property)
|
||||
* @return a dynamic string holding the formatted data. NULL when
|
||||
* out of memory
|
||||
*/
|
||||
pDynString formatValue(hdbValue v, pHdb node);
|
||||
/**
|
||||
* read values for a Hdb value from a string.
|
||||
* @param v The hdbValue to read data into. Datatype and arraylength must
|
||||
* already have been initialised before this call in order to allow for
|
||||
* checks. Arrays should also have been allocated in the right size.
|
||||
* @param data The string to parse and convert.
|
||||
* @param error A string to copy failure reasons to
|
||||
* @param errlen The length of the error string
|
||||
* @return 0 on failure, 1 on success
|
||||
*/
|
||||
int readHdbValue(hdbValue *v, char *data, char *error, int errlen);
|
||||
/**
|
||||
* convert from test to a Hipadaba type
|
||||
* @param text The type text
|
||||
* @return The converted Hipadaba type
|
||||
*/
|
||||
int convertHdbType(char *text);
|
||||
/**
|
||||
* wrap a SICSOBJFunc function as an hdbValue
|
||||
* @param func the function
|
||||
* @return: A properly initialized hdbValue structure
|
||||
*/
|
||||
hdbValue MakeSICSFunc(SICSOBJFunc func);
|
||||
|
||||
/*================= SICS Interpreter Interface ===========================*/
|
||||
/**
|
||||
* InstallHipadaba installs the Hipadaba commands into the SICS interpreter.
|
||||
* The actual command implementation is in sicshipadaba.c.
|
||||
* @param pCon The connection object
|
||||
* @param pSics The SICS interpreter
|
||||
* @param pData The object data structure
|
||||
* @param argc The number of arguments
|
||||
* @param argv[] The text arguments
|
||||
* @return 0 on filaure, 1 on success
|
||||
*/
|
||||
int InstallSICSHipadaba(SConnection *pCon, SicsInterp *pSics, void *pData,
|
||||
int argc, char *argv[]);
|
||||
/**
|
||||
* get the root of the SICS Hipadaba tree
|
||||
* @return The root node of the hipdaba
|
||||
*/
|
||||
pHdb GetHipadabaRoot();
|
||||
/**
|
||||
* kill the SICS hierarchical database
|
||||
* Only to be called when shutting down the SICServer
|
||||
*/
|
||||
void killSICSHipadaba(void);
|
||||
#endif /*SICSHIPADABA_H_*/
|
||||
Reference in New Issue
Block a user