interface/wx/mstream.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mstream.h
   3 // Purpose:     interface of wxMemoryOutputStream, wxMemoryInputStream
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMemoryOutputStream
  11
  12     This class allows to use all methods taking a wxOutputStream reference to write
  13     to in-memory data.
  14
  15     Example:
  16     @code
  17         wxMemoryOutputStream stream;
  18         if (!my_wxImage.SaveFile(stream))
  19             return;
  20
  21         // now we can access the saved image bytes:
  22         wxStreamBuffer* theBuffer = stream.GetOutputStreamBuffer();
  23         unsigned char byte;
  24         if (theBuffer->Read(byte, 1) != 1)
  25             return;
  26
  27         // ... do something with 'byte'...
  28
  29         // remember that ~wxMemoryOutputStream will destroy the internal
  30         // buffer since we didn't provide our own when constructing it
  31     @endcode
  32
  33     @library{wxbase}
  34     @category{streams}
  35
  36     @see wxStreamBuffer
  37 */
  38 class wxMemoryOutputStream : public wxOutputStream
  39 {
  40 public:
  41     /**
  42         If @a data is @NULL, then it will initialize a new empty buffer which will
  43         grow if required.
  44
  45         @warning
  46         If the buffer is created by wxMemoryOutputStream, it will be destroyed
  47         at the destruction of the stream.
  48     */
  49     wxMemoryOutputStream(void* data = NULL, size_t length = 0);
  50
  51     /**
  52         Destructor.
  53
  54         If the buffer wasn't provided by the user, it will be deleted here.
  55     */
  56     virtual ~wxMemoryOutputStream();
  57
  58     /**
  59         Allows you to transfer data from the internal buffer of wxMemoryOutputStream
  60         to an external buffer. @a len specifies the size of the buffer.
  61     */
  62     size_t CopyTo(void* buffer, size_t len) const;
  63
  64     /**
  65         Returns the pointer to the stream object used as an internal buffer
  66         for this stream.
  67     */
  68     wxStreamBuffer* GetOutputStreamBuffer() const;
  69 };
  70
  71
  72
  73 /**
  74     @class wxMemoryInputStream
  75
  76     This class allows to use all methods taking a wxInputStream reference to read
  77     in-memory data.
  78
  79     Example:
  80     @code
  81         // we've got a block of memory containing a BMP image and we want
  82         // to use wxImage to load it:
  83         wxMemoryInputStream stream(my_memory_block, size);
  84
  85         wxImage theBitmap;
  86         if (!theBitmap.LoadFile(stream, wxBITMAP_TYPE_BMP))
  87             return;
  88
  89         // we can now safely delete the original memory buffer as the data
  90         // has been decoded by wxImage:
  91         delete [] my_memory_block;
  92     @endcode
  93
  94     @library{wxbase}
  95     @category{streams}
  96
  97     @see wxStreamBuffer, wxMemoryOutputStream
  98 */
  99 class wxMemoryInputStream : public wxInputStream
 100 {
 101 public:
 102     /**
 103         Initializes a new read-only memory stream which will use the specified
 104         buffer data of length len. The stream does not take ownership of the buffer,
 105         i.e. the buffer will not be deleted in its destructor.
 106     */
 107     wxMemoryInputStream(const void* data, size_t len);
 108
 109     /**
 110         Creates a new read-only memory stream, initializing it with the data from
 111         the given output stream @a stream.
 112     */
 113     wxMemoryInputStream(const wxMemoryOutputStream& stream);
 114
 115     /**
 116         Creates a new read-only memory stream, initializing it with the
 117         data from the given input stream @a stream.
 118
 119         The @a len argument specifies the amount of data to read from the
 120         @a stream. Setting it to ::wxInvalidOffset means that the @a stream
 121         is to be read entirely (i.e. till the EOF is reached).
 122     */
 123     wxMemoryInputStream(wxInputStream& stream,
 124                         wxFileOffset len = wxInvalidOffset);
 125
 126     /**
 127         Destructor. Does NOT free the buffer provided in the ctor.
 128     */
 129     virtual ~wxMemoryInputStream();
 130
 131     /**
 132         Returns the pointer to the stream object used as an internal buffer
 133         for that stream.
 134     */
 135     wxStreamBuffer* GetInputStreamBuffer() const;
 136 };
 137