//{ //( // A collection of file system utility functions. // // Note that cmFileSysInitialize() creates an internal cmLHeapH_t based // heap manager from which it allocates memory for some returned objects. // (e.g. cmFileSysMakeFn(), cmFileSysPathParts(), cmFileSysDirEntries()) // Where possible the client can explicitely free these objects via the // provided functions. (e.g. cmFileSysFreeFn(), cmFileSysFreePathParts(), cmFileSysDirFreeEntries()) // However if these objects are not free they will be automatically deallocated // when the internal heap is destroyed by cmFileSysFinalize(). // //) #ifndef cmFileSys_h #define cmFileSys_h #ifdef __cplusplus extern "C" { #endif //( // Result codes returned by cmFileSys.h functions enum { kOkFsRC = cmOkRC, kMemAllocErrFsRC, kLHeapAllocErrFsRC, kStatFailFsRC, kAssertFailFsRC, kOpenDirFailFsRC, kFnTooLongFsRC, kMkDirFailFsRC, kSysErrFsRC, kOsxFailFsRC, kLinuxFailFsRC, kInvalidDirFsRC }; typedef cmHandle_t cmFileSysH_t; //< Opaque handle type used by all cmFileSys.h functions typedef unsigned cmFsRC_t; //< Result code used as the return type by many cmFileSys.h functions. extern cmFileSysH_t cmFileSysNullHandle; // NULL handle to be used for setting cmFileSysH_t type handles to an explicit uninitialized value. // Initialize a file system object. // If *hp was not initalized by an earlier call to cmFileSysInitialize() then it should // be set to cmFileSysNullHandle prior to calling this function. If *hp is a valid handle // then it is automatically finalized by an internal call to cmFileSysFinalize() prior to // being re-iniitalized. // The appNameStr is used to determine the location of the preference and resource directories // on some platforms cmFsRC_t cmFileSysInitialize( cmFileSysH_t* hp, cmCtx_t* ctx, const cmChar_t* appNameStr ); // Finalize a file system object. // Upon successful completion *hp is set to cmFileSysNullHandle. cmFsRC_t cmFileSysFinalize( cmFileSysH_t* hp ); // Returns true if the file system handle is active and initialized. bool cmFileSysIsValid( cmFileSysH_t h ); const cmChar_t* cmFileSysAppName( cmFileSysH_t h ); //< Return the application name as passed to cmFileSysInitialize() const cmChar_t* cmFileSysPrefsDir( cmFileSysH_t h ); //< Return the operating system dependent preference data directory for this application. const cmChar_t* cmFileSysRsrcDir( cmFileSysH_t h ); //< Return the operating system dependent application resource directory for this application. const cmChar_t* cmFileSysUserDir( cmFileSysH_t h ); //< Return the operating system dependent user directory for this application. // Test the type of a file system object: // bool cmFileSysIsDir( cmFileSysH_t h, const cmChar_t* dirStr ); //< Return true if 'dirStr' refers to an existing directory. bool cmFileSysIsFile( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to an existing file. bool cmFileSysIsLink( cmFileSysH_t h, const cmChar_t* fnStr ); //< Return true if 'fnStr' refers to a symbolic link. // Create File Names: // // Create a file name by concatenating sub-strings. // // Variable arg's. entries are directories inserted between // 'dirPrefixStr' and the file name. // Terminate var arg's directory list with a NULL. // // The returned string is allocated in a local heap maintained by the cmFileSys object. // The memory used by the string will exist until it is released with cmFileSysFreeFn() // or the cmFileSys object is finalized. const cmChar_t* cmFileSysMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... ); // Same as cmFileSysMakeFn with but with a va_list argument to accept the var. args. parameters. const cmChar_t* cmFileSysVMakeFn( cmFileSysH_t h, const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl ); // Release the file name created through an earlier call to cmFileSysMakeFn(). void cmFileSysFreeFn( cmFileSysH_t h, const cmChar_t* fn ); // Create a directory - where the entire path already exists except for the // final directory. cmFsRC_t cmFileSysMkDir( cmFileSysH_t h, const cmChar_t* dir ); // Create a complete directory path - where any of the path segments may // not already exist. cmFsRC_t cmFileSysMkDirAll( cmFileSysH_t h, const cmChar_t* dir ); // Parse a path into its parts: // // Return record used by cmFileSysParts() typedef struct { const cmChar_t* dirStr; const cmChar_t* fnStr; const cmChar_t* extStr; } cmFileSysPathPart_t; // Given a file name decompose it into a directory string, file name string and file extension string. // The cmFileSysPathPart_t record and the memory used by the strings that it references // are allocated from a local heap maintained by the cmFileSys object. This memory will exist // until it is released with cmFileSysFreePathParts() or the cmFileSysH_t handle is finalized. cmFileSysPathPart_t* cmFileSysPathParts( cmFileSysH_t h, const cmChar_t* pathNameStr ); // Free the memory associated with a cmFileSysPathPart_t record returned from an eariler call to cmFileSysPathParts(). void cmFileSysFreePathParts( cmFileSysH_t h, cmFileSysPathPart_t* p ); // Return the parts of a directory path as an array of strings. // The last element in the array is set to NULL to mark the end of the array. // Note that all '/' separator characters are removed from the result with // the exception of the first one - which denotes the root directory. // The returned array is allocated from the file systems internal heap and will // be automatically released when the file system is closed by cmFileSysDestroy(). // The caller may optionally release the array memory with a call to // cmFileSysFreeDirParts(). cmChar_t** cmFileSysDirParts( cmFileSysH_t h, const cmChar_t* dirStr ); void cmFileSysFreeDirParts( cmFileSysH_t h, cmChar_t** dirStrArray ); // Return the count of elements in a directory parts array as returned by // cmFileSysDirParts(). unsigned cmFileSysDirPartsCount(cmFileSysH_t h, cmChar_t** dirStrArray ); // Form a directory string from a NULL terminated array of strings. // If the first element in the array is set to '/' then the // resulting directory will be absolute rather than relative. // The returned string is allocated from the file systems internal heap and will // be automatically released when the file system is closed by cmFileSysDestroy(). // The caller may optionally release the array memory with a call to // cmFileSysFreeDir(). cmChar_t* cmFileSysFormDir( cmFileSysH_t h, cmChar_t** dirStrArray, unsigned n ); void cmFileSysFreeDir( cmFileSysH_t h, const cmChar_t* dir ); // Walk a directory tree: // // Flags used by cmFileSysDirEntries 'includeFlags' parameter. enum { kFileFsFl = 0x01, //< include all visible files kDirFsFl = 0x02, //< include all visible directory kInvisibleFsFl = 0x04, //< include file/dir name beginning with a '.' kCurDirFsFl = 0x08, //< include '.' directory kParentDirFsFl = 0x10, //< include '..' directory kAllFsFl = 0x1f, //< all type flags kFullPathFsFl = 0x40, //< return the full path in the 'name' field of cmFileSysDirEntry_t; kRecurseFsFl = 0x80 //< recurse into directories }; // The return type for cmFileSysDirEntries(). typedef struct { unsigned flags; //< Entry type flags from kXXXFsFl. const cmChar_t* name; //< Entry name or full path depending on kFullPathFsFl. } cmFileSysDirEntry_t; // Return the file and directory names contained in a given subdirectory. // // Set 'includeFlags' with the kXXXFsFl flags of the files to include in the returned // directory entry array. The value pointed to by dirEntryCntPtr will be set to the // number of records in the returned array. cmFileSysDirEntry_t* cmFileSysDirEntries( cmFileSysH_t h, const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr ); // Release the memory assoicated with a cmFileSysDirEntry_t array returned from an earlier call to cmFileSysDirEntries(). void cmFileSysDirFreeEntries( cmFileSysH_t h, cmFileSysDirEntry_t* p ); // Return the last error code generated by the file system. cmFsRC_t cmFileSysErrorCode( cmFileSysH_t h ); //------------------------------------------------------------------------------------------------- // Global file system functions: // These functions work using a global cmFileSysH created by cmFsInitialize(). // The functions are otherwise just wrappers for the same named function above. cmFsRC_t cmFsInitialize( cmCtx_t* ctx, const cmChar_t* appNameStr ); cmFsRC_t cmFsFinalize(); const cmChar_t* cmFsAppName(); const cmChar_t* cmFsPrefsDir(); const cmChar_t* cmFsRsrcDir(); const cmChar_t* cmFsUserDir(); bool cmFsIsDir( const cmChar_t* dirStr ); bool cmFsIsFile( const cmChar_t* fnStr ); bool cmFsIsLink( const cmChar_t* fnStr ); const cmChar_t* cmFsVMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, va_list vl ); const cmChar_t* cmFsMakeFn( const cmChar_t* dirPrefix, const cmChar_t* fn, const cmChar_t* ext, ... ); void cmFsFreeFn( const cmChar_t* fn ); cmFsRC_t cmFsMkDir( const cmChar_t* dir ); cmFsRC_t cmFsMkDirAll( const cmChar_t* dir ); cmFileSysPathPart_t* cmFsPathParts( const cmChar_t* pathNameStr ); void cmFsFreePathParts( cmFileSysPathPart_t* p ); cmChar_t** cmFsDirParts( const cmChar_t* dirStr ); void cmFsFreeDirParts( cmChar_t** dirStrArray ); unsigned cmFsDirPartsCount( cmChar_t** dirStrArray ); cmChar_t* cmFsFormDir( cmChar_t** dirStrArray, unsigned n ); void cmFsFreeDir( const cmChar_t* dir ); cmFileSysDirEntry_t* cmFsDirEntries( const cmChar_t* dirStr, unsigned includeFlags, unsigned* dirEntryCntPtr ); void cmFsDirFreeEntries( cmFileSysDirEntry_t* p ); cmFsRC_t cmFsErrorCode(); // Test and example function to demonstrate the use of the functions in cmFileSys.h cmFsRC_t cmFileSysTest( cmCtx_t* ctx ); //) //} #ifdef __cplusplus } #endif #endif