libcm is a C development framework with an emphasis on audio signal processing applications.
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

cmFile.h 8.4KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203
  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. };
  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. };
  42. // Open or create a file.
  43. // Equivalent to fopen().
  44. // If *hp was not initalized by an earlier call to cmFileOpen() then it should
  45. // be set to cmFileNullHandle prior to calling this function. If *hp is a valid handle
  46. // then it is automatically finalized by an internal call to cmFileClose() prior to
  47. // being re-iniitalized.
  48. cmFileRC_t cmFileOpen(
  49. cmFileH_t* hp, // Pointer to a client supplied cmFileHandle_t to recieve the handle for the new object.
  50. const cmChar_t* fn, // The name of the file to open or create.
  51. enum cmFileOpenFlags_t flags, // See cmFileOpenFlags_t
  52. cmRpt_t* rpt // The cmRpt_t to use for error reporting
  53. );
  54. // Close a file opened with Equivalent to fclose().
  55. cmFileRC_t cmFileClose( cmFileH_t* hp );
  56. // Return true if the file handle is associated with an open file.
  57. bool cmFileIsValid( cmFileH_t h );
  58. // Read a block bytes from a file. Equivalent to fread().
  59. cmFileRC_t cmFileRead( cmFileH_t h, void* buf, unsigned bufByteCnt );
  60. // Write a block of bytes to a file. Equivalent to fwrite().
  61. cmFileRC_t cmFileWrite( cmFileH_t h, const void* buf, unsigned bufByteCnt );
  62. enum cmFileSeekFlags_t
  63. {
  64. kBeginFileFl = 0x01,
  65. kCurFileFl = 0x02,
  66. kEndFileFl = 0x04
  67. };
  68. // Set the file position indicator. Equivalent to fseek().
  69. cmFileRC_t cmFileSeek( cmFileH_t h, enum cmFileSeekFlags_t flags, int offsByteCnt );
  70. // Return the file position indicator. Equivalent to ftell().
  71. cmFileRC_t cmFileTell( cmFileH_t h, long* offsPtr );
  72. // Return true if the file position indicator is at the end of the file.
  73. // Equivalent to feof().
  74. bool cmFileEof( cmFileH_t h );
  75. // Return the length of the file in bytes
  76. unsigned cmFileByteCount( cmFileH_t h );
  77. // Return the file name associated with a file handle.
  78. const cmChar_t* cmFileName( cmFileH_t h );
  79. // Write a buffer to a file.
  80. cmFileRC_t cmFileFnWrite( const cmChar_t* fn, cmRpt_t* rpt, const void* buf, unsigned bufByteCnt );
  81. // Allocate and fill a buffer from the file.
  82. // Set *bufByteCntPtr to count of bytes read into the buffer.
  83. // 'bufByteCntPtr' is optional - set it to NULL if it is not required by the caller.
  84. // It is the callers responsibility to delete the returned buffer with a
  85. // call to cmMemFree()
  86. cmChar_t* cmFileToBuf( cmFileH_t h, unsigned* bufByteCntPtr );
  87. // Same as cmFileToBuf() but accepts a file name argument.
  88. // 'rpt' is the report object to use for error reporting.
  89. cmChar_t* cmFileFnToBuf( const cmChar_t* fn, cmRpt_t* rpt, unsigned* bufByteCntPtr );
  90. // Allocate and fill a zero terminated string from a file.
  91. // Set *bufByteCntPtr to count of bytes read into the buffer.=
  92. // (the buffer memory size is one byte larger to account for the terminating zero)
  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* cmFileToStr( 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* cmFileFnToStr( const cmChar_t* fn, cmRpt_t* rpt, unsigned* bufByteCntPtr );
  100. // Return the count of lines in a file.
  101. cmFileRC_t cmFileLineCount( cmFileH_t h, unsigned* lineCntPtr );
  102. // Read the next line into buf[bufByteCnt].
  103. // Consider using cmFileGetLineAuto() as an alternative to this function
  104. // to avoid having to use a buffer with an explicit size.
  105. //
  106. // If buf is not long enough to hold the entire string then
  107. //
  108. // 1. The function returns kFileBufTooSmallRC
  109. // 2. *bufByteCntPtr is set to the size of the required buffer.
  110. // 3. The internal file position is left unchanged.
  111. //
  112. // If the buffer is long enough to hold the entire line then
  113. // *bufByteCntPtr is left unchanged.
  114. // See cmFileGetLineTest() in cmProcTest.c or cmFileGetLineAuto()
  115. // in cmFile.c for examples of how to use this function to a
  116. // achieve proper buffer sizing.
  117. cmFileRC_t cmFileGetLine( cmFileH_t h, cmChar_t* buf, unsigned* bufByteCntPtr );
  118. // A version of cmFileGetLine() which eliminates the need to handle buffer
  119. // sizing.
  120. //
  121. // Example usage:
  122. //
  123. // cmChar_t* buf = NULL;
  124. // unsigned bufByteCnt = 0;
  125. // while(cmFileGetLineAuto(h,&buf,&bufByteCnt)==kOkFileRC)
  126. // proc(buf);
  127. // cmMemPtrFree(buf);
  128. //
  129. // On the first call to this function *bufPtrPtr must be set to NULL and
  130. // *bufByteCntPtr must be set to 0.
  131. // Following the last call to this function call cmMemPtrFree(bufPtrptr)
  132. // to be sure the line buffer is fully released. Note this step is not
  133. // neccessary if the last call does not return kOkFileRC.
  134. cmFileRC_t cmFileGetLineAuto( cmFileH_t h, cmChar_t** bufPtrPtr, unsigned* bufByteCntPtr );
  135. // Binary Array Reading Functions
  136. // Each of these functions reads a block of binary data from a file.
  137. // The advantage to using these functions over cmFileRead() is only that they are type specific.
  138. cmFileRC_t cmFileReadChar( cmFileH_t h, char* buf, unsigned cnt );
  139. cmFileRC_t cmFileReadUChar( cmFileH_t h, unsigned char* buf, unsigned cnt );
  140. cmFileRC_t cmFileReadShort( cmFileH_t h, short* buf, unsigned cnt );
  141. cmFileRC_t cmFileReadUShort( cmFileH_t h, unsigned short* buf, unsigned cnt );
  142. cmFileRC_t cmFileReadLong( cmFileH_t h, long* buf, unsigned cnt );
  143. cmFileRC_t cmFileReadULong( cmFileH_t h, unsigned long* buf, unsigned cnt );
  144. cmFileRC_t cmFileReadInt( cmFileH_t h, int* buf, unsigned cnt );
  145. cmFileRC_t cmFileReadUInt( cmFileH_t h, unsigned int* buf, unsigned cnt );
  146. cmFileRC_t cmFileReadFloat( cmFileH_t h, float* buf, unsigned cnt );
  147. cmFileRC_t cmFileReadDouble( cmFileH_t h, double* buf, unsigned cnt );
  148. cmFileRC_t cmFileReadBool( cmFileH_t h, bool* buf, unsigned cnt );
  149. // Binary Array Writing Functions
  150. // Each of these functions writes an array to a binary file.
  151. // The advantage to using functions rather than cmFileWrite() is only that they are type specific.
  152. cmFileRC_t cmFileWriteChar( cmFileH_t h, const char* buf, unsigned cnt );
  153. cmFileRC_t cmFileWriteUChar( cmFileH_t h, const unsigned char* buf, unsigned cnt );
  154. cmFileRC_t cmFileWriteShort( cmFileH_t h, const short* buf, unsigned cnt );
  155. cmFileRC_t cmFileWriteUShort( cmFileH_t h, const unsigned short* buf, unsigned cnt );
  156. cmFileRC_t cmFileWriteLong( cmFileH_t h, const long* buf, unsigned cnt );
  157. cmFileRC_t cmFileWriteULong( cmFileH_t h, const unsigned long* buf, unsigned cnt );
  158. cmFileRC_t cmFileWriteInt( cmFileH_t h, const int* buf, unsigned cnt );
  159. cmFileRC_t cmFileWriteUInt( cmFileH_t h, const unsigned int* buf, unsigned cnt );
  160. cmFileRC_t cmFileWriteFloat( cmFileH_t h, const float* buf, unsigned cnt );
  161. cmFileRC_t cmFileWriteDouble( cmFileH_t h, const double* buf, unsigned cnt );
  162. cmFileRC_t cmFileWriteBool( cmFileH_t h, const bool* buf, unsigned cnt );
  163. // Formatted Text Output Functions:
  164. // Print formatted text to a file.
  165. cmFileRC_t cmFilePrint( cmFileH_t h, const cmChar_t* text );
  166. cmFileRC_t cmFilePrintf( cmFileH_t h, const cmChar_t* fmt, ... );
  167. cmFileRC_t cmFileVPrintf( cmFileH_t h, const cmChar_t* fmt, va_list vl );
  168. //)
  169. //}
  170. #ifdef __cplusplus
  171. }
  172. #endif
  173. #endif