interface/wfstream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wfstream.h
   3 // Purpose:     documentation for wxTempFileOutputStream class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTempFileOutputStream
  11     @wxheader{wfstream.h}
  12
  13     wxTempFileOutputStream is an output stream based on wxTempFile. It
  14     provides a relatively safe way to replace the contents of the
  15     existing file.
  16
  17     @library{wxbase}
  18     @category{streams}
  19
  20     @seealso
  21     wxTempFile
  22 */
  23 class wxTempFileOutputStream : public wxOutputStream
  24 {
  25 public:
  26     /**
  27         Associates wxTempFileOutputStream with the file to be replaced and opens it.
  28         You should use
  29         wxStreamBase::IsOk to verify if the constructor succeeded.
  30
  31         Call Commit() or wxOutputStream::Close to
  32         replace the old file and close this one. Calling Discard()
  33         (or allowing the destructor to do it) will discard the changes.
  34     */
  35     wxTempFileOutputStream(const wxString& fileName);
  36
  37     /**
  38         Validate changes: deletes the old file of the given name and renames the new
  39         file to the old name. Returns @true if both actions succeeded. If @false is
  40         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     bool Commit();
  45
  46     /**
  47         Discard changes: the old file contents are not changed, the temporary file is
  48         deleted.
  49     */
  50     void Discard();
  51 };
  52
  53
  54 /**
  55     @class wxFFileOutputStream
  56     @wxheader{wfstream.h}
  57
  58     This class represents data written to a file. There are actually
  59     two such groups of classes: this one is based on wxFFile
  60     whereas wxFileInputStream is based in
  61     the wxFile class.
  62
  63     Note that wxOutputStream::SeekO
  64     can seek beyond the end of the stream (file) and will thus not return
  65     @e wxInvalidOffset for that.
  66
  67     @library{wxbase}
  68     @category{streams}
  69
  70     @seealso
  71     wxBufferedOutputStream, wxFFileInputStream, wxFileInputStream
  72 */
  73 class wxFFileOutputStream : public wxOutputStream
  74 {
  75 public:
  76     //@{
  77     /**
  78         Initializes a file stream in write-only mode using the file descriptor @e fp.
  79     */
  80     wxFFileOutputStream(const wxString& filename,
  81                         const wxString& mode="w+b");
  82     wxFFileOutputStream(wxFFile& file);
  83     wxFFileOutputStream(FILE * fp);
  84     //@}
  85
  86     /**
  87         Destructor.
  88     */
  89     ~wxFFileOutputStream();
  90
  91     /**
  92         Returns @true if the stream is initialized and ready.
  93     */
  94 #define bool IsOk()     /* implementation is private */
  95 };
  96
  97
  98 /**
  99     @class wxFileOutputStream
 100     @wxheader{wfstream.h}
 101
 102     This class represents data written to a file. There are actually
 103     two such groups of classes: this one is based on wxFile
 104     whereas wxFFileInputStream is based in
 105     the wxFFile class.
 106
 107     Note that wxOutputStream::SeekO
 108     can seek beyond the end of the stream (file) and will thus not return
 109     @e wxInvalidOffset for that.
 110
 111     @library{wxbase}
 112     @category{streams}
 113
 114     @seealso
 115     wxBufferedOutputStream, wxFileInputStream, wxFFileInputStream
 116 */
 117 class wxFileOutputStream : public wxOutputStream
 118 {
 119 public:
 120     //@{
 121     /**
 122         Initializes a file stream in write-only mode using the file descriptor @e fd.
 123     */
 124     wxFileOutputStream(const wxString& ofileName);
 125     wxFileOutputStream(wxFile& file);
 126     wxFileOutputStream(int fd);
 127     //@}
 128
 129     /**
 130         Destructor.
 131     */
 132     ~wxFileOutputStream();
 133
 134     /**
 135         Returns @true if the stream is initialized and ready.
 136     */
 137 #define bool IsOk()     /* implementation is private */
 138 };
 139
 140
 141 /**
 142     @class wxFileInputStream
 143     @wxheader{wfstream.h}
 144
 145     This class represents data read in from a file. There are actually
 146     two such groups of classes: this one is based on wxFile
 147     whereas wxFFileInputStream is based in
 148     the wxFFile class.
 149
 150     Note that wxInputStream::SeekI
 151     can seek beyond the end of the stream (file) and will thus not return
 152     @e wxInvalidOffset for that.
 153
 154     @library{wxbase}
 155     @category{streams}
 156
 157     @seealso
 158     wxBufferedInputStream, wxFileOutputStream, wxFFileOutputStream
 159 */
 160 class wxFileInputStream : public wxInputStream
 161 {
 162 public:
 163     //@{
 164     /**
 165         Initializes a file stream in read-only mode using the specified file descriptor.
 166     */
 167     wxFileInputStream(const wxString& ifileName);
 168     wxFileInputStream(wxFile& file);
 169     wxFileInputStream(int fd);
 170     //@}
 171
 172     /**
 173         Destructor.
 174     */
 175     ~wxFileInputStream();
 176
 177     /**
 178         Returns @true if the stream is initialized and ready.
 179     */
 180 #define bool IsOk()     /* implementation is private */
 181 };
 182
 183
 184 /**
 185     @class wxFFileInputStream
 186     @wxheader{wfstream.h}
 187
 188     This class represents data read in from a file. There are actually
 189     two such groups of classes: this one is based on wxFFile
 190     whereas wxFileInputStream is based in
 191     the wxFile class.
 192
 193     Note that wxInputStream::SeekI
 194     can seek beyond the end of the stream (file) and will thus not return
 195     @e wxInvalidOffset for that.
 196
 197     @library{wxbase}
 198     @category{streams}
 199
 200     @seealso
 201     wxBufferedInputStream, wxFFileOutputStream, wxFileOutputStream
 202 */
 203 class wxFFileInputStream : public wxInputStream
 204 {
 205 public:
 206     //@{
 207     /**
 208         Initializes a file stream in read-only mode using the specified file pointer @e
 209         fp.
 210     */
 211     wxFFileInputStream(const wxString& filename,
 212                        const wxString& mode = "rb");
 213     wxFFileInputStream(wxFFile& file);
 214     wxFFileInputStream(FILE * fp);
 215     //@}
 216
 217     /**
 218         Destructor.
 219     */
 220     ~wxFFileInputStream();
 221
 222     /**
 223         Returns @true if the stream is initialized and ready.
 224     */
 225 #define bool IsOk()     /* implementation is private */
 226 };
 227
 228
 229 /**
 230     @class wxFFileStream
 231     @wxheader{wfstream.h}
 232
 233
 234     @library{wxbase}
 235     @category{FIXME}
 236
 237     @seealso
 238     wxStreamBuffer
 239 */
 240 class wxFFileStream : public wxFFileOutputStream
 241 {
 242 public:
 243     /**
 244         Initializes a new file stream in read-write mode using the specified
 245         @e iofilename name.
 246     */
 247     wxFFileStream(const wxString& iofileName);
 248 };
 249
 250
 251 /**
 252     @class wxFileStream
 253     @wxheader{wfstream.h}
 254
 255
 256     @library{wxbase}
 257     @category{FIXME}
 258
 259     @seealso
 260     wxStreamBuffer
 261 */
 262 class wxFileStream : public wxFileOutputStream
 263 {
 264 public:
 265     /**
 266         Initializes a new file stream in read-write mode using the specified
 267         @e iofilename name.
 268     */
 269     wxFileStream(const wxString& iofileName);
 270 };