interface/wx/ffile.h

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