libcm is a C development framework with an emphasis on audio signal processing applications.
Вы не можете выбрать более 25 тем Темы должны начинаться с буквы или цифры, могут содержать дефисы(-) и должны содержать не более 35 символов.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. #ifndef cmFile_h
  2. #define cmFile_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. //( { file_desc: "File abstraction class." kw:[file system base]}
  7. //
  8. // The cmFile API extends the C standard file handling routines
  9. // with cm style error handling. All cm file input and output occurs
  10. // through this interface."
  11. //
  12. enum
  13. {
  14. kOkFileRC = cmOkRC,
  15. kInvalidFlagFileRC,
  16. kOpenFailFileRC,
  17. kCloseFailFileRC,
  18. kReadFailFileRC,
  19. kWriteFailFileRC,
  20. kSeekFailFileRC,
  21. kTellFailFileRC,
  22. kPrintFailFileRC,
  23. kObjAllocFailFileRC,
  24. kHandleInvalidFileRC,
  25. kStatFailFileRC,
  26. kBufAllocFailFileRC,
  27. kBufTooSmallFileRC,
  28. kFileSysFailFileRC,
  29. };
  30. typedef unsigned cmFileRC_t;
  31. typedef cmHandle_t cmFileH_t;
  32. extern cmFileH_t cmFileNullHandle;
  33. // Flags for use with cmFileOpen().
  34. enum cmFileOpenFlags_t
  35. {
  36. kReadFileFl = 0x01, //< Open a file for reading
  37. kWriteFileFl = 0x02, //< Create an empty file for writing
  38. kAppendFileFl = 0x04, //< Open a file for writing at the end of the file.
  39. kUpdateFileFl = 0x08, //< Open a file for reading and writing.
  40. kBinaryFileFl = 0x10, //< Open a file for binary (not text) input/output.
  41. kStdoutFileFl = 0x20, //< Ignore fn use 'stdout'
  42. kStderrFileFl = 0x40, //< Ignore fn use 'stderr'
  43. kStdinFileFl = 0x80, //< Ignore fn use 'stdin'
  44. };
  45. // Open or create a file.
  46. // Equivalent to fopen().
  47. // If *hp was not initalized by an earlier call to cmFileOpen() then it should
  48. // be set to cmFileNullHandle prior to calling this function. If *hp is a valid handle
  49. // then it is automatically finalized by an internal call to cmFileClose() prior to
  50. // being re-iniitalized.
  51. //
  52. // If kStdoutFileFl, kStderrFileFl or kStdinFileFl are set then
  53. // file name argument 'fn' is ignored.
  54. cmFileRC_t cmFileOpen(
  55. cmFileH_t* hp, // Pointer to a client supplied cmFileHandle_t to recieve the handle for the new object.
  56. const cmChar_t* fn, // The name of the file to open or create.
  57. enum cmFileOpenFlags_t flags, // See cmFileOpenFlags_t
  58. cmRpt_t* rpt // The cmRpt_t to use for error reporting
  59. );
  60. // Close a file opened with Equivalent to fclose().
  61. cmFileRC_t cmFileClose( cmFileH_t* hp );
  62. // Return true if the file handle is associated with an open file.
  63. bool cmFileIsValid( cmFileH_t h );
  64. // Read a block bytes from a file. Equivalent to fread().
  65. cmFileRC_t cmFileRead( cmFileH_t h, void* buf, unsigned bufByteCnt );
  66. // Write a block of bytes to a file. Equivalent to fwrite().
  67. cmFileRC_t cmFileWrite( cmFileH_t h, const void* buf, unsigned bufByteCnt );
  68. enum cmFileSeekFlags_t
  69. {
  70. kBeginFileFl = 0x01,
  71. kCurFileFl = 0x02,
  72. kEndFileFl = 0x04
  73. };
  74. // Set the file position indicator. Equivalent to fseek().
  75. cmFileRC_t cmFileSeek( cmFileH_t h, enum cmFileSeekFlags_t flags, int offsByteCnt );
  76. // Return the file position indicator. Equivalent to ftell().
  77. cmFileRC_t cmFileTell( cmFileH_t h, long* offsPtr );
  78. // Return true if the file position indicator is at the end of the file.
  79. // Equivalent to feof().
  80. bool cmFileEof( cmFileH_t h );
  81. // Return the length of the file in bytes
  82. unsigned cmFileByteCount( cmFileH_t h );
  83. cmFileRC_t cmFileByteCountFn( const cmChar_t* fn, cmRpt_t* rpt, unsigned* fileByteCntPtr );
  84. // Set *isEqualPtr=true if the two files are identical.
  85. cmFileRC_t cmFileCompare( const cmChar_t* fn0, const cmChar_t* fn1, cmRpt_t* rpt, bool* isEqualFlPtr );
  86. // Return the file name associated with a file handle.
  87. const cmChar_t* cmFileName( cmFileH_t h );
  88. // Write a buffer to a file.
  89. cmFileRC_t cmFileFnWrite( const cmChar_t* fn, cmRpt_t* rpt, const void* buf, unsigned bufByteCnt );
  90. // Allocate and fill a buffer from the file.
  91. // Set *bufByteCntPtr to count of bytes read into the buffer.
  92. // 'bufByteCntPtr' is optional - set it to NULL if it is not required by the caller.
  93. // It is the callers responsibility to delete the returned buffer with a
  94. // call to cmMemFree()
  95. cmChar_t* cmFileToBuf( cmFileH_t h, unsigned* bufByteCntPtr );
  96. // Same as cmFileToBuf() but accepts a file name argument.
  97. // 'rpt' is the report object to use for error reporting.
  98. cmChar_t* cmFileFnToBuf( const cmChar_t* fn, cmRpt_t* rpt, unsigned* bufByteCntPtr );
  99. // Copy the file named in srcDir/srcFn/srcExt to a file named dstDir/dstFn/dstExt.
  100. // Note that srcExt/dstExt may be set to NULL if the file extension is included
  101. // in srcFn/dstFn. Likewise srcFn/dstFn may be set to NULL if the file name
  102. // is included in srcDir/dstDir.
  103. cmFileRC_t cmFileCopy(
  104. const cmChar_t* srcDir,
  105. const cmChar_t* srcFn,
  106. const cmChar_t* srcExt,
  107. const cmChar_t* dstDir,
  108. const cmChar_t* dstFn,
  109. const cmChar_t* dstExt,
  110. cmErr_t* err);
  111. // This function creates a backup copy of the file 'fn' by duplicating it into
  112. // a file named fn_#.ext where # is an integer which makes the file name unique.
  113. // The integers chosen with zero and are incremented until an
  114. // unused file name is found in the same directory as 'fn'.
  115. // If the file identified by 'fn' is not found then the function returns quietly.
  116. cmFileRC_t cmFileBackup( const cmChar_t* dir, const cmChar_t* name, const cmChar_t* ext, cmErr_t* err );
  117. // Allocate and fill a zero terminated string from a file.
  118. // Set *bufByteCntPtr to count of bytes read into the buffer.=
  119. // (the buffer memory size is one byte larger to account for the terminating zero)
  120. // 'bufByteCntPtr' is optional - set it to NULL if it is not required by the caller.
  121. // It is the callers responsibility to delete the returned buffer with a
  122. // call to cmMemFree()
  123. cmChar_t* cmFileToStr( cmFileH_t h, unsigned* bufByteCntPtr );
  124. // Same as cmFileToBuf() but accepts a file name argument.
  125. // 'rpt' is the report object to use for error reporting.
  126. cmChar_t* cmFileFnToStr( const cmChar_t* fn, cmRpt_t* rpt, unsigned* bufByteCntPtr );
  127. // Return the count of lines in a file.
  128. cmFileRC_t cmFileLineCount( cmFileH_t h, unsigned* lineCntPtr );
  129. // Read the next line into buf[bufByteCnt].
  130. // Consider using cmFileGetLineAuto() as an alternative to this function
  131. // to avoid having to use a buffer with an explicit size.
  132. //
  133. // If buf is not long enough to hold the entire string then
  134. //
  135. // 1. The function returns kFileBufTooSmallRC
  136. // 2. *bufByteCntPtr is set to the size of the required buffer.
  137. // 3. The internal file position is left unchanged.
  138. //
  139. // If the buffer is long enough to hold the entire line then
  140. // *bufByteCntPtr is left unchanged.
  141. // See cmFileGetLineTest() in cmProcTest.c or cmFileGetLineAuto()
  142. // in cmFile.c for examples of how to use this function to a
  143. // achieve proper buffer sizing.
  144. cmFileRC_t cmFileGetLine( cmFileH_t h, cmChar_t* buf, unsigned* bufByteCntPtr );
  145. // A version of cmFileGetLine() which eliminates the need to handle buffer
  146. // sizing.
  147. //
  148. // Example usage:
  149. //
  150. // cmChar_t* buf = NULL;
  151. // unsigned bufByteCnt = 0;
  152. // while(cmFileGetLineAuto(h,&buf,&bufByteCnt)==kOkFileRC)
  153. // proc(buf);
  154. // cmMemPtrFree(buf);
  155. //
  156. // On the first call to this function *bufPtrPtr must be set to NULL and
  157. // *bufByteCntPtr must be set to 0.
  158. // Following the last call to this function call cmMemPtrFree(bufPtrptr)
  159. // to be sure the line buffer is fully released. Note this step is not
  160. // neccessary if the last call does not return kOkFileRC.
  161. cmFileRC_t cmFileGetLineAuto( cmFileH_t h, cmChar_t** bufPtrPtr, unsigned* bufByteCntPtr );
  162. // Binary Array Reading Functions
  163. // Each of these functions reads a block of binary data from a file.
  164. // The advantage to using these functions over cmFileRead() is only that they are type specific.
  165. cmFileRC_t cmFileReadChar( cmFileH_t h, char* buf, unsigned cnt );
  166. cmFileRC_t cmFileReadUChar( cmFileH_t h, unsigned char* buf, unsigned cnt );
  167. cmFileRC_t cmFileReadShort( cmFileH_t h, short* buf, unsigned cnt );
  168. cmFileRC_t cmFileReadUShort( cmFileH_t h, unsigned short* buf, unsigned cnt );
  169. cmFileRC_t cmFileReadLong( cmFileH_t h, long* buf, unsigned cnt );
  170. cmFileRC_t cmFileReadULong( cmFileH_t h, unsigned long* buf, unsigned cnt );
  171. cmFileRC_t cmFileReadInt( cmFileH_t h, int* buf, unsigned cnt );
  172. cmFileRC_t cmFileReadUInt( cmFileH_t h, unsigned int* buf, unsigned cnt );
  173. cmFileRC_t cmFileReadFloat( cmFileH_t h, float* buf, unsigned cnt );
  174. cmFileRC_t cmFileReadDouble( cmFileH_t h, double* buf, unsigned cnt );
  175. cmFileRC_t cmFileReadBool( cmFileH_t h, bool* buf, unsigned cnt );
  176. // Binary Array Writing Functions
  177. // Each of these functions writes an array to a binary file.
  178. // The advantage to using functions rather than cmFileWrite() is only that they are type specific.
  179. cmFileRC_t cmFileWriteChar( cmFileH_t h, const char* buf, unsigned cnt );
  180. cmFileRC_t cmFileWriteUChar( cmFileH_t h, const unsigned char* buf, unsigned cnt );
  181. cmFileRC_t cmFileWriteShort( cmFileH_t h, const short* buf, unsigned cnt );
  182. cmFileRC_t cmFileWriteUShort( cmFileH_t h, const unsigned short* buf, unsigned cnt );
  183. cmFileRC_t cmFileWriteLong( cmFileH_t h, const long* buf, unsigned cnt );
  184. cmFileRC_t cmFileWriteULong( cmFileH_t h, const unsigned long* buf, unsigned cnt );
  185. cmFileRC_t cmFileWriteInt( cmFileH_t h, const int* buf, unsigned cnt );
  186. cmFileRC_t cmFileWriteUInt( cmFileH_t h, const unsigned int* buf, unsigned cnt );
  187. cmFileRC_t cmFileWriteFloat( cmFileH_t h, const float* buf, unsigned cnt );
  188. cmFileRC_t cmFileWriteDouble( cmFileH_t h, const double* buf, unsigned cnt );
  189. cmFileRC_t cmFileWriteBool( cmFileH_t h, const bool* buf, unsigned cnt );
  190. // Write a string to a file as <N> <char0> <char1> ... <char(N-1)>
  191. // where N is the count of characters in the string.
  192. cmFileRC_t cmFileWriteStr( cmFileH_t h, const cmChar_t* s );
  193. // Read a string back from a file as written by cmFileWriteStr().
  194. // Note that the string will by string will be dynamically allocated
  195. // and threfore must eventually be released via cmMemFree().
  196. // If maxCharN is set to zero then the default maximum string
  197. // length is 16384. Note that this limit is used to prevent
  198. // corrupt files from generating excessively long strings.
  199. cmFileRC_t cmFileReadStr( cmFileH_t h, cmChar_t** sRef, unsigned maxCharN );
  200. // Formatted Text Output Functions:
  201. // Print formatted text to a file.
  202. cmFileRC_t cmFilePrint( cmFileH_t h, const cmChar_t* text );
  203. cmFileRC_t cmFilePrintf( cmFileH_t h, const cmChar_t* fmt, ... );
  204. cmFileRC_t cmFileVPrintf( cmFileH_t h, const cmChar_t* fmt, va_list vl );
  205. cmFileRC_t cmFileLastRC( cmFileH_t h );
  206. cmFileRC_t cmFileSetRC( cmFileH_t h, cmFileRC_t rc );
  207. //)
  208. #ifdef __cplusplus
  209. }
  210. #endif
  211. #endif