CNetscapeStream

Purpose

The CNetscapeStream class provides an interface and default behavior for encapsulating an incoming stream from the Navigator. (The default behavior is to do nothing with the stream.) The static EvolveStream method takes an NPStream object and extracts a CNetscapeStream object from the pdata field, making dispatch of multiple asynchronous streams a trivial matter. (See the introduction for more information on how stream dispatching is done in this plug-in framework.)

Note: The CNetscapeStream class in intended to live only for as long as there is incoming data, but the base class makes no provision for passing on the stream data when the stream is finished. Your inheriting class is responsible for this behavior. See CPlainTextStream for an example of how this can be done.

Dependencies

Methods

Members

static const long kMaxBufSize An arbitrarily large number for returning in WriteReady if you don't care how much data is passed in Write.
NPStream* mSourceStream The Navigator stream structure that CNetscapeStream encapsulates. mSourceStream->pdata should be a pointer to this.
char* mMIMEType The MIME-Type of the stream.
NPBool mSeekable Indicates whether the stream is capable of seeking. You cannot actually use the seeking methods (NPN_RequestRead) unless mStreamType is set to NP_SEEK in the constructor.
unsigned short mStreamType The transfer mode of the stream. Corresponds to *stype in NPP_NewStream. Changing this member will usually only be effective if done in the constructor.

CNetscapeStream::CNetscapeStream()

Syntax

CNetscapeStream::CNetscapeStream( NPMIMEType type, NPStream* stream, NPBool seekable, uint16 stype )

Purpose

Constructor. After the constructor is called, GetStreamType() can be called to access the preferred transfer method. When inheriting from CNetscapeStream, always initialize CNetscapeStream using this constructor.

Parameters

type The MIME type of the new incoming stream.
stream The Navigator stream structure which this class will encapsulate.
seekable Determines whether the stream is capable of seeking.
stype The default transfer method of the stream.

Return Value

None.


CNetscapeStream::~CNetscapeStream

Syntax

CNetscapeStream::~CNetscapeStream()

Purpose

Destructor.

Parameters

None.

Return Value

None.

CNetscapeStream::WriteReady()

Syntax

long
WriteReady() 

Purpose

This method is called from NPP_WriteReady, after the stream object has been extracted from stream->pdata. The return value from this method tells the Navigator how much data we are ready to receive in the next call to Write(). A call to WriteReady() will always precede a call to Write(). Default behavior is to return kMaxBufSize, indicating that we are ready to handle an arbitrarily large chunk of data.

Parameters

None.

Return Value

The number of bytes which we are ready to accept in the next call to Write().


CNetscapeStream::Write()

Syntax

long
Write( int32 offset, int32 len, void *buffer )

Purpose

This method is called from NPP_Write, after the stream object has been extracted from stream->pdata. The method passes data into our stream encapsulation. Note that *buffer is valid only during the duration of this call. If you intend to use the data, you must copy it, rather than saving a reference to buffer. The default behavior of CNetscapeStream is to ignore the data. You must override this method if you intend to do anything with the data.

Parameters

offset The location of this chunk of data within the stream. If the stream type is not NP_SEEK, then offset will progress sequentially with each chunk of data received. Otherwise, offset will tell you which requested byterange this call is providing.
len The size of *buffer, in bytes.
buffer A pointer to the stream data. This pointer is only valid for the duration of the call to Write(). If you intend to use the data, you must copy it.

Return Value

None.


CNetscapeStream::Finish()

Syntax

NPError
Finish( NPError reason )

Purpose

This method is called from NPP_DestroyStream, after the stream object has been extracted from stream->pdata. In this method the stream object should prepare itself for destruction, handing off its data. This object will be destroyed when Finish() returns. You must override this method if you want your data to survive past the end of the call.

Parameters

reason The reason code indicating why this stream has finished.

Return Value

An NPError error code.


CNetscapeStream::StreamAsFile()

Syntax

void
StreamAsFile( const char* fname )

Purpose

This method is called from NPP_StreamAsFile, after the stream object has been extracted from stream->pdata. This method will only be called if mStreamType was set to NP_ASFILE or NP_ASFILEONLY in the constructor.

Parameters

fname The name of the file that contains the stream data.

Return Value

None.


CNetscapeStream::GetStreamType()

Syntax

unsigned short
GetStreamType()

Purpose

Accessor method for the stream's preferred transfer method. Called by NPP_NewStream() after the CNetscapeStream has been constructed.

Parameters

None.

Return Value

The preferred transfer method for the stream: can be NP_NORMAL, NP_SEEK, NP_ASFILE, or NP_ASFILEONLY


CNetscapeStream::GetURL()

Syntax

const char*
GetURL()

Purpose

Accessor method for the URL associated with this stream.

Parameters

None.

Return Value

The URL associated with this stream


CNetscapeStream::EvolveStream()

Syntax

static CNetscapeStream*
EvolveStream( NPStream* npStream )

Purpose

This static method extracts and type-casts a CNetscapeStream* from the pdata field of an NPStream structure. Used to dispatch NPP_Write, NPP_WriteReady, etc. to the appropriate objects.

Parameters

npStream The NPStream struct from which to extract a CNetscapeStream object.

Return Value

A pointer to a CNetscapeStream object.