libcm/src/cmPrefs.h

//| Copyright: (C) 2009-2020 Kevin Larke <contact AT larke DOT org> 
//| License: GNU GPL version 3.0 or above. See the accompanying LICENSE file.
#ifndef cmPrefs_h
#define cmPrefs_h

#ifdef __cplusplus
extern "C" {
#endif

  //( { file_desc:"Manage persistent application preferences." kw:[base] }
  
  typedef unsigned cmPrRC_t;
  typedef cmHandle_t cmPrH_t;

  enum
  {
    kOkPrRC = cmOkRC,
    kJsonFailPrRC,
    kLHeapFailPrRC,
    kCbNotFoundPrRC,
    kVarNotFoundPrRC,
    kBufTooSmallPrRC,
    kCvtErrPrRC,
    kInvalidIdPrRC,
    kInvalidIndexPrRC,
    kWriteFileFailPrRC,
    kNodeCreateFailPrRC,
    kDuplicateIdPrRC,
    kFileSysFailPrRC
  };

  enum
  {
    kMaxVarPrId = 0x7fffffff // User assigned variable id's given to cmPrefsCreateXXX()
                             // must be less than kMaxVarPrId
  };

  typedef void (*cmPrefsOnChangeFunc_t)( cmPrH_t h, void* cbDataPtr, unsigned id ); 

  extern cmPrH_t cmPrNullHandle;

  // cmPrefsInit() creates the preference directory if it does not exist 
  // according to cmFsPrefsDir(). It then forms the prefs file name as
  // 'cmFsPrefsDir()/fnName.fnExt' and call cmPrefsInitialize().
  // Set 'fnName' to NULL to use cmFsAppName() as the pref file name.
  // Set 'fnExt' to NULL to use '.js' as the pref file extension.
  // 'cbFunc'  and 'cbDataPtr' are optional in both versions.
  // 'pathPrefixStr' (optional) provides a prefix to be added to 
  // the path of each preference variable. This can be used to separate
  // preference data from other data in the preference file.
  cmPrRC_t cmPrefsInit(   cmCtx_t* ctx, cmPrH_t* hp, const cmChar_t* fnName, const cmChar_t* fnExt, cmPrefsOnChangeFunc_t cbFunc, void* cbDataPtr, const cmChar_t* pathPrefixStr );
  cmPrRC_t cmPrefsInitialize( cmCtx_t* ctx, cmPrH_t* hp, const cmChar_t* fn, cmPrefsOnChangeFunc_t cbFunc, void* cbDataPtr, const cmChar_t* pathPrefixStr);
  cmPrRC_t cmPrefsFinalize(   cmPrH_t* hp );

  bool cmPrefsIsValid( cmPrH_t h );

  const cmChar_t* cmPrefsFileName( cmPrH_t h );

  // Return last RC.
  cmPrRC_t cmPrefsRC( cmPrH_t h);

  // Return last RC and set new RC.
  cmPrRC_t cmPrefsSetRC( cmPrH_t h, cmPrRC_t rc );

  cmPrRC_t cmPrefsInstallCallback( cmPrH_t h, cmPrefsOnChangeFunc_t cbFunc, void* cbDataPtr );
  cmPrRC_t cmPrefsRemoveCallback(  cmPrH_t h, cmPrefsOnChangeFunc_t cbFunc );

  // Return cmInvalidId if the no variable is found with the requested path.
  unsigned cmPrefsId( cmPrH_t h, const cmChar_t* pathStr, bool reportNotFoundFl );

  // Returns -1 (and generates an error msg) if no pref. variable
  // is associated with id.  Returns 1 if the variable is a scalar.
  unsigned cmPrefsEleCount( cmPrH_t h,  unsigned id );

  // On input *'eleCntPtr' must contain the number of elements in the buffer 
  // pointed to by 'vp' or NULL if '*vp' is a scalar.
  // On return *'eleCntPtr' contains the actual number of elements 
  // returned by the function.  
  // Set eleCntPtr to NULL for scalar a values.
  cmPrRC_t cmPrefsGetBool(   cmPrH_t h, unsigned id, bool*            vp, unsigned* eleCntPtr );
  cmPrRC_t cmPrefsGetUInt(   cmPrH_t h, unsigned id, unsigned*        vp, unsigned* eleCntPtr );
  cmPrRC_t cmPrefsGetInt(    cmPrH_t h, unsigned id, int*             vp, unsigned* eleCntPtr );
  cmPrRC_t cmPrefsGetReal(   cmPrH_t h, unsigned id, double*          vp, unsigned* eleCntPtr );
  cmPrRC_t cmPrefsGetString( cmPrH_t h, unsigned id, const cmChar_t** vp, unsigned* eleCntPtr );

  // Simplified scalar interface - check cmPrefsRC() for errors.
  bool            cmPrefsBool(   cmPrH_t h, unsigned id );
  unsigned        cmPrefsUInt(   cmPrH_t h, unsigned id );
  int             cmPrefsInt(    cmPrH_t h, unsigned id );
  float           cmPrefsFloat(  cmPrH_t h, unsigned id );
  double          cmPrefsReal(   cmPrH_t h, unsigned id );
  const cmChar_t* cmPrefsString( cmPrH_t h, unsigned id ); 

  // Simplified scalar interface w/ default values - check cmPrefsRC() for errors.
  // Returns the stored preference variable unless 'pathStr' does not identify a variable
  // or if 'h' is not valid.  In either of these cases 'dfltVal' is returned.
  bool            cmPrefsBoolDef(   cmPrH_t h, const cmChar_t* pathStr, bool            dfltVal );
  unsigned        cmPrefsUIntDef(   cmPrH_t h, const cmChar_t* pathStr, unsigned        dfltVal );
  int             cmPrefsIntDef(    cmPrH_t h, const cmChar_t* pathStr, int             dfltVal );
  float           cmPrefsFloatDef(  cmPrH_t h, const cmChar_t* pathStr, float           dfltVal );
  double          cmPrefsRealDef(   cmPrH_t h, const cmChar_t* pathStr, double          dfltVal );
  const cmChar_t* cmPrefsStringDef( cmPrH_t h, const cmChar_t* pathStr, const cmChar_t* dfltVal ); 

  // Get a scalar value. 
  cmPrRC_t        cmPrefsBoolRc(   cmPrH_t h, const cmChar_t* pathStr, bool*            retValPtr );
  cmPrRC_t        cmPrefsUIntRc(   cmPrH_t h, const cmChar_t* pathStr, unsigned*        retValPtr );
  cmPrRC_t        cmPrefsIntRc(    cmPrH_t h, const cmChar_t* pathStr, int*             retValPtr );
  cmPrRC_t        cmPrefsFloatRc(  cmPrH_t h, const cmChar_t* pathStr, float*           retValPtr );
  cmPrRC_t        cmPrefsRealRc(   cmPrH_t h, const cmChar_t* pathStr, double*          retValPtr );
  cmPrRC_t        cmPrefsStringRc( cmPrH_t h, const cmChar_t* pathStr, const cmChar_t** retValPtr ); 


  // Simplified array interface - check cmPrefsRC() for errors

  // Returns cmInvalidCnt if 'id' is invalid or 0 if the identified var. is a scalar.
  unsigned        cmPrefsArrayElementCount( cmPrH_t h, unsigned id );

  bool            cmPrefsBoolEle(   cmPrH_t h, unsigned id, unsigned idx );
  unsigned        cmPrefsUIntEle(   cmPrH_t h, unsigned id, unsigned idx );
  int             cmPrefsIntEle(    cmPrH_t h, unsigned id, unsigned idx );
  float           cmPrefsFloatEle(  cmPrH_t h, unsigned id, unsigned idx );
  double          cmPrefsRealEle(   cmPrH_t h, unsigned id, unsigned idx );
  const cmChar_t* cmPrefsStringEle( cmPrH_t h, unsigned id, unsigned idx ); 

  // Set a preference value.
  // The size of array variables is allowed to shrink or grow but the type (bool/int/real/string)
  // must match.
  //
  // Note that the following limitations apply:
  // 1) This interface allows setting the value of an existing preference variable.
  //    New variables may not be added.
  // 2) The type (bool/int/real/string) of the variable must match the value.
  // (e.g. 'int' type variables can only be set via cmPrefsSetInt()).
  // 3) For  scalar (non-array) variables *eleCntPtr must be set to 1.
  //

  cmPrRC_t cmPrefsSetBoolArray(   cmPrH_t h, unsigned id, const bool*      vp, const unsigned* eleCntPtr );
  cmPrRC_t cmPrefsSetIntArray(    cmPrH_t h, unsigned id, const int*       vp, const unsigned* eleCntPtr );
  cmPrRC_t cmPrefsSetRealArray(   cmPrH_t h, unsigned id, const double*    vp, const unsigned* eleCntPtr );
  cmPrRC_t cmPrefsSetStringArray( cmPrH_t h, unsigned id, const cmChar_t** vp, const unsigned* eleCntPtr );

  cmPrRC_t cmPrefsSetBool(   cmPrH_t h, unsigned id, bool     val );
  cmPrRC_t cmPrefsSetUInt(   cmPrH_t h, unsigned id, unsigned val );
  cmPrRC_t cmPrefsSetInt(    cmPrH_t h, unsigned id, int      val );
  cmPrRC_t cmPrefsSetFloat(  cmPrH_t h, unsigned id, float    val );
  cmPrRC_t cmPrefsSetReal(   cmPrH_t h, unsigned id, double   val );
  cmPrRC_t cmPrefsSetString( cmPrH_t h, unsigned id, const cmChar_t* val );

  cmPrRC_t cmPrefsPathSetBool(   cmPrH_t h, const cmChar_t* pathStr, bool     val );
  cmPrRC_t cmPrefsPathSetUInt(   cmPrH_t h, const cmChar_t* pathStr, unsigned val );
  cmPrRC_t cmPrefsPathSetInt(    cmPrH_t h, const cmChar_t* pathStr, int      val );
  cmPrRC_t cmPrefsPathSetFloat(  cmPrH_t h, const cmChar_t* pathStr, float    val );
  cmPrRC_t cmPrefsPathSetReal(   cmPrH_t h, const cmChar_t* pathStr, double   val );
  cmPrRC_t cmPrefsPathSetString( cmPrH_t h, const cmChar_t* pathStr, const cmChar_t* val );

  // Create a new preference variable and set it's value to 'val'.
  // If a variable with the same path and type already exists and kForceValuePrFl
  // is set then update it's value to 'val'. Note that in this case if
  //  kForceValuePrFl is not set then the function returns quietly.
  //
  // If a variable with the same path but a different type exists then an error is returned.
  // 
  // The 'id' argument is optional.  If 'id' is set to cmInvalidId then the
  // variable will be automatically assigned an id.  The value of the
  // automatically assigned id can be found from the path string
  // via cmPrefsId().  If 'id' is not set to cmInvalidId then it must be less than 
  // kMaxVarId.

  // Set kForceValuePrFl 
  enum { kForceValuePrFl=0x01 };
  cmPrRC_t cmPrefsCreateBool(   cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, bool     val );
  cmPrRC_t cmPrefsCreateUInt(   cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, unsigned val );
  cmPrRC_t cmPrefsCreateInt(    cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, int      val );
  cmPrRC_t cmPrefsCreateFloat(  cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, float    val );
  cmPrRC_t cmPrefsCreateReal(   cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, double   val );
  cmPrRC_t cmPrefsCreateString( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const cmChar_t* val );

  cmPrRC_t cmPrefsCreateBoolArray(   cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const bool*     val, unsigned eleCnt );
  cmPrRC_t cmPrefsCreateUIntArray(   cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const unsigned* val, unsigned eleCnt );
  cmPrRC_t cmPrefsCreateIntArray(    cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const int*      val, unsigned eleCnt );
  cmPrRC_t cmPrefsCreateFloatArray(  cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const float*    val, unsigned eleCnt );
  cmPrRC_t cmPrefsCreateRealArray(   cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const double*   val, unsigned eleCnt );
  cmPrRC_t cmPrefsCreateStringArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const cmChar_t** val, unsigned eleCnt );

  bool     cmPrefsIsDirty( cmPrH_t h );

  // If 'fn' is NULL then the filename passed in cmPrefsInitialize() is used.
  cmPrRC_t cmPrefsWrite( cmPrH_t h, const cmChar_t* fn );

  void cmPrefsReport( cmPrH_t h );


  void cmPrefsTest( cmCtx_t* ctx, const char* ifn, const char* ofn );
    
  //)
  
#ifdef __cplusplus
}
#endif

#endif