Fix wxWebView documentation warnings.

[wxWidgets.git] / interface / wx / stream.h

diff --git a/interface/wx/stream.h b/interface/wx/stream.h
index 2cb6d47e6389f462f6cd53cb51627e978a7816b1..51b983dd8ad9a1edab64fa7289a74252df3ff566 100644 (file)
--- a/interface/wx/stream.h
+++ b/interface/wx/stream.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxStreamBase and its derived classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxStreamBase and its derived classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -76,10 +76,22 @@ public:
     virtual bool IsOk() const;
 
     /**
     virtual bool IsOk() const;
 
     /**

-        Returns @true if the streams supports seeking to arbitrary offsets.
+        Returns @true if the stream supports seeking to arbitrary offsets.

     */
     virtual bool IsSeekable() const;
 
     */
     virtual bool IsSeekable() const;
 

+    /**
+        Resets the stream state.
+
+        By default, resets the stream to good state, i.e. clears any errors.
+        Since wxWidgets 2.9.3 can be also used to explicitly set the state to
+        the specified error (the @a error argument didn't exist in the previous
+        versions).
+
+        @see GetLastError()
+     */
+    void Reset(wxStreamError error = wxSTREAM_NO_ERROR);
+

     /**
         Returns the opposite of IsOk().
         You can use this function to test the validity of the stream as if
     /**
         Returns the opposite of IsOk().
         You can use this function to test the validity of the stream as if


@@ -138,6 +150,13 @@ protected:
 class wxStreamBuffer
 {
 public:
 class wxStreamBuffer
 {
 public:

+    /** BufMode flags */
+    enum BufMode
+    {
+        read,
+        write,
+        read_write
+    };

 
     /**
         Constructor, creates a new stream buffer using @a stream as a parent stream
 
     /**
         Constructor, creates a new stream buffer using @a stream as a parent stream


@@ -172,8 +191,13 @@ public:
         and calling SetBufferIO() but is more convenient.
 
         @since 2.9.0
         and calling SetBufferIO() but is more convenient.
 
         @since 2.9.0

+
+        @param bufsize
+            The size of buffer in bytes.
+        @param stream
+            The associated input stream, the buffer will be used in read mode.

      */
      */

-    wxStreamBuffer(wxInputStream& stream, size_t bufsize);
+    wxStreamBuffer(size_t bufsize, wxInputStream& stream);

 
     /**
         Constructor for an output buffer of the specified size.
 
     /**
         Constructor for an output buffer of the specified size.


@@ -182,8 +206,13 @@ public:
         and calling SetBufferIO() but is more convenient.
 
         @since 2.9.0
         and calling SetBufferIO() but is more convenient.
 
         @since 2.9.0

+
+        @param bufsize
+            The size of buffer in bytes.
+        @param stream
+            The associated output stream, the buffer will be used in write mode.

      */
      */

-    wxStreamBuffer(wxOutputStream& stream, size_t bufsize);
+    wxStreamBuffer(size_t bufsize, wxOutputStream& stream);

 
     /**
         Constructor; creates a new empty stream buffer which won't flush any data
 
     /**
         Constructor; creates a new empty stream buffer which won't flush any data


@@ -219,7 +248,7 @@ public:
         Destructor.
         It finalizes all IO calls and frees all internal buffers if necessary.
     */
         Destructor.
         It finalizes all IO calls and frees all internal buffers if necessary.
     */

-    wxStreamBuffer();
+    ~wxStreamBuffer();

 
     /**
         Fill the IO buffer.
 
     /**
         Fill the IO buffer.


@@ -508,6 +537,20 @@ public:
     */
     wxOutputStream& Write(wxInputStream& stream_in);
 
     */
     wxOutputStream& Write(wxInputStream& stream_in);
 

+    /**
+        Writes exactly the specified number of bytes from the buffer.
+
+        Returns @true if exactly @a size bytes were written. Otherwise, returns
+        @false and LastWrite() should be used to retrieve the exact amount of
+        the data written if necessary.
+
+        This method uses repeated calls to Write() (which may return writing
+        only part of the data) if necessary.
+
+        @since 2.9.5
+    */
+    bool WriteAll(const void* buffer, size_t size);
+

 protected:
     /**
         Internal function. It is called when the stream wants to write data of the
 protected:
     /**
         Internal function. It is called when the stream wants to write data of the


@@ -579,7 +622,7 @@ public:
 
     /**
         Reads the specified amount of bytes and stores the data in buffer.
 
     /**
         Reads the specified amount of bytes and stores the data in buffer.

-        To check if the call was successfull you must use LastRead() to check
+        To check if the call was successful you must use LastRead() to check

         if this call did actually read @a size bytes (if it didn't, GetLastError()
         should return a meaningful value).
 
         if this call did actually read @a size bytes (if it didn't, GetLastError()
         should return a meaningful value).
 


@@ -600,9 +643,31 @@ public:
     */
     wxInputStream& Read(wxOutputStream& stream_out);
 
     */
     wxInputStream& Read(wxOutputStream& stream_out);
 

+    /**
+        Reads exactly the specified number of bytes into the buffer.
+
+        Returns @true only if the entire amount of data was read, otherwise
+        @false is returned and the number of bytes really read can be retrieved
+        using LastRead(), as with Read().
+
+        This method uses repeated calls to Read() (which may return after
+        reading less than the requested number of bytes) if necessary.
+
+        @warning
+        The buffer absolutely needs to have at least the specified size.
+
+        @since 2.9.5
+    */
+    bool ReadAll(void* buffer, size_t size);
+

     /**
         Changes the stream current position.
 
     /**
         Changes the stream current position.
 

+        This operation in general is possible only for seekable streams 
+        (see wxStreamBase::IsSeekable()); non-seekable streams support only
+        seeking positive amounts in mode @c wxFromCurrent (this is implemented
+        by reading data and simply discarding it).
+

         @param pos
             Offset to seek to.
         @param mode
         @param pos
             Offset to seek to.
         @param mode


@@ -613,7 +678,9 @@ public:
     virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 
     /**
     virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 
     /**

-        Returns the current stream position.
+        Returns the current stream position or ::wxInvalidOffset if it's not
+        available (e.g. socket streams do not have a size nor a current stream
+        position).

     */
     virtual wxFileOffset TellI() const;
 
     */
     virtual wxFileOffset TellI() const;
 


@@ -651,7 +718,7 @@ protected:
         reached or an error occurred (in this last case the internal @c m_lasterror
         variable should be set accordingly as well).
     */
         reached or an error occurred (in this last case the internal @c m_lasterror
         variable should be set accordingly as well).
     */

-    size_t OnSysRead(void* buffer, size_t bufsize);
+    size_t OnSysRead(void* buffer, size_t bufsize) = 0;

 };
 
 
 };
 
 


@@ -686,9 +753,11 @@ public:
     virtual ~wxCountingOutputStream();
 
     /**
     virtual ~wxCountingOutputStream();
 
     /**

-        Returns the current size of the stream.
+        Returns the current length of the stream.
+
+        This is the amount of data written to the stream so far, in bytes.

     */
     */

-    size_t GetSize() const;
+    virtual wxFileOffset GetLength() const;

 };
 
 
 };
 
 


@@ -819,7 +888,7 @@ public:
         const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
 
         while (factory) {
         const wxFilterClassFactory *factory = wxFilterClassFactory::GetFirst();
 
         while (factory) {

-            list << factory->GetProtocol() << _T("\n");
+            list << factory->GetProtocol() << wxT("\n");

             factory = factory->GetNext();
         }
         @endcode
             factory = factory->GetNext();
         }
         @endcode


@@ -849,7 +918,7 @@ public:
         const wxChar *const *p;
 
         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
         const wxChar *const *p;
 
         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)

-            list << *p << _T("\n");
+            list << *p << wxT("\n");

         @endcode
     */
     virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
         @endcode
     */
     virtual const wxChar * const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;


@@ -1030,3 +1099,57 @@ public:
 };
 
 
 };
 
 

+/**
+    @class wxWrapperInputStream
+
+    A wrapper input stream is a kind of filter stream which forwards all the
+    operations to its base stream. This is useful to build utility classes such
+    as wxFSInputStream.
+
+    @note
+    The interface of this class is the same as that of wxInputStream.
+    Only a constructor differs and it is documented below.
+
+    @library{wxbase}
+    @category{streams}
+
+    @see wxFSInputStream, wxFilterInputStream
+    @since 2.9.4
+*/
+class wxWrapperInputStream : public wxFilterInputStream
+{
+public:
+    //@{
+    /**
+        Initializes a wrapper stream.
+
+        If the parent stream is passed as a pointer then the new wrapper stream
+        takes ownership of it. If it is passed by reference then it does not.
+    */
+    wxWrapperInputStream(wxInputStream& stream);
+    wxWrapperInputStream(wxInputStream* stream);
+    //@}
+
+protected:
+    /**
+        Default constructor, use InitParentStream() to finish initialization.
+
+        This constructor can be used by the derived classes from their own
+        constructors when the parent stream can't be specified immediately.
+        The derived class must call InitParentStream() later to do it.
+     */
+    wxWrapperInputStream();
+
+    //@{
+    /**
+        Set up the wrapped stream for an object initialized using the default
+        constructor.
+
+        The ownership logic is the same as for the non-default constructor,
+        i.e. this object takes ownership of the stream if it's passed by
+        pointer but not if it's passed by reference.
+     */
+    void InitParentStream(wxInputStream& stream);
+    void InitParentStream(wxInputStream* stream);
+    //@}
+};