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.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231
  1. //{
  2. //(
  3. // A collection of file system utility functions.
  4. //
  5. // Note that cmFileSysInitialize() creates an internal cmLHeapH_t based
  6. // heap manager from which it allocates memory for some returned objects.
  7. // (e.g. cmFileSysMakeFn(), cmFileSysPathParts(), cmFileSysDirEntries())
  8. // Where possible the client can explicitely free these objects via the
  9. // provided functions. (e.g. cmFileSysFreeFn(), cmFileSysFreePathParts(), cmFileSysDirFreeEntries())
  10. // However if these objects are not free they will be automatically deallocated
  11. // when the internal heap is destroyed by cmFileSysFinalize().
  12. //
  13. //)
  14. #ifndef cmFileSys_h
  15. #define cmFileSys_h
  16. #ifdef __cplusplus
  17. extern "C" {
  18. #endif
  19. //(
  20. // Result codes returned by cmFileSys.h functions
  21. enum
  22. {
  23. kOkFsRC = cmOkRC,
  24. kMemAllocErrFsRC,
  25. kLHeapAllocErrFsRC,
  26. kStatFailFsRC,
  27. kAssertFailFsRC,
  28. kOpenDirFailFsRC,
  29. kFnTooLongFsRC,
  30. kMkDirFailFsRC,
  31. kSysErrFsRC,
  32. kOsxFailFsRC,
  33. kLinuxFailFsRC,
  34. kInvalidDirFsRC
  35. };
  36. typedef cmHandle_t cmFileSysH_t; //< Opaque handle type used by all cmFileSys.h functions
  37. typedef unsigned cmFsRC_t; //< Result code used as the return type by many cmFileSys.h functions.
  38. extern cmFileSysH_t cmFileSysNullHandle; // NULL handle to be used for setting cmFileSysH_t type handles to an explicit uninitialized value.
  39. // Initialize a file system object.
  40. // If *hp was not initalized by an earlier call to cmFileSysInitialize() then it should
  41. // be set to cmFileSysNullHandle prior to calling this function. If *hp is a valid handle
  42. // then it is automatically finalized by an internal call to cmFileSysFinalize() prior to
  43. // being re-iniitalized.
  44. // The appNameStr is used to determine the location of the preference and resource directories
  45. // on some platforms
  46. cmFsRC_t cmFileSysInitialize( cmFileSysH_t* hp, cmCtx_t* ctx, const cmChar_t* appNameStr );
  47. // Finalize a file system object.
  48. // Upon successful completion *hp is set to cmFileSysNullHandle.
  49. cmFsRC_t cmFileSysFinalize( cmFileSysH_t* hp );
  50. // Returns true if the file system handle is active and initialized.
  51. bool cmFileSysIsValid( cmFileSysH_t h );
  52. const cmChar_t* cmFileSysPrefsDir( cmFileSysH_t h ); //< Return the operating system dependent preference data directory for this application.
  53. const cmChar_t* cmFileSysRsrcDir( cmFileSysH_t h ); //< Return the operating system dependent application resource directory for this application.
  54. const cmChar_t* cmFileSysUserDir( cmFileSysH_t h ); //< Return the operating system dependent user directory for this application.
  55. // Test the type of a file system object:
  56. //
  57. bool cmFileSysIsDir( cmFileSysH_t h, const cmChar_t* dirStr ); //< Return true if 'dirStr' refers to an existing directory.
  58. bool cmFileSysIsFile( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to an existing file.
  59. bool cmFileSysIsLink( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to a symbolic link.
  60. // Create File Names:
  61. //
  62. // Create a file name by concatenating sub-strings.
  63. //
  64. // Variable arg's. entries are directories inserted between
  65. // 'dirPrefixStr' and the file name.
  66. // Terminate var arg's directory list with a NULL.
  67. //
  68. // The returned string is allocated in a local heap maintained by the cmFileSys object.
  69. // The memory used by the string will exist until it is released with cmFileSysFreeFn()
  70. // or the cmFileSys object is finalized.
  71. const cmChar_t* cmFileSysMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  72. // Same as cmFileSysMakeFn with but with a va_list argument to accept the var. args. parameters.
  73. const cmChar_t* cmFileSysVMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  74. // Release the file name created through an earlier call to cmFileSysMakeFn().
  75. void cmFileSysFreeFn( cmFileSysH_t h, const cmChar_t* fn );
  76. // Create a directory - where the entire path already exists except for the
  77. // final directory.
  78. cmFsRC_t cmFileSysMkDir( cmFileSysH_t h, const cmChar_t* dir );
  79. // Create a complete directory path - where any of the path segments may
  80. // not already exist.
  81. cmFsRC_t cmFileSysMkDirAll( cmFileSysH_t h, const cmChar_t* dir );
  82. // Parse a path into its parts:
  83. //
  84. // Return record used by cmFileSysParts()
  85. typedef struct
  86. {
  87. const cmChar_t* dirStr;
  88. const cmChar_t* fnStr;
  89. const cmChar_t* extStr;
  90. } cmFileSysPathPart_t;
  91. // Given a file name decompose it into a directory string, file name string and file extension string.
  92. // The cmFileSysPathPart_t record and the memory used by the strings that it references
  93. // are allocated from a local heap maintained by the cmFileSys object. This memory will exist
  94. // until it is released with cmFileSysFreePathParts() or the cmFileSysH_t handle is finalized.
  95. cmFileSysPathPart_t* cmFileSysPathParts( cmFileSysH_t h, const cmChar_t* pathNameStr );
  96. // Free the memory associated with a cmFileSysPathPart_t record returned from an eariler call to cmFileSysPathParts().
  97. void cmFileSysFreePathParts( cmFileSysH_t h, cmFileSysPathPart_t* p );
  98. // Return the parts of a directory path as an array of strings.
  99. // The last element in the array is set to NULL to mark the end of the array.
  100. // Note that all '/' separator characters are removed from the result with
  101. // the exception of the first one - which denotes the root directory.
  102. // The returned array is allocated from the file systems internal heap and will
  103. // be automatically released when the file system is closed by cmFileSysDestroy().
  104. // The caller may optionally release the array memory with a call to
  105. // cmFileSysFreeDirParts().
  106. cmChar_t** cmFileSysDirParts( cmFileSysH_t h, const cmChar_t* dirStr );
  107. void cmFileSysFreeDirParts( cmFileSysH_t h, cmChar_t** dirStrArray );
  108. // Return the count of elements in a directory parts array as returned by
  109. // cmFileSysDirParts().
  110. unsigned cmFileSysDirPartsCount(cmFileSysH_t h, cmChar_t** dirStrArray );
  111. // Form a directory string from a NULL terminated array of strings.
  112. // If the first element in the array is set to '/' then the
  113. // resulting directory will be absolute rather than relative.
  114. // The returned string is allocated from the file systems internal heap and will
  115. // be automatically released when the file system is closed by cmFileSysDestroy().
  116. // The caller may optionally release the array memory with a call to
  117. // cmFileSysFreeDir().
  118. cmChar_t* cmFileSysFormDir( cmFileSysH_t h, cmChar_t** dirStrArray, unsigned n );
  119. void cmFileSysFreeDir( cmFileSysH_t h, const cmChar_t* dir );
  120. // Walk a directory tree:
  121. //
  122. // Flags used by cmFileSysDirEntries 'includeFlags' parameter.
  123. enum
  124. {
  125. kFileFsFl = 0x01, //< include all visible files
  126. kDirFsFl = 0x02, //< include all visible directory
  127. kInvisibleFsFl = 0x04, //< include file/dir name beginning with a '.'
  128. kCurDirFsFl = 0x08, //< include '.' directory
  129. kParentDirFsFl = 0x10, //< include '..' directory
  130. kAllFsFl = 0x1f, //< all type flags
  131. kFullPathFsFl = 0x40, //< return the full path in the 'name' field of cmFileSysDirEntry_t;
  132. kRecurseFsFl = 0x80 //< recurse into directories
  133. };
  134. // The return type for cmFileSysDirEntries().
  135. typedef struct
  136. {
  137. unsigned flags; //< Entry type flags from kXXXFsFl.
  138. const cmChar_t* name; //< Entry name or full path depending on kFullPathFsFl.
  139. } cmFileSysDirEntry_t;
  140. // Return the file and directory names contained in a given subdirectory.
  141. //
  142. // Set 'includeFlags' with the kXXXFsFl flags of the files to include in the returned
  143. // directory entry array. The value pointed to by dirEntryCntPtr will be set to the
  144. // number of records in the returned array.
  145. cmFileSysDirEntry_t* cmFileSysDirEntries( cmFileSysH_t h, const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
  146. // Release the memory assoicated with a cmFileSysDirEntry_t array returned from an earlier call to cmFileSysDirEntries().
  147. void cmFileSysDirFreeEntries( cmFileSysH_t h, cmFileSysDirEntry_t* p );
  148. // Return the last error code generated by the file system.
  149. cmFsRC_t cmFileSysErrorCode( cmFileSysH_t h );
  150. //-------------------------------------------------------------------------------------------------
  151. // Global file system functions:
  152. // These functions work using a global cmFileSysH created by cmFsInitialize().
  153. // The functions are otherwise just wrappers for the same named function above.
  154. cmFsRC_t cmFsInitialize( cmCtx_t* ctx, const cmChar_t* appNameStr );
  155. cmFsRC_t cmFsFinalize();
  156. const cmChar_t* cmFsPrefsDir();
  157. const cmChar_t* cmFsRsrcDir();
  158. const cmChar_t* cmFsUserDir();
  159. bool cmFsIsDir( const cmChar_t* dirStr );
  160. bool cmFsIsFile( const cmChar_t* fnStr );
  161. bool cmFsIsLink( const cmChar_t* fnStr );
  162. const cmChar_t* cmFsVMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  163. const cmChar_t* cmFsMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  164. void cmFsFreeFn( const cmChar_t* fn );
  165. cmFsRC_t cmFsMkDir( const cmChar_t* dir );
  166. cmFsRC_t cmFsMkDirAll( const cmChar_t* dir );
  167. cmFileSysPathPart_t* cmFsPathParts( const cmChar_t* pathNameStr );
  168. void cmFsFreePathParts( cmFileSysPathPart_t* p );
  169. cmChar_t** cmFsDirParts( const cmChar_t* dirStr );
  170. void cmFsFreeDirParts( cmChar_t** dirStrArray );
  171. unsigned cmFsDirPartsCount( cmChar_t** dirStrArray );
  172. cmChar_t* cmFsFormDir( cmChar_t** dirStrArray, unsigned n );
  173. void cmFsFreeDir( const cmChar_t* dir );
  174. cmFileSysDirEntry_t* cmFsDirEntries( const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
  175. void cmFsDirFreeEntries( cmFileSysDirEntry_t* p );
  176. cmFsRC_t cmFsErrorCode();
  177. // Test and example function to demonstrate the use of the functions in cmFileSys.h
  178. cmFsRC_t cmFileSysTest( cmCtx_t* ctx );
  179. //)
  180. //}
  181. #ifdef __cplusplus
  182. }
  183. #endif
  184. #endif