interface/wx/mstream.h

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