NPP_NewStream

« Gecko Plugin API Reference « Plug-in Side Plug-in API

Summary

Notifies a plug-in instance of a new data stream.

Syntax

#include <npapi.h>
NPError NPP_NewStream(NPP        instance, 
                      NPMIMEType type,
                      NPStream*  stream,
                      NPBool     seekable,
                      uint16*    stype);

Parameters

The function has the following parameters:

instance: Pointer to current plug-in instance.

type: Pointer to MIME type of the stream.

stream: Pointer to new stream.

seekable

Boolean indicating whether the stream is seekable:

true: Seekable. Stream supports random access through calls to NPN_RequestRead (for example, local files or HTTP servers that support byte-range requests).
false: Not seekable. The browser must copy data in the stream to the local cache to satisfy random access requests made through NPN_RequestRead.

stype

Out parameter. The plugin should set this value to request a mode for the stream. For more information about each of these values, see Directions in this section.

NP_NORMAL (Default): Delivers stream data to the instance in a series of calls to NPP_WriteReady and NPP_Write.
NP_ASFILEONLY: Saves stream data to a file in the local cache.
NP_ASFILE: File download. Like NP_ASFILEONLY except that data is delivered to the plug-in as it is saved to the file (as in mode NP_NORMAL).
NP_SEEK: Stream data randomly accessible by the plug-in as needed, through calls to NPN_RequestRead.

Implementation note: some plugins, notably Silverlight, do not set this outparam, and rely on the outparam being initialized to a default NP_NORMAL value.

Returns

If successful, the function should return NPERR_NO_ERROR.
If unsuccessful, the function should return one of the NPError Error Codes. This will cause the browser to destroy the stream without calling NPP_DestroyStream.

Description

NPP_NewStream notifies the plug-in when a new stream is created. The NPStream* pointer is valid until the stream is destroyed. The plug-in can store plug-in-private data associated with the stream in stream->pdata. The MIME type of the stream is provided by the type parameter.

The data in the stream can be the file specified in the SRC attribute of the EMBED tag, for an embedded instance, or the file itself, for a full-page instance. A plug-in can also request a stream with the function NPN_GetURL. The browser calls NPP_DestroyStream when the stream completes (either successfully or abnormally). The plug-in can terminate the stream itself by calling NPN_DestroyStream.

The parameter stype defines the mode of the stream. Values:

NP_NORMAL (Default): Delivers stream data to the instance in a series of calls to NPP_WriteReady and NPP_Write. The plug-in can process the data progressively as it arrives from the network or file system.
NP_ASFILEONLY: The browser saves stream data to a file in the local cache. When the stream is complete, the browser calls NPP_StreamAsFile to deliver the path of the file to the plug-in. If the stream comes from a local file, the NPP_Write and NPP_WriteReady functions are not called. NPP_StreamAsFile is simply called immediately. This mode allows the plug-in full random access to the data using platform-specific file operations.
NP_ASFILE: File download. Differs from NP_ASFILEONLY in that data is delivered to the plug-in, through a series of calls to NPP_WriteReady and NPP_Write, as it is saved to the file (as in mode NP_NORMAL). When the stream is complete, the browser calls NPP_StreamAsFile to deliver the path of the file to the plug-in. If the data in the stream comes from a file that is already local, the data is read, sent to the plug-in through NPP_Write, and written to a file in the local cache.

NOTE: Most plug-ins that need the stream saved to a file should use the more efficient mode NP_ASFILEONLY (above); this mode is preserved for compatibility only.

NP_SEEK: Stream data is not automatically delivered to the instance, but can be randomly accessed by the plug-in as needed, through calls to NPN_RequestRead. If the stream is not seekable, placing the stream in NP_SEEK mode causes the browser to save the entire stream to the disk cache. NPN_RequestRead requests are only fulfilled when all data has been read and stored in the cache. As an optimization to extract the maximum benefit from existing network connections, the browser continues to read data sequentially out of the stream (as in mode NP_NORMAL) until the first NPN_RequestRead call is made.

NOTE: In any mode other than NP_SEEK, the application should call NPP_DestroyStream once all data in the stream has been written to the plug-in. The plug-in can also request termination of the stream at any time by calling NPN_DestroyStream.