interface/ffile.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ffile.h
   3 // Purpose:     interface of wxFFile
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10
  11 /**
  12     Values used for both wxFile and wxFFile.
  13
  14     @todo make the value names uppercase
  15 */
  16 enum wxSeekMode
  17 {
  18   wxFromStart,
  19   wxFromCurrent,
  20   wxFromEnd
  21 };
  22
  23 /**
  24     See wxFFile::GetKind().
  25 */
  26 enum wxFileKind
  27 {
  28   wxFILE_KIND_UNKNOWN,
  29   wxFILE_KIND_DISK,     /**< A file supporting seeking to arbitrary offsets. */
  30   wxFILE_KIND_TERMINAL, /**< A terminal. */
  31   wxFILE_KIND_PIPE      /**< A pipe. */
  32 };
  33
  34
  35 /**
  36     @class wxFFile
  37     @wxheader{ffile.h}
  38
  39     wxFFile implements buffered file I/O.
  40
  41     This is a very small class designed to minimize the overhead of using it - in fact,
  42     there is hardly any overhead at all, but using it brings you automatic error checking
  43     and hides differences between platforms and compilers.
  44
  45     It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio).
  46
  47     @library{wxbase}
  48     @category{file}
  49
  50     @see wxFFile::IsOpened
  51 */
  52 class wxFFile
  53 {
  54 public:
  55     wxFFile();
  56
  57     /**
  58         Opens a file with the given file pointer, which has already been opened.
  59
  60         @param fp
  61             An existing file descriptor, such as stderr.
  62     */
  63     wxFFile(FILE* fp);
  64
  65     /**
  66         Opens a file with the given mode.
  67         As there is no way to return whether the operation was successful or not from
  68         the constructor you should test the return value of IsOpened() to check that it
  69         didn't fail.
  70
  71         @param filename
  72             The filename.
  73         @param mode
  74             The mode in which to open the file using standard C strings.
  75             Note that you should use "b" flag if you use binary files under Windows
  76             or the results might be unexpected due to automatic newline conversion done
  77             for the text files.
  78     */
  79     wxFFile(const wxString& filename, const wxString& mode = "r");
  80
  81
  82     /**
  83         Destructor will close the file.
  84
  85         @note it is not virtual so you should @e not derive from wxFFile!
  86     */
  87     ~wxFFile();
  88
  89     /**
  90         Attaches an existing file pointer to the wxFFile object.
  91
  92         The descriptor should be already opened and it will be closed by wxFFile object.
  93     */
  94     void Attach(FILE* fp);
  95
  96     /**
  97         Closes the file and returns @true on success.
  98     */
  99     bool Close();
 100
 101     /**
 102         Get back a file pointer from wxFFile object -- the caller is responsible for
 103         closing the file if this descriptor is opened.
 104
 105         IsOpened() will return @false after call to Detach().
 106     */
 107     void Detach();
 108
 109     /**
 110         Returns @true if the an attempt has been made to read @e past
 111         the end of the file.
 112
 113         Note that the behaviour of the file descriptor based class  wxFile is different as
 114         wxFile::Eof() will return @true here as soon as the last byte of the file has been read.
 115
 116         Also note that this method may only be called for opened files and may crash if
 117         the file is not opened.
 118
 119         @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
 120
 121         @see IsOpened()
 122     */
 123     bool Eof() const;
 124
 125     /**
 126         Returns @true if an error has occurred on this file, similar to the standard
 127         @c ferror() function.
 128
 129         Please note that this method may only be called for opened files and may crash
 130         if the file is not opened.
 131
 132         @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
 133
 134         @see IsOpened()
 135     */
 136     bool Error() const;
 137
 138     /**
 139         Flushes the file and returns @true on success.
 140     */
 141     bool Flush();
 142
 143     /**
 144         Returns the type of the file.
 145
 146         @see wxFileKind
 147     */
 148     wxFileKind GetKind() const;
 149
 150     /**
 151         Returns @true if the file is opened.
 152
 153         Most of the methods of this class may only be used for an opened file.
 154     */
 155     bool IsOpened() const;
 156
 157     /**
 158         Returns the length of the file.
 159     */
 160     wxFileOffset Length() const;
 161
 162     /**
 163         Opens the file, returning @true if successful.
 164
 165         @param filename
 166             The filename.
 167         @param mode
 168             The mode in which to open the file.
 169     */
 170     bool Open(const wxString& filename, const wxString& mode = "r");
 171
 172     /**
 173         Reads the specified number of bytes into a buffer, returning the actual number read.
 174
 175         @param buffer
 176             A buffer to receive the data.
 177         @param count
 178             The number of bytes to read.
 179
 180         @return The number of bytes read.
 181     */
 182     size_t Read(void* buffer, size_t count);
 183
 184     /**
 185         Reads the entire contents of the file into a string.
 186
 187         @param str
 188             String to read data into.
 189         @param conv
 190             Conversion object to use in Unicode build; by default supposes
 191             that file contents is encoded in UTF-8.
 192
 193         @return @true if file was read successfully, @false otherwise.
 194     */
 195     bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto());
 196
 197     /**
 198         Seeks to the specified position and returns @true on success.
 199
 200         @param ofs
 201             Offset to seek to.
 202         @param mode
 203             One of wxFromStart, wxFromEnd, wxFromCurrent.
 204     */
 205     bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart);
 206
 207     /**
 208         Moves the file pointer to the specified number of bytes before the end of the
 209         file and returns @true on success.
 210
 211         @param ofs
 212             Number of bytes before the end of the file.
 213     */
 214     bool SeekEnd(wxFileOffset ofs = 0);
 215
 216     /**
 217         Returns the current position.
 218     */
 219     wxFileOffset Tell() const;
 220
 221     /**
 222         Writes the contents of the string to the file, returns @true on success.
 223
 224         The second argument is only meaningful in Unicode build of wxWidgets when
 225         @a conv is used to convert @a str to multibyte representation.
 226     */
 227     bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto());
 228
 229     /**
 230         Writes the specified number of bytes from a buffer.
 231
 232         @param buffer
 233             A buffer containing the data.
 234         @param count
 235             The number of bytes to write.
 236
 237         @return The number of bytes written.
 238     */
 239     size_t Write(const void* buffer, size_t count);
 240
 241     /**
 242         Returns the file pointer associated with the file.
 243     */
 244     FILE* fp() const;
 245 };
 246