mozilla

Revision 73990 of NPN_RequestRead

  • Revision slug: NPN_RequestRead
  • Revision title: NPN_RequestRead
  • Revision id: 73990
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 1 words removed

Revision Content

{{ Np-plugin-api() }}

Summary

Requests a range of bytes from a seekable stream. This initiates a read operation; the actual data is received through subsequent calls to NPP_WriteReady() and NPP_Write().

Syntax

#include <npapi.h>
 
NPError NPN_RequestRead(NPStream*    stream,
                        NPByteRange* rangeList);

Parameters

The function has the following parameters:

stream
Stream of type NP_SEEK from which to read bytes.
rangeList
Range of bytes in the form of a linked list of NPByteRange objects, each of which specifies a request for a range of bytes.

Returns

  • If successful, the function returns NPERR_NO_ERROR.
  • If unsuccessful, the function returns an error code. For possible values, see Error Codes.

Description

For a seekable stream, the browser sends data only in response to requests by the plug-in. The plug-in calls NPN_RequestRead() to request data from a seekable stream.

The plug-in can use this function to make one or more requests for ranges of bytes. These requests result in subsequent calls to NPP_WriteReady() and NPP_Write(). For multiple requests, the function creates a linked list of NPByteRange structures, each of which represents a separate request.

If the plug-in requests multiple ranges (either through a list of NPByteRange objects in a single call to NPN_RequestRead(), or multiple calls to NPN_RequestRead()), the browser can write individual ranges in any order, and with any number of NPP_WriteReady() and NPP_Write() calls.

The plug-in must allocate NPByteRange objects, which the browser copies if necessary. The plug-in can free these as soon as the call returns.

Seekable streams are created by calling NPP_NewStream() with NP_SEEK as the stype mode.

  • The plug-in can call NPN_RequestRead() on streams that were not initially in NP_SEEK mode as long as the stream is inherently seekable; NPN_RequestRead() automatically changes the mode to NP_SEEK.
  • If the stream is not inherently seekable, the stream must have been put in NP_SEEK mode initially (since the browser must cache all the stream data on disk in order to access it randomly).
  • If NPN_RequestRead() is called on a stream that is not inherently seekable and not initially in mode NP_SEEK, it returns the error code NPERR_STREAM_NOT_SEEKABLE.

Typically, the only streams that are inherently seekable are those from in-memory or on-disk data, or from HTTP servers that support byte-range requests.

See also

Revision Source

<p>{{ Np-plugin-api() }}</p>
<h3 id="Summary" name="Summary">Summary</h3>
<p>Requests a range of bytes from a seekable stream. This initiates a read operation; the actual data is received through subsequent calls to <code><a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady()</a></code> and <code><a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write()</a></code>.</p>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<pre>#include &lt;npapi.h&gt;
 
NPError NPN_RequestRead(NPStream*    stream,
                        NPByteRange* rangeList);
</pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<p>The function has the following parameters:</p>
<dl> <dt><code>stream</code></dt> <dd>Stream of type <code>NP_SEEK</code> from which to read bytes.</dd>
</dl>
<dl> <dt><code>rangeList</code></dt> <dd>Range of bytes in the form of a linked list of <a href="/en/NPByteRange" title="en/NPByteRange"><code>NPByteRange</code></a> objects, each of which specifies a request for a range of bytes.</dd>
</dl>
<h3 id="Returns" name="Returns">Returns</h3>
<ul> <li>If successful, the function returns <code>NPERR_NO_ERROR</code>.</li> <li>If unsuccessful, 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 id="Description" name="Description">Description</h3>
<p>For a seekable stream, the browser sends data only in response to requests by the plug-in. The plug-in calls <code>NPN_RequestRead()</code> to request data from a seekable stream.</p>
<p>The plug-in can use this function to make one or more requests for ranges of bytes. These requests result in subsequent calls to <code><a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady()</a></code> and <code><a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write()</a></code>. For multiple requests, the function creates a linked list of <a href="/en/NPByteRange" title="en/NPByteRange"><code>NPByteRange</code></a> structures, each of which represents a separate request.</p>
<p>If the plug-in requests multiple ranges (either through a list of <a href="/en/NPByteRange" title="en/NPByteRange"><code>NPByteRange</code></a> objects in a single call to <code>NPN_RequestRead()</code>, or multiple calls to <code>NPN_RequestRead()</code>), the browser can write individual ranges in any order, and with any number of <code><a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady()</a></code> and <code><a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write()</a></code> calls.</p>
<p>The plug-in must allocate <a href="/en/NPByteRange" title="en/NPByteRange"><code>NPByteRange</code></a> objects, which the browser copies if necessary. The plug-in can free these as soon as the call returns.</p>
<p>Seekable streams are created by calling <code><a href="/en/NPP_NewStream" title="en/NPP_NewStream">NPP_NewStream()</a></code> with <code><a href="/en/NP_SEEK" title="en/NP_SEEK">NP_SEEK</a></code> as the stype mode.</p>
<ul> <li>The plug-in can call <code>NPN_RequestRead()</code> on streams that were not initially in <code><a href="/en/NP_SEEK" title="en/NP_SEEK">NP_SEEK</a></code> mode as long as the stream is inherently seekable; <code>NPN_RequestRead()</code> automatically changes the mode to <code><a href="/en/NP_SEEK" title="en/NP_SEEK">NP_SEEK</a></code>.</li> <li>If the stream is not inherently seekable, the stream must have been put in <code><a href="/en/NP_SEEK" title="en/NP_SEEK">NP_SEEK</a></code> mode initially (since the browser must cache all the stream data on disk in order to access it randomly).</li> <li>If <code>NPN_RequestRead()</code> is called on a stream that is not inherently seekable and not initially in mode <code><a href="/en/NP_SEEK" title="en/NP_SEEK">NP_SEEK</a></code>, it returns the error code <code>NPERR_STREAM_NOT_SEEKABLE</code>.</li>
</ul>
<p>Typically, the only streams that are inherently seekable are those from in-memory or on-disk data, or from HTTP servers that support byte-range requests.</p><h3 id="See_Also" name="See_Also">See also</h3>
<ul> <li><code><a href="/en/NPP_NewStream" title="en/NPP_NewStream">NPP_NewStream()</a></code></li> <li><code><a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady()</a></code></li> <li><code><a href="/en/NPP_Write" title="en/NPP_Write">NPP_Write()</a></code></li> <li><code><a href="/en/NPStream" title="en/NPStream">NPStream</a></code></li>
</ul>
Revert to this revision