interface/ffile.h

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