DWFCore::DWFMonitoredInputStream Class Reference

#include "dwfcore/MonitoredInputStream.h"

Inheritance diagram for DWFCore::DWFMonitoredInputStream:

Inheritance graph
[legend]
Collaboration diagram for DWFCore::DWFMonitoredInputStream:

Collaboration graph
[legend]
List of all members.

Detailed Description

An input stream whose read operation can be "watched".

Since:
1.0.1
This implementation of the DWFInputStream is useful when it is desriable for one entity to passively receive the same data as the active stream reader. There are two mechanisms provided for hooking into the stream: an object may implement the Monitor interface, or DWFOutputStream. In both cases, whatever data was obtained during the read() operation will be either posted to the monitor or written into the output stream.

Example 1: Use a monitor to show progress:

                class ProgressMonitor : public DWFMonitoredInputStream::Monitor
                {
                    ProgressMonitor( size_t nTotalBytesInStream )
                        : _nTotalBytes( nTotalBytesInStream )
                        , _nBytesReadSoFar( 0 )
                    {;}
                    
                    void notify( const void* const pBuffer,
                                 size_t            nBytesRequested,
                                 size_t            nBytesRead )
                        throw( DWFException )
                    {
                        _nBytesReadSoFar += nBytesRead;
                        float nProgress = 100.0 * (float)(_nBytesReadSoFar / _nTotalBytesInStream);
   
                        _send_progress_function( nProgress );
                    }
                };

Example 2: Copy a stream into a temporary file.

                DWFString zTemplate( L"_dwfcore_" );
   
                //
                // passing true as the second parameter will result in the
                // temporary disk file being deleted when the DWFTempFile
                // object is destroyed.
                //
                DWFTempFile* pTempFile = DWFTempFile::Create( zTemplate, true );
                DWFOutputStream* pTempFileStream = pTempFile->getOuputStream();
   
                //
                // passing true here tells the monitor stream to assume
                // ownership of the file stream and delete it when
                // he is deleted himself
                //
                pMonitorStream->attachMonitor( pTempFileStream, true );
   
                ... read from the monitor stream ...
   
                DWFCORE_FREE_OBJECT( pMonitorStream );
                DWFCORE_FREE_OBJECT( pTempFile );
Examples:

Files/Files.cpp.

Definition at line 100 of file MonitoredInputStream.h.

Public Member Functions

_DWFCORE_API DWFMonitoredInputStream (DWFInputStream *pStream, bool bOwnStream) throw ()
virtual _DWFCORE_API ~DWFMonitoredInputStream () throw ()
_DWFCORE_API void attach (Monitor *pMonitor, bool bOwnMonitor) throw ( DWFException )
_DWFCORE_API void attach (DWFOutputStream *pMonitor, bool bOwnMonitor) throw ( DWFException )
_DWFCORE_API void detach () throw ( DWFException )
_DWFCORE_API size_t available () const throw ( DWFException )
_DWFCORE_API size_t read (void *pBuffer, size_t nBytesToRead) throw ( DWFException )
_DWFCORE_API off_t seek (int eOrigin, off_t nOffset) throw ( DWFException )

Classes

interface  Monitor
 Callback interface for watching DWFMonitoredInputStream objects. More...


Constructor & Destructor Documentation

_DWFCORE_API DWFCore::DWFMonitoredInputStream::DWFMonitoredInputStream DWFInputStream pStream,
bool  bOwnStream
throw ()
 

Constructor

Parameters:
pStream The source data stream to be monitored.
bOwnStream If true, this object will assume ownership of pInputStream and delete it as necessary using DWFCORE_FREE_OBJECT. If false, the caller retains ownership of pInputStream and is responsible for deleting it.
Exceptions:
None 

virtual _DWFCORE_API DWFCore::DWFMonitoredInputStream::~DWFMonitoredInputStream  )  throw () [virtual]
 

Destructor

Exceptions:
None 


Member Function Documentation

_DWFCORE_API void DWFCore::DWFMonitoredInputStream::attach DWFOutputStream pMonitor,
bool  bOwnMonitor
throw ( DWFException )
 

Binds a monitoring stream to the stream. Any data obtained from a read() call will result in this stream's write() method being invoked. Any previously bound monitor will be replaced; and deleted if this stream currently owns it.

Parameters:
pMonitor The stream to which read data will be written.
bOwnMonitor If true, this object will assume ownership of pMonitor and delete it as necessary using DWFCORE_FREE_OBJECT. If false, the caller retains ownership of pMonitor and is responsible for deleting it.
Exceptions:
None 

_DWFCORE_API void DWFCore::DWFMonitoredInputStream::attach Monitor pMonitor,
bool  bOwnMonitor
throw ( DWFException )
 

Binds a monitor to the stream. Any data obtained from a read() call will result in this monitor's notify() method being invoked. Any previously bound monitor will be replaced; and deleted if this stream currently owns it.

Parameters:
pMonitor The monitor to which read data will be posted.
bOwnMonitor If true, this object will assume ownership of pMonitor and delete it as necessary using DWFCORE_FREE_OBJECT. If false, the caller retains ownership of pMonitor and is responsible for deleting it.
Exceptions:
None 
Examples:
Files/Files.cpp.

_DWFCORE_API size_t DWFCore::DWFMonitoredInputStream::available  )  const throw ( DWFException ) [virtual]
 

Used to determine the availablity of data that can be provided by the stream. This method is not required to report the exact number of bytes that will be obtain from a subsequent read() invocation. This method must report zero bytes once the stream data has been expired. Once this method returns zero, it may never again report a non-zero value.

Returns:
The number of bytes available to read from the stream.
Exceptions:
DWFException 

Implements DWFCore::DWFInputStream.

_DWFCORE_API void DWFCore::DWFMonitoredInputStream::detach  )  throw ( DWFException )
 

Unbinds any monitors from the stream. All owned monitors will be deleted.

Exceptions:
None 

_DWFCORE_API size_t DWFCore::DWFMonitoredInputStream::read void *  pBuffer,
size_t  nBytesToRead
throw ( DWFException ) [virtual]
 

Reads at most nBytesToRead from the stream into the buffer provided. The stream is not required to fill the read buffer but it must always report the number of bytes, including zero, that were obtained.

Parameters:
pBuffer A pointer to a block of memory to receive the bytes. Any implementation receiving a NULL buffer pointer should throw a DWFInvalidArgumentException.
nBytesToRead The number of bytes to copy into pBuffer. This value should not exceed the capacity of the memory block at pBuffer.
Returns:
The number of actual bytes read.
Exceptions:
DWFException 

Implements DWFCore::DWFInputStream.

_DWFCORE_API off_t DWFCore::DWFMonitoredInputStream::seek int  eOrigin,
off_t  nOffset
throw ( DWFException ) [virtual]
 

Repositions the internal cursor for subsequent read invocations. Not all implementations will support this method; it is recommended that a DWFNotImplementedException be thrown if not.

Warning:
This method may not be supported by all streams.
Parameters:
eOrigin One of SEEK_SET, SEEK_CUR or SEEK_END.
nOffset The number of bytes from eOrigin to move the internal cursor.
Returns:
The previous cursor offset before the seek.
Exceptions:
DWFException 

Implements DWFCore::DWFInputStream.


The documentation for this class was generated from the following file:
Generated on Tue Jan 6 22:39:38 2009 for Autodesk DWF Core Library by  doxygen 1.4.5