/**
 * 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>
/*======================== callback error codes ===============================*/
#define SICSCBRO        -607
#define SICSCBPERM      -608
#define SICSCBRANGE     -609  
#define SICSCBBADFIXED  -610
#define SICSNOPAR       -611
/*======================== data structure for automatic parameter update =======*/
typedef struct {
        SConnection *pCon;
        int updateList;
        int iEnd;
}hdbUpdateTask, *pHdbUpdateTask;
/*======================== common callbacks =====================================*/
/**
 * 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. Usefule for program parameters.
 * @return a suitably initialized callback structure setting
 * program parameters
 */
pHdbCallback MakeSetUpdateCallback();
/**
 * 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);
/*======================== 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
 */
void RemoveSICSPar(pHdb node);
/*=============== Add par functions =======================================*/
/**
 * add a new simple hdb parameter as child to node
 * @param node The node to add the new node too.
 * @param priv The privilege required to change that parameter
 * @param v The initial value and datatype of this parameter
 * @return 1 on success, 0 else
 */
int AddSICSHdbPar(pHdb node, char *name, int priv, hdbValue v);
/**
 * add a new read only hdb parameter as child to node
 * @param node The node to add the new node too.
 * @param v The initial value and datatype of this parameter
 * @return 1 on success, 0 else
 */
int AddSICSHdbROPar(pHdb node, 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 node The node to add the new node too.
 * @param priv The privilege required to change that parameter
 * @param data The pointer to map this parameter too. 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 1 on success, 0 else
 */
int AddSICSHdbMemPar(pHdb node, char *name, int priv,
     void *data, int datalength, int type, int length);
/*============== access support functions =================================*/
/**
 * SICSHdbGetFloat returns the float value of a parameter. Integers are
 * automatically converted.
 * @param parent The parent node where to start searching for the parameter
 * @param pCon The optional connection object to use for reporting errors.
 * @param path The path to the parameter.
 * @param value The value of the parameter
 * @return 1 on success, a negative error code else.
 */  
int SICSHdbGetFloat(pHdb parent, SConnection *pCon,
     char *path, float *value);
/**
 * SICSHdbSetFloat sets the value of a parameter. Integers are
 * automatically converted.
 * @param parent The parent node where to start searching for the parameter
 * @param pCon The optional connection object to use for reporting errors.
 * @param path The path to the parameter.
 * @param value The new value of the parameter
 * @return 1 on success, a negative error code else.
 */  
int SICSHdbSetFloat(pHdb parent, SConnection *pCon, 
     char *path, float value);
/**
 * 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);
/**
 * 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 The node to print
 * @pCon The connection to print too
 * @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
 * @return a dynamic string holding the formatted data. NULL when
 * out of memory
 */ 
pDynString formatValue(hdbValue v);
/**
 * 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 too
 * @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);
/*================= 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_*/