libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

cmPrefs.h 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199
  1. #ifndef cmPrefs_h
  2. #define cmPrefs_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. //( { file_desc:"Manage persistent application preferences." kw:[base] }
  7. typedef unsigned cmPrRC_t;
  8. typedef cmHandle_t cmPrH_t;
  9. enum
  10. {
  11. kOkPrRC = cmOkRC,
  12. kJsonFailPrRC,
  13. kLHeapFailPrRC,
  14. kCbNotFoundPrRC,
  15. kVarNotFoundPrRC,
  16. kBufTooSmallPrRC,
  17. kCvtErrPrRC,
  18. kInvalidIdPrRC,
  19. kInvalidIndexPrRC,
  20. kWriteFileFailPrRC,
  21. kNodeCreateFailPrRC,
  22. kDuplicateIdPrRC,
  23. kFileSysFailPrRC
  24. };
  25. enum
  26. {
  27. kMaxVarPrId = 0x7fffffff // User assigned variable id's given to cmPrefsCreateXXX()
  28. // must be less than kMaxVarPrId
  29. };
  30. typedef void (*cmPrefsOnChangeFunc_t)( cmPrH_t h, void* cbDataPtr, unsigned id );
  31. extern cmPrH_t cmPrNullHandle;
  32. // cmPrefsInit() creates the preference directory if it does not exist
  33. // according to cmFsPrefsDir(). It then forms the prefs file name as
  34. // 'cmFsPrefsDir()/fnName.fnExt' and call cmPrefsInitialize().
  35. // Set 'fnName' to NULL to use cmFsAppName() as the pref file name.
  36. // Set 'fnExt' to NULL to use '.js' as the pref file extension.
  37. // 'cbFunc' and 'cbDataPtr' are optional in both versions.
  38. // 'pathPrefixStr' (optional) provides a prefix to be added to
  39. // the path of each preference variable. This can be used to separate
  40. // preference data from other data in the preference file.
  41. 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 );
  42. cmPrRC_t cmPrefsInitialize( cmCtx_t* ctx, cmPrH_t* hp, const cmChar_t* fn, cmPrefsOnChangeFunc_t cbFunc, void* cbDataPtr, const cmChar_t* pathPrefixStr);
  43. cmPrRC_t cmPrefsFinalize( cmPrH_t* hp );
  44. bool cmPrefsIsValid( cmPrH_t h );
  45. const cmChar_t* cmPrefsFileName( cmPrH_t h );
  46. // Return last RC.
  47. cmPrRC_t cmPrefsRC( cmPrH_t h);
  48. // Return last RC and set new RC.
  49. cmPrRC_t cmPrefsSetRC( cmPrH_t h, cmPrRC_t rc );
  50. cmPrRC_t cmPrefsInstallCallback( cmPrH_t h, cmPrefsOnChangeFunc_t cbFunc, void* cbDataPtr );
  51. cmPrRC_t cmPrefsRemoveCallback( cmPrH_t h, cmPrefsOnChangeFunc_t cbFunc );
  52. // Return cmInvalidId if the no variable is found with the requested path.
  53. unsigned cmPrefsId( cmPrH_t h, const cmChar_t* pathStr, bool reportNotFoundFl );
  54. // Returns -1 (and generates an error msg) if no pref. variable
  55. // is associated with id. Returns 1 if the variable is a scalar.
  56. unsigned cmPrefsEleCount( cmPrH_t h, unsigned id );
  57. // On input *'eleCntPtr' must contain the number of elements in the buffer
  58. // pointed to by 'vp' or NULL if '*vp' is a scalar.
  59. // On return *'eleCntPtr' contains the actual number of elements
  60. // returned by the function.
  61. // Set eleCntPtr to NULL for scalar a values.
  62. cmPrRC_t cmPrefsGetBool( cmPrH_t h, unsigned id, bool* vp, unsigned* eleCntPtr );
  63. cmPrRC_t cmPrefsGetUInt( cmPrH_t h, unsigned id, unsigned* vp, unsigned* eleCntPtr );
  64. cmPrRC_t cmPrefsGetInt( cmPrH_t h, unsigned id, int* vp, unsigned* eleCntPtr );
  65. cmPrRC_t cmPrefsGetReal( cmPrH_t h, unsigned id, double* vp, unsigned* eleCntPtr );
  66. cmPrRC_t cmPrefsGetString( cmPrH_t h, unsigned id, const cmChar_t** vp, unsigned* eleCntPtr );
  67. // Simplified scalar interface - check cmPrefsRC() for errors.
  68. bool cmPrefsBool( cmPrH_t h, unsigned id );
  69. unsigned cmPrefsUInt( cmPrH_t h, unsigned id );
  70. int cmPrefsInt( cmPrH_t h, unsigned id );
  71. float cmPrefsFloat( cmPrH_t h, unsigned id );
  72. double cmPrefsReal( cmPrH_t h, unsigned id );
  73. const cmChar_t* cmPrefsString( cmPrH_t h, unsigned id );
  74. // Simplified scalar interface w/ default values - check cmPrefsRC() for errors.
  75. // Returns the stored preference variable unless 'pathStr' does not identify a variable
  76. // or if 'h' is not valid. In either of these cases 'dfltVal' is returned.
  77. bool cmPrefsBoolDef( cmPrH_t h, const cmChar_t* pathStr, bool dfltVal );
  78. unsigned cmPrefsUIntDef( cmPrH_t h, const cmChar_t* pathStr, unsigned dfltVal );
  79. int cmPrefsIntDef( cmPrH_t h, const cmChar_t* pathStr, int dfltVal );
  80. float cmPrefsFloatDef( cmPrH_t h, const cmChar_t* pathStr, float dfltVal );
  81. double cmPrefsRealDef( cmPrH_t h, const cmChar_t* pathStr, double dfltVal );
  82. const cmChar_t* cmPrefsStringDef( cmPrH_t h, const cmChar_t* pathStr, const cmChar_t* dfltVal );
  83. // Get a scalar value.
  84. cmPrRC_t cmPrefsBoolRc( cmPrH_t h, const cmChar_t* pathStr, bool* retValPtr );
  85. cmPrRC_t cmPrefsUIntRc( cmPrH_t h, const cmChar_t* pathStr, unsigned* retValPtr );
  86. cmPrRC_t cmPrefsIntRc( cmPrH_t h, const cmChar_t* pathStr, int* retValPtr );
  87. cmPrRC_t cmPrefsFloatRc( cmPrH_t h, const cmChar_t* pathStr, float* retValPtr );
  88. cmPrRC_t cmPrefsRealRc( cmPrH_t h, const cmChar_t* pathStr, double* retValPtr );
  89. cmPrRC_t cmPrefsStringRc( cmPrH_t h, const cmChar_t* pathStr, const cmChar_t** retValPtr );
  90. // Simplified array interface - check cmPrefsRC() for errors
  91. // Returns cmInvalidCnt if 'id' is invalid or 0 if the identified var. is a scalar.
  92. unsigned cmPrefsArrayElementCount( cmPrH_t h, unsigned id );
  93. bool cmPrefsBoolEle( cmPrH_t h, unsigned id, unsigned idx );
  94. unsigned cmPrefsUIntEle( cmPrH_t h, unsigned id, unsigned idx );
  95. int cmPrefsIntEle( cmPrH_t h, unsigned id, unsigned idx );
  96. float cmPrefsFloatEle( cmPrH_t h, unsigned id, unsigned idx );
  97. double cmPrefsRealEle( cmPrH_t h, unsigned id, unsigned idx );
  98. const cmChar_t* cmPrefsStringEle( cmPrH_t h, unsigned id, unsigned idx );
  99. // Set a preference value.
  100. // The size of array variables is allowed to shrink or grow but the type (bool/int/real/string)
  101. // must match.
  102. //
  103. // Note that the following limitations apply:
  104. // 1) This interface allows setting the value of an existing preference variable.
  105. // New variables may not be added.
  106. // 2) The type (bool/int/real/string) of the variable must match the value.
  107. // (e.g. 'int' type variables can only be set via cmPrefsSetInt()).
  108. // 3) For scalar (non-array) variables *eleCntPtr must be set to 1.
  109. //
  110. cmPrRC_t cmPrefsSetBoolArray( cmPrH_t h, unsigned id, const bool* vp, const unsigned* eleCntPtr );
  111. cmPrRC_t cmPrefsSetIntArray( cmPrH_t h, unsigned id, const int* vp, const unsigned* eleCntPtr );
  112. cmPrRC_t cmPrefsSetRealArray( cmPrH_t h, unsigned id, const double* vp, const unsigned* eleCntPtr );
  113. cmPrRC_t cmPrefsSetStringArray( cmPrH_t h, unsigned id, const cmChar_t** vp, const unsigned* eleCntPtr );
  114. cmPrRC_t cmPrefsSetBool( cmPrH_t h, unsigned id, bool val );
  115. cmPrRC_t cmPrefsSetUInt( cmPrH_t h, unsigned id, unsigned val );
  116. cmPrRC_t cmPrefsSetInt( cmPrH_t h, unsigned id, int val );
  117. cmPrRC_t cmPrefsSetFloat( cmPrH_t h, unsigned id, float val );
  118. cmPrRC_t cmPrefsSetReal( cmPrH_t h, unsigned id, double val );
  119. cmPrRC_t cmPrefsSetString( cmPrH_t h, unsigned id, const cmChar_t* val );
  120. cmPrRC_t cmPrefsPathSetBool( cmPrH_t h, const cmChar_t* pathStr, bool val );
  121. cmPrRC_t cmPrefsPathSetUInt( cmPrH_t h, const cmChar_t* pathStr, unsigned val );
  122. cmPrRC_t cmPrefsPathSetInt( cmPrH_t h, const cmChar_t* pathStr, int val );
  123. cmPrRC_t cmPrefsPathSetFloat( cmPrH_t h, const cmChar_t* pathStr, float val );
  124. cmPrRC_t cmPrefsPathSetReal( cmPrH_t h, const cmChar_t* pathStr, double val );
  125. cmPrRC_t cmPrefsPathSetString( cmPrH_t h, const cmChar_t* pathStr, const cmChar_t* val );
  126. // Create a new preference variable and set it's value to 'val'.
  127. // If a variable with the same path and type already exists and kForceValuePrFl
  128. // is set then update it's value to 'val'. Note that in this case if
  129. // kForceValuePrFl is not set then the function returns quietly.
  130. //
  131. // If a variable with the same path but a different type exists then an error is returned.
  132. //
  133. // The 'id' argument is optional. If 'id' is set to cmInvalidId then the
  134. // variable will be automatically assigned an id. The value of the
  135. // automatically assigned id can be found from the path string
  136. // via cmPrefsId(). If 'id' is not set to cmInvalidId then it must be less than
  137. // kMaxVarId.
  138. // Set kForceValuePrFl
  139. enum { kForceValuePrFl=0x01 };
  140. cmPrRC_t cmPrefsCreateBool( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, bool val );
  141. cmPrRC_t cmPrefsCreateUInt( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, unsigned val );
  142. cmPrRC_t cmPrefsCreateInt( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, int val );
  143. cmPrRC_t cmPrefsCreateFloat( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, float val );
  144. cmPrRC_t cmPrefsCreateReal( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, double val );
  145. cmPrRC_t cmPrefsCreateString( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const cmChar_t* val );
  146. cmPrRC_t cmPrefsCreateBoolArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const bool* val, unsigned eleCnt );
  147. cmPrRC_t cmPrefsCreateUIntArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const unsigned* val, unsigned eleCnt );
  148. cmPrRC_t cmPrefsCreateIntArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const int* val, unsigned eleCnt );
  149. cmPrRC_t cmPrefsCreateFloatArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const float* val, unsigned eleCnt );
  150. cmPrRC_t cmPrefsCreateRealArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const double* val, unsigned eleCnt );
  151. cmPrRC_t cmPrefsCreateStringArray( cmPrH_t h, unsigned id, const cmChar_t* pathStr, unsigned flags, const cmChar_t** val, unsigned eleCnt );
  152. bool cmPrefsIsDirty( cmPrH_t h );
  153. // If 'fn' is NULL then the filename passed in cmPrefsInitialize() is used.
  154. cmPrRC_t cmPrefsWrite( cmPrH_t h, const cmChar_t* fn );
  155. void cmPrefsReport( cmPrH_t h );
  156. void cmPrefsTest( cmCtx_t* ctx, const char* ifn, const char* ofn );
  157. //)
  158. #ifdef __cplusplus
  159. }
  160. #endif
  161. #endif