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.

cmFile.h 11KB

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