interface/wx/wfstream.h

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