interface/wx/wfstream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wfstream.h
   3 // Purpose:     interface of wxTempFileOutputStream
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTempFileOutputStream
  11
  12     wxTempFileOutputStream is an output stream based on wxTempFile.
  13     It provides a relatively safe way to replace the contents of the
  14     existing file.
  15
  16     @library{wxbase}
  17     @category{streams}
  18
  19     @see wxTempFile
  20 */
  21 class wxTempFileOutputStream : public wxOutputStream
  22 {
  23 public:
  24     /**
  25         Associates wxTempFileOutputStream with the file to be replaced and opens it.
  26
  27         @warning
  28         You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
  29
  30         Call Commit() or wxOutputStream::Close() to replace the old file and close
  31         this one. Calling Discard() (or allowing the destructor to do it) will
  32         discard the changes.
  33     */
  34     wxTempFileOutputStream(const wxString& fileName);
  35
  36     /**
  37         Validate changes: deletes the old file of the given name and renames the new
  38         file to the old name. Returns @true if both actions succeeded.
  39
  40         If @false is returned it may unfortunately mean two quite different things: either that
  41         either the old file couldn't be deleted or that the new file couldn't be renamed
  42         to the old name.
  43     */
  44     virtual bool Commit();
  45
  46     /**
  47         Discard changes: the old file contents are not changed, the temporary file is
  48         deleted.
  49     */
  50     virtual void Discard();
  51 };
  52
  53
  54
  55 /**
  56     @class wxFFileOutputStream
  57
  58     This class represents data written to a file.
  59     There are actually two such groups of classes: this one is based on wxFFile
  60     whereas wxFileOutputStream is based in the wxFile class.
  61
  62     Note that wxOutputStream::SeekO() can seek beyond the end of the stream
  63     (file) and will thus not return ::wxInvalidOffset for that.
  64
  65     @library{wxbase}
  66     @category{streams}
  67
  68     @see wxBufferedOutputStream, wxFFileInputStream, wxFileOutputStream, wxFileInputStream
  69 */
  70 class wxFFileOutputStream : public wxOutputStream
  71 {
  72 public:
  73     /**
  74         Open the given file @a filename with mode @a mode.
  75
  76         @warning
  77         You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
  78     */
  79     wxFFileOutputStream(const wxString& filename,
  80                         const wxString& mode = "wb");
  81
  82     /**
  83         Initializes a file stream in write-only mode using the file I/O object file.
  84     */
  85     wxFFileOutputStream(wxFFile& file);
  86
  87     /**
  88         Initializes a file stream in write-only mode using the file descriptor fp.
  89     */
  90     wxFFileOutputStream(FILE* fp);
  91
  92     /**
  93         Destructor.
  94     */
  95     virtual ~wxFFileOutputStream();
  96
  97     /**
  98         Returns @true if the stream is initialized and ready.
  99     */
 100     bool IsOk() const;
 101
 102     /**
 103         Returns the underlying file object.
 104         @since 2.9.5
 105     */
 106     wxFFile* GetFile() const;
 107 };
 108
 109
 110
 111 /**
 112     @class wxFileOutputStream
 113
 114     This class represents data written to a file.
 115     There are actually two such groups of classes: this one is based on wxFile
 116     whereas wxFFileOutputStream is based in the wxFFile class.
 117
 118     Note that wxOutputStream::SeekO() can seek beyond the end of the stream
 119     (file) and will thus not return ::wxInvalidOffset for that.
 120
 121     @library{wxbase}
 122     @category{streams}
 123
 124     @see wxBufferedOutputStream, wxFileInputStream, wxFFileOutputStream, wxFFileInputStream
 125 */
 126 class wxFileOutputStream : public wxOutputStream
 127 {
 128 public:
 129     /**
 130         Creates a new file with @a ofileName name and initializes the stream in write-only mode.
 131
 132         @warning
 133         You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
 134     */
 135     wxFileOutputStream(const wxString& ofileName);
 136
 137     /**
 138         Initializes a file stream in write-only mode using the file I/O object file.
 139     */
 140     wxFileOutputStream(wxFile& file);
 141
 142     /**
 143         Initializes a file stream in write-only mode using the file descriptor @e fd.
 144     */
 145     wxFileOutputStream(int fd);
 146
 147     /**
 148         Destructor.
 149     */
 150     virtual ~wxFileOutputStream();
 151
 152     /**
 153         Returns @true if the stream is initialized and ready.
 154     */
 155     bool IsOk() const;
 156
 157     /**
 158         Returns the underlying file object.
 159         @since 2.9.5
 160     */
 161     wxFile* GetFile() const;
 162 };
 163
 164
 165
 166 /**
 167     @class wxFileInputStream
 168
 169     This class represents data read in from a file.
 170     There are actually two such groups of classes: this one is based on wxFile
 171     whereas wxFFileInputStream is based in the wxFFile class.
 172
 173     Note that wxInputStream::SeekI() can seek beyond the end of the stream (file)
 174     and will thus not return ::wxInvalidOffset for that.
 175
 176     @library{wxbase}
 177     @category{streams}
 178
 179     @see wxBufferedInputStream, wxFileOutputStream, wxFFileOutputStream
 180 */
 181 class wxFileInputStream : public wxInputStream
 182 {
 183 public:
 184     /**
 185         Opens the specified file using its @a ifileName name in read-only mode.
 186
 187         @warning
 188         You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
 189     */
 190     wxFileInputStream(const wxString& ifileName);
 191
 192     /**
 193         Initializes a file stream in read-only mode using the file I/O object file.
 194     */
 195     wxFileInputStream(wxFile& file);
 196
 197     /**
 198         Initializes a file stream in read-only mode using the specified file descriptor.
 199     */
 200     wxFileInputStream(int fd);
 201
 202     /**
 203         Destructor.
 204     */
 205     virtual ~wxFileInputStream();
 206
 207     /**
 208         Returns @true if the stream is initialized and ready.
 209     */
 210     bool IsOk() const;
 211
 212     /**
 213         Returns the underlying file object.
 214         @since 2.9.5
 215     */
 216     wxFile* GetFile() const;
 217 };
 218
 219
 220
 221 /**
 222     @class wxFFileInputStream
 223
 224     This class represents data read in from a file.
 225     There are actually two such groups of classes: this one is based on wxFFile
 226     whereas wxFileInputStream is based in the wxFile class.
 227
 228     Note that wxInputStream::SeekI() can seek beyond the end of the stream (file)
 229     and will thus not return ::wxInvalidOffset for that.
 230
 231     @library{wxbase}
 232     @category{streams}
 233
 234     @see wxBufferedInputStream, wxFFileOutputStream, wxFileOutputStream
 235 */
 236 class wxFFileInputStream : public wxInputStream
 237 {
 238 public:
 239     /**
 240         Opens the specified file using its @a filename name using the specified @a mode.
 241
 242         @warning
 243         You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
 244     */
 245     wxFFileInputStream(const wxString& filename,
 246                        const wxString& mode = "rb");
 247
 248     /**
 249         Initializes a file stream in read-only mode using the file I/O object file.
 250     */
 251     wxFFileInputStream(wxFFile& file);
 252
 253     /**
 254         Initializes a file stream in read-only mode using the specified file pointer @a fp.
 255     */
 256     wxFFileInputStream(FILE* fp);
 257
 258     /**
 259         Destructor.
 260     */
 261     virtual ~wxFFileInputStream();
 262
 263     /**
 264         Returns @true if the stream is initialized and ready.
 265     */
 266     bool IsOk() const;
 267
 268     /**
 269         Returns the underlying file object.
 270         @since 2.9.5
 271     */
 272     wxFFile* GetFile() const;
 273 };
 274
 275
 276
 277 /**
 278     @class wxFFileStream
 279
 280     This stream allows to both read from and write to a file using buffered
 281     STDIO functions.
 282
 283     @library{wxbase}
 284     @category{streams}
 285
 286     @see wxFFileInputStream, wxFFileOutputStream, wxFileStream
 287 */
 288 class wxFFileStream : public wxFFileInputStream,
 289                       public wxFFileOutputStream
 290 {
 291 public:
 292     /**
 293         Initializes a new file stream in the given @a mode using the specified
 294         @a iofileName name.
 295
 296         @warning
 297         You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
 298     */
 299     wxFFileStream(const wxString& iofileName, const wxString& mode = "w+b");
 300
 301     /**
 302         Returns @true if the stream is initialized and ready.
 303
 304         This method returns @true if the stream can be both read from and
 305         written to.
 306     */
 307     bool IsOk() const;
 308 };
 309
 310
 311
 312 /**
 313     @class wxFileStream
 314
 315     This class represents data that can be both read from and written to a file.
 316     There are actually two such groups of classes: this one is based on wxFile
 317     whereas wxFFileStream is based in the wxFFile class.
 318
 319     @library{wxbase}
 320     @category{streams}
 321
 322     @see wxFileInputStream, wxFileOutputStream, wxFFileStream
 323 */
 324 class wxFileStream : public wxFileOutputStream,
 325                      public wxFileInputStream
 326 {
 327 public:
 328     /**
 329         Initializes a new file stream in read-write mode using the specified
 330         @a iofileName name.
 331
 332         @warning
 333         You should use IsOk() to verify if the constructor succeeded.
 334     */
 335     wxFileStream(const wxString& iofileName);
 336
 337     /**
 338         Returns @true if the stream is initialized and ready.
 339
 340         This method returns @true if the stream can be both read from and
 341         written to.
 342     */
 343     bool IsOk() const;
 344 };
 345