libcm is a C development framework with an emphasis on audio signal processing applications.
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.

cmFileSys.h 11KB

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