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 10KB

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