NPP_NewStream

  • Revision slug: NPP_NewStream
  • Revision title: NPP_NewStream
  • Revision id: 125807
  • Created:
  • Creator: jgriffin
  • Is current revision? No
  • Comment 1 words added, 1 words removed

Revision Content

 

{{ Np-plugin-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
Requested mode of new 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.

Returns

  • If successful, the function returns NPERR_NO_ERROR.
  • If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see Error Codes.

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.

See Also

NPN_NewStream, NPP_StreamAsFile, NPP_Write, NPP_WriteReady, NPP_DestroyStream, NPN_RequestRead, NPStream, NPN_GetURL

{{ languages( { "ja": "ja/NPP_NewStream" } ) }}

Revision Source

<p> </p>
<p>{{ Np-plugin-api() }}</p>
<h3 name="Summary">Summary</h3>
<p>Notifies a plug-in instance of a new data stream.</p>
<h3 name="Syntax">Syntax</h3>
<pre>#include &lt;npapi.h&gt;
NPError NPP_NewStream(NPP        instance, 
                      NPMIMEType type,
                      NPStream*  stream,
                      NPBool     seekable,
                      uint16*    stype);
 
</pre>
<h3 name="Parameters">Parameters</h3>
<p>The function has the following parameters:</p>
<dl> <dt>instance</dt> <dd>Pointer to current plug-in instance.</dd>
</dl>
<dl> <dt>type</dt> <dd>Pointer to MIME type of the stream.</dd>
</dl>
<dl> <dt>stream</dt> <dd>Pointer to new stream.</dd>
</dl>
<dl> <dt>seekable</dt> <dd>Boolean indicating whether the stream is seekable: <ul> <li>true: Seekable. Stream supports random access through calls to <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a> (for example, local files or HTTP servers that support byte-range requests).</li> <li>false: Not seekable. The browser must copy data in the stream to the local cache to satisfy random access requests made through <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a>.</li> </ul> </dd>
</dl>
<dl> <dt>stype</dt> <dd>Requested mode of new stream. For more information about each of these values, see Directions in this section. <ul> <li><strong>NP_NORMAL</strong> (Default): Delivers stream data to the instance in a series of calls to <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> and <a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write</a>.</li> <li><strong>NP_ASFILEONLY</strong>: Saves stream data to a file in the local cache.</li> <li><strong>NP_ASFILE</strong>: 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).</li> <li><strong>NP_SEEK</strong>: Stream data randomly accessible by the plug-in as needed, through calls to <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a>.</li> </ul> </dd>
</dl>
<h3 name="Returns">Returns</h3>
<ul> <li>If successful, the function returns NPERR_NO_ERROR.</li> <li>If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see <a href="/en/NPAPI/Constants#Error_Codes" title="en/NPAPI/Constants#Error_Codes">Error Codes</a>.</li>
</ul>
<h3 name="Description">Description</h3>
<p><code>NPP_NewStream</code> 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-&gt;pdata. The MIME type of the stream is provided by the type parameter.</p>
<p>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 <a href="/en/NPN_GetURL" title="en/NPN_GetURL">NPN_GetURL</a>. The browser calls <a href="/en/NPP_DestroyStream" title="en/NPP_DestroyStream">NPP_DestroyStream</a> when the stream completes (either successfully or abnormally). The plug-in can terminate the stream itself by calling <a href="/en/NPN_DestroyStream" title="en/NPN_DestroyStream">NPN_DestroyStream</a>.</p>
<p>The parameter stype defines the mode of the stream. Values:</p>
<ul> <li>NP_NORMAL (Default): Delivers stream data to the instance in a series of calls to <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> and <a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write</a>. The plug-in can process the data progressively as it arrives from the network or file system.</li> <li>NP_ASFILEONLY: The browser saves stream data to a file in the local cache. When the stream is complete, the browser calls <a href="/en/NPP_StreamAsFile" title="en/NPP_StreamAsFile">NPP_StreamAsFile</a> to deliver the path of the file to the plug-in. If the stream comes from a local file, the <a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write</a> and <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> functions are not called. <a href="/en/NPP_StreamAsFile" title="en/NPP_StreamAsFile">NPP_StreamAsFile</a> is simply called immediately. This mode allows the plug-in full random access to the data using platform-specific file operations.</li> <li>NP_ASFILE: File download. Differs from NP_ASFILEONLY in that data is delivered to the plug-in, through a series of calls to <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> and <a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write</a>, as it is saved to the file (as in mode NP_NORMAL). When the stream is complete, the browser calls <a href="/en/NPP_StreamAsFile" title="en/NPP_StreamAsFile">NPP_StreamAsFile</a> 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 <a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write</a>, and written to a file in the local cache.</li>
</ul>
<div class="note">
<p>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.</p>
</div>
<ul> <li>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 <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a>. 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. <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a> 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 <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a> call is made.</li>
</ul>
<div class="note">
<p>NOTE: In any mode other than NP_SEEK, the application should call <a href="/en/NPP_DestroyStream" title="en/NPP_DestroyStream">NPP_DestroyStream</a> 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 <a href="/en/NPN_DestroyStream" title="en/NPN DestroyStream">NPN_DestroyStream</a>.</p>
</div>
<h3 name="See_Also">See Also</h3>
<p><a href="/en/NPN_NewStream" title="en/NPN_NewStream">NPN_NewStream</a>, <a href="/en/NPP_StreamAsFile" title="en/NPP_StreamAsFile">NPP_StreamAsFile</a>, <a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write</a>, <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a>, <a href="/en/NPP_DestroyStream" title="en/NPP_DestroyStream">NPP_DestroyStream</a>, <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a>, <a href="/en/NPStream" title="en/NPStream">NPStream</a>, <a href="/en/NPN_GetURL" title="en/NPN_GetURL">NPN_GetURL</a></p>
<p>{{ languages( { "ja": "ja/NPP_NewStream" } ) }}</p>
Revert to this revision