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