DWFCore::DWFDigestInputStream Class Reference

#include "dwfcore/DigestInputStream.h"

Inheritance diagram for DWFCore::DWFDigestInputStream:

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

Collaboration graph
[legend]
List of all members.

Detailed Description

The interface for an input stream object that computes a digest for a complete sequence of bytes read.

Since:
1.2
Implementations of this can be used to determine a digest (MD5, SHA-1, SHA256, etc.) for the complete sequence of bytes that are read from another linked [chained] input stream. The bytes essentially pass through this implementation for digest computation.
Examples:

Digest/main.cpp.

Definition at line 48 of file DigestInputStream.h.

Public Member Functions

_DWFCORE_API DWFDigestInputStream () throw ()
_DWFCORE_API DWFDigestInputStream (DWFDigest *pDigest, DWFInputStream *pInputStream, bool bOwnStream) throw ()
virtual _DWFCORE_API ~DWFDigestInputStream () throw ()
_DWFCORE_API void setDigest (DWFDigest *pDigest) throw ()
virtual _DWFCORE_API void chainInputStream (DWFInputStream *pInputStream, bool bOwnStream) throw ()
virtual _DWFCORE_API bool isDigestProgressive () throw ( DWFException )
virtual _DWFCORE_API DWFString digest () throw ( DWFException )
virtual _DWFCORE_API size_t digestRawBytes (unsigned char *&rpBytes) throw ( DWFException )
virtual _DWFCORE_API DWFString digestBase64 () throw ( DWFException )
virtual _DWFCORE_API size_t available () const throw ( DWFException )
virtual _DWFCORE_API size_t read (void *pBuffer, size_t nBytesToRead) throw ( DWFException )
virtual _DWFCORE_API off_t seek (int eOrigin, off_t nOffset) throw ( DWFException )


Constructor & Destructor Documentation

_DWFCORE_API DWFCore::DWFDigestInputStream::DWFDigestInputStream  )  throw ()
 

Constructor. If the default constructor is used, then the user must set the digest and the input stream using setDigest and chainInputStream respectively, otherwise an exception will be thrown.

_DWFCORE_API DWFCore::DWFDigestInputStream::DWFDigestInputStream DWFDigest pDigest,
DWFInputStream pInputStream,
bool  bOwnStream
throw ()
 

Constructor. If either the digest or the inputstream is NULL, then it must be set using setDigest or chainInputStream respectively.

Parameters:
pDigest A pointer to the digest object that will be used to determine the digest of the stream data. This digest stream will take ownership of the digest. The digest should be allocated with the DWFCORE_ALLOC_OBJECT macro.
pInputStream A pointer to a stream to chain to this object. If this pointer is NULL and another stream was previously chained to this object, it will be cleared (and deleted if owned.) This object should be allocated with the DWFCORE_ALLOC_OBJECT macro. if ownership will be transferred.
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::DWFDigestInputStream::~DWFDigestInputStream  )  throw () [virtual]
 

Destructor


Member Function Documentation

virtual _DWFCORE_API size_t DWFCore::DWFDigestInputStream::available  )  const throw ( DWFException ) [inline, virtual]
 

Used to determine the availablity of data from the underlying input stream.

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

Implements DWFCore::DWFInputStream.

Examples:
Digest/main.cpp.

Definition at line 200 of file DigestInputStream.h.

virtual _DWFCORE_API void DWFCore::DWFDigestInputStream::chainInputStream DWFInputStream pInputStream,
bool  bOwnStream
throw () [virtual]
 

Attaches (or detaches) another input stream to this object. Chaining simply refers to the process of using one stream as the source for another. Any number of these objects can be chained together to add functionality and data modification in a single read() invocation.

Parameters:
pInputStream A pointer to a stream to chain to this object. If this pointer is NULL and another stream was previously chained to this object, it will be cleared (and deleted if owned.) This object should be allocated with the DWFCORE_ALLOC_OBJECT macro. if ownership will be transferred.
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 
Examples:
Digest/main.cpp.

virtual _DWFCORE_API DWFString DWFCore::DWFDigestInputStream::digest  )  throw ( DWFException ) [virtual]
 

Return the digest computed on the bytes read, in hexadecimal form. If no input stream has been linked, this will throw a DWFIllegalStateException.

Returns:
The digest. The length depends on the algorithm used.
Exceptions:
DWFException 
Examples:
Digest/main.cpp.

virtual _DWFCORE_API DWFString DWFCore::DWFDigestInputStream::digestBase64  )  throw ( DWFException ) [virtual]
 

Return the digest computed on the bytes read, in base 64 encoding. If no input stream has been linked, this will throw a DWFIllegalStateException.

Returns:
The digest in base 64 encoding. The length depends on the algorithm used.
Exceptions:
DWFException 

virtual _DWFCORE_API size_t DWFCore::DWFDigestInputStream::digestRawBytes unsigned char *&  rpBytes  )  throw ( DWFException ) [virtual]
 

Return the digest computed on the bytes read, in terms of the raw digest bytes. The bytes are return in a array of unsigned characters that must be deleted by the caller using DWFCORE_FREE_MEMORY(). If no input stream has been linked, this will throw a DWFIllegalStateException.

Parameters:
rpBytes The array of bytes will be allocated and returned via this pointer. It should be initialized to NULL before calling this.
Returns:
The size of the character array holding the raw bytes of the digest. The length depends on the algorithm used.
Exceptions:
DWFException 

virtual _DWFCORE_API bool DWFCore::DWFDigestInputStream::isDigestProgressive  )  throw ( DWFException ) [virtual]
 

This returns whether or not the underlying digest is progressive, that is, the digest can be returned on the number of bytes streamed so far, and still be updated. If a digest is not progressive, digest() should be called only after all bytes have been streamed through the digest stream.

Returns:
True if the digest supports digest() calls while bytes are being streamed.
Exceptions:
DWFException 
Examples:
Digest/main.cpp.

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

Reads at most nBytesToRead from the underlying input stream. The underlying digest computation will be updated in the process. If no input stream has been linked, this will throw a DWFIllegalStateException.

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 pDigest. 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.

Examples:
Digest/main.cpp.

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

Repositions the internal cursor on the linked input stream for subsequent read invocations. This method may fail and throw an exception if the request either exceeds the bounds of the underlying memory buffer, or exhausts the underlying stream or the underlying stream does not support the method itself. If no input stream has been linked, this will throw a DWFIllegalStateException.

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.

_DWFCORE_API void DWFCore::DWFDigestInputStream::setDigest DWFDigest pDigest  )  throw ()
 

Set the digest object to use to evaluate the digest of the streamed data. Any This will delete any digest that the digest stream may already own.

Parameters:
pDigest A pointer to the digest object that will be used to determine the digest of the stream data. This digest stream will take ownership of the new digest which should be allocated with the DWFCORE_ALLOC_OBJECT macro.
Exceptions:
DWFException 


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