This article needs a technical review. How you can help.
« Gecko Plugin API Reference « Plug-in Side Plug-in 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 inNP_SEEK
mode as long as the stream is inherently seekable;NPN_RequestRead()
automatically changes the mode toNP_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 modeNP_SEEK
, it returns the error codeNPERR_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.