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