libcm is a C development framework with an emphasis on audio signal processing applications.
Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

cmFileSys.h 11KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251
  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. kGenFileFailFsRC,
  36. kAccessFailFsRC
  37. };
  38. typedef cmHandle_t cmFileSysH_t; //< Opaque handle type used by all cmFileSys.h functions
  39. typedef unsigned cmFsRC_t; //< Result code used as the return type by many cmFileSys.h functions.
  40. extern cmFileSysH_t cmFileSysNullHandle; // NULL handle to be used for setting cmFileSysH_t type handles to an explicit uninitialized value.
  41. // Initialize a file system object.
  42. // If *hp was not initalized by an earlier call to cmFileSysInitialize() then it should
  43. // be set to cmFileSysNullHandle prior to calling this function. If *hp is a valid handle
  44. // then it is automatically finalized by an internal call to cmFileSysFinalize() prior to
  45. // being re-iniitalized.
  46. // The appNameStr is used to determine the location of the preference and resource directories
  47. // on some platforms
  48. cmFsRC_t cmFileSysInitialize( cmFileSysH_t* hp, cmCtx_t* ctx, const cmChar_t* appNameStr );
  49. // Finalize a file system object.
  50. // Upon successful completion *hp is set to cmFileSysNullHandle.
  51. cmFsRC_t cmFileSysFinalize( cmFileSysH_t* hp );
  52. // Returns true if the file system handle is active and initialized.
  53. bool cmFileSysIsValid( cmFileSysH_t h );
  54. const cmChar_t* cmFileSysAppName( cmFileSysH_t h ); //< Return the application name as passed to cmFileSysInitialize()
  55. const cmChar_t* cmFileSysPrefsDir( cmFileSysH_t h ); //< Return the operating system dependent preference data directory for this application.
  56. const cmChar_t* cmFileSysRsrcDir( cmFileSysH_t h ); //< Return the operating system dependent application resource directory for this application.
  57. const cmChar_t* cmFileSysUserDir( cmFileSysH_t h ); //< Return the operating system dependent user directory for this application.
  58. // Check if a request to create a file will succeed.
  59. bool cmFileSysCanWriteToDir( cmFileSysH_t h, const cmChar_t* dirStr );
  60. // Test the type of a file system object:
  61. //
  62. bool cmFileSysIsDir( cmFileSysH_t h, const cmChar_t* dirStr ); //< Return true if 'dirStr' refers to an existing directory.
  63. bool cmFileSysIsFile( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to an existing file.
  64. bool cmFileSysIsLink( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to a symbolic link.
  65. // Create File Names:
  66. //
  67. // Create a file name by concatenating sub-strings.
  68. //
  69. // Variable arg's. entries are directories inserted between
  70. // 'dirPrefixStr' and the file name.
  71. // Terminate var arg's directory list with a NULL.
  72. //
  73. // The returned string is allocated in a local heap maintained by the cmFileSys object.
  74. // The memory used by the string will exist until it is released with cmFileSysFreeFn()
  75. // or the cmFileSys object is finalized.
  76. const cmChar_t* cmFileSysMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  77. // Same as cmFileSysMakeFn with but with a va_list argument to accept the var. args. parameters.
  78. const cmChar_t* cmFileSysVMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  79. // Release the file name created through an earlier call to cmFileSysMakeFn().
  80. void cmFileSysFreeFn( cmFileSysH_t h, const cmChar_t* fn );
  81. // Generate an unused filename in the directory 'dir' beginning with the prefix 'prefixStr'.
  82. // The returned file name will have the format: <dir>/<prefixStr>nnnn.<extStr> where
  83. // nnn represents 1 or more digits. The returned string must be released with a
  84. // call to cmMemFree().
  85. cmFsRC_t cmFileSysGenFn( cmFileSysH_t h, const cmChar_t* dir, const cmChar_t* prefixStr, const cmChar_t* extStr, const cmChar_t** fnPtr );
  86. // Create a directory - where the entire path already exists except for the
  87. // final directory.
  88. cmFsRC_t cmFileSysMkDir( cmFileSysH_t h, const cmChar_t* dir );
  89. // Create a complete directory path - where any of the path segments may
  90. // not already exist.
  91. cmFsRC_t cmFileSysMkDirAll( cmFileSysH_t h, const cmChar_t* dir );
  92. // Parse a path into its parts:
  93. //
  94. // Return record used by cmFileSysParts()
  95. typedef struct
  96. {
  97. const cmChar_t* dirStr;
  98. const cmChar_t* fnStr;
  99. const cmChar_t* extStr;
  100. } cmFileSysPathPart_t;
  101. // Given a file name decompose it into a directory string, file name string and file extension string.
  102. // The cmFileSysPathPart_t record and the memory used by the strings that it references
  103. // are allocated from a local heap maintained by the cmFileSys object. This memory will exist
  104. // until it is released with cmFileSysFreePathParts() or the cmFileSysH_t handle is finalized.
  105. cmFileSysPathPart_t* cmFileSysPathParts( cmFileSysH_t h, const cmChar_t* pathNameStr );
  106. // Free the memory associated with a cmFileSysPathPart_t record returned from an eariler call to cmFileSysPathParts().
  107. void cmFileSysFreePathParts( cmFileSysH_t h, cmFileSysPathPart_t* p );
  108. // Return the parts of a directory path as an array of strings.
  109. // The last element in the array is set to NULL to mark the end of the array.
  110. // Note that all '/' separator characters are removed from the result with
  111. // the exception of the first one - which denotes the root directory.
  112. // The returned array is allocated from the file systems internal heap and will
  113. // be automatically released when the file system is closed by cmFileSysDestroy().
  114. // The caller may optionally release the array memory with a call to
  115. // cmFileSysFreeDirParts().
  116. cmChar_t** cmFileSysDirParts( cmFileSysH_t h, const cmChar_t* dirStr );
  117. void cmFileSysFreeDirParts( cmFileSysH_t h, cmChar_t** dirStrArray );
  118. // Return the count of elements in a directory parts array as returned by
  119. // cmFileSysDirParts().
  120. unsigned cmFileSysDirPartsCount(cmFileSysH_t h, cmChar_t** dirStrArray );
  121. // Form a directory string from a NULL terminated array of strings.
  122. // If the first element in the array is set to '/' then the
  123. // resulting directory will be absolute rather than relative.
  124. // The returned string is allocated from the file systems internal heap and will
  125. // be automatically released when the file system is closed by cmFileSysDestroy().
  126. // The caller may optionally release the array memory with a call to
  127. // cmFileSysFreeDir().
  128. cmChar_t* cmFileSysFormDir( cmFileSysH_t h, cmChar_t** dirStrArray, unsigned n );
  129. void cmFileSysFreeDir( cmFileSysH_t h, const cmChar_t* dir );
  130. // Walk a directory tree:
  131. //
  132. // Flags used by cmFileSysDirEntries 'includeFlags' parameter.
  133. enum
  134. {
  135. kFileFsFl = 0x001, //< include all visible files
  136. kDirFsFl = 0x002, //< include all visible directory
  137. kLinkFsFl = 0x004, //< include all symbolic links
  138. kInvisibleFsFl = 0x008, //< include file/dir name beginning with a '.'
  139. kCurDirFsFl = 0x010, //< include '.' directory
  140. kParentDirFsFl = 0x020, //< include '..' directory
  141. kAllFsFl = 0x02f, //< all type flags
  142. kFullPathFsFl = 0x040, //< return the full path in the 'name' field of cmFileSysDirEntry_t;
  143. kRecurseFsFl = 0x080, //< recurse into directories
  144. kRecurseLinksFsFl = 0x100 //< recurse into symbol link directories
  145. };
  146. // The return type for cmFileSysDirEntries().
  147. typedef struct
  148. {
  149. unsigned flags; //< Entry type flags from kXXXFsFl.
  150. const cmChar_t* name; //< Entry name or full path depending on kFullPathFsFl.
  151. } cmFileSysDirEntry_t;
  152. // Return the file and directory names contained in a given subdirectory.
  153. //
  154. // Set 'includeFlags' with the kXXXFsFl flags of the files to include in the returned
  155. // directory entry array. The value pointed to by dirEntryCntPtr will be set to the
  156. // number of records in the returned array.
  157. cmFileSysDirEntry_t* cmFileSysDirEntries( cmFileSysH_t h, const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
  158. // Release the memory assoicated with a cmFileSysDirEntry_t array returned from an earlier call to cmFileSysDirEntries().
  159. void cmFileSysDirFreeEntries( cmFileSysH_t h, cmFileSysDirEntry_t* p );
  160. // Return the last error code generated by the file system.
  161. cmFsRC_t cmFileSysErrorCode( cmFileSysH_t h );
  162. //-------------------------------------------------------------------------------------------------
  163. // Global file system functions:
  164. // These functions work using a global cmFileSysH created by cmFsInitialize().
  165. // The functions are otherwise just wrappers for the same named function above.
  166. cmFsRC_t cmFsInitialize( cmCtx_t* ctx, const cmChar_t* appNameStr );
  167. cmFsRC_t cmFsFinalize();
  168. const cmChar_t* cmFsAppName();
  169. const cmChar_t* cmFsPrefsDir();
  170. const cmChar_t* cmFsRsrcDir();
  171. const cmChar_t* cmFsUserDir();
  172. bool cmFsCanWriteToDir( const cmChar_t* dirStr );
  173. bool cmFsIsDir( const cmChar_t* dirStr );
  174. bool cmFsIsFile( const cmChar_t* fnStr );
  175. bool cmFsIsLink( const cmChar_t* fnStr );
  176. const cmChar_t* cmFsVMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl );
  177. const cmChar_t* cmFsMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... );
  178. void cmFsFreeFn( const cmChar_t* fn );
  179. cmFsRC_t cmFsGenFn( const cmChar_t* dir, const cmChar_t* prefixStr, const cmChar_t* extStr, const cmChar_t** fnPtr );
  180. cmFsRC_t cmFsMkDir( const cmChar_t* dir );
  181. cmFsRC_t cmFsMkDirAll( const cmChar_t* dir );
  182. cmFileSysPathPart_t* cmFsPathParts( const cmChar_t* pathNameStr );
  183. void cmFsFreePathParts( cmFileSysPathPart_t* p );
  184. cmChar_t** cmFsDirParts( const cmChar_t* dirStr );
  185. void cmFsFreeDirParts( cmChar_t** dirStrArray );
  186. unsigned cmFsDirPartsCount( cmChar_t** dirStrArray );
  187. cmChar_t* cmFsFormDir( cmChar_t** dirStrArray, unsigned n );
  188. void cmFsFreeDir( const cmChar_t* dir );
  189. cmFileSysDirEntry_t* cmFsDirEntries( const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr );
  190. void cmFsDirFreeEntries( cmFileSysDirEntry_t* p );
  191. cmFsRC_t cmFsErrorCode();
  192. // Test and example function to demonstrate the use of the functions in cmFileSys.h
  193. cmFsRC_t cmFileSysTest( cmCtx_t* ctx );
  194. //)
  195. //}
  196. #ifdef __cplusplus
  197. }
  198. #endif
  199. #endif