sics/sicshipadaba.h

/** @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>
#define MAX_HDB_PATH 1024
/*======================== 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);
pHdbMessage GetHdbStartMessage(pHdbMessage message);
pHdbMessage GetHdbStopMessage(pHdbMessage message);
void SendHdbStatusMessage(pHdb node, char *status);
/*======================== 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);
/** Remove all Callbacks rooted in the node
 * @param internalID the internalID to be looked for
 */
void RemoveSICSInternalCallbackFrom(pHdb node, 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 set 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_ */