Skip to main content

Visit Mozilla.org

NPN RequestRead

From MDC

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

Contents

[edit] Summary

Requests a range of bytes for a seekable stream.

[edit] Syntax

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

[edit] Parameters

The function has the following parameters:

stream
Stream of type NP_SEEK from which to read bytes. Communicator writes the requested bytes to the plug-in through subsequent calls to NPP_WriteReady and NPP_Write.
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.

[edit] 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.

[edit] 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 toNPN_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_RequestReadautomatically 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.

[edit] See Also

NPP_NewStream, NPStream

Retrieved from "http://developer.mozilla.org/en/docs/NPN_RequestRead"