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