NPP_Write

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

Summary

Delivers data to a plug-in instance. (Remark: Hence the name "NPP_Write" is misleading - just think of:"Data_Arrived")

Syntax

#include <npapi.h>
 
int32 NPP_Write(NPP instance, 
                NPStream* stream,
                int32 offset, 
                int32 len, 
                void* buf);

Parameters

The function has the following parameters:

instance: Pointer to the current plug-in instance.

stream: Pointer to the current stream.

offset: Offset in bytes of buf from the beginning of the data in the stream. Can be used to check stream progress or by range requests from NPN_RequestRead.

len: Length in bytes of buf; number of bytes accepted.

buf: Buffer of data, delivered by the stream, that contains len bytes of data offset bytes from the start of the stream. The buffer is allocated by the browser and is deleted after returning from the function, so the plug-in should make a copy of the data it needs to keep.

Returns

The plug-in should return the number of bytes written (consumed by the instance). If the return value is smaller than the size of the buffer, the browser sends the remaining data to the plug-in through subsequent calls to NPP_WriteReady and NPP_Write.
If unsuccessful, the function signals an error by returning a negative value. The browser will destroy the stream by calling NPP_DestroyStream.

Description

The browser calls the NPP_Write function to deliver the data specified in a previous NPP_WriteReady call to the plug-in. A plug-in must consume at least as many bytes as indicated in the NPP_WriteReady call.

After a stream is created by a call to NPP_NewStream, the browser calls NPP_Write either:

If the plug-in requested a normal-mode stream, the data in the stream is delivered to the plug-in instance in a series of calls to NPP_WriteReady and NPP_Write.
If the plug-in requested a seekable stream, the NPN_RequestRead function requests reads of a specified byte range that results in a series of calls to NPP_WriteReady and NPP_Write.

The plug-in can use the offset parameter to track the bytes that are written. This gives you different information depending in the type of stream. In a normal-mode stream., the parameter value increases as the each buffer is written. The buf parameter is not persistent, so the plug-in must process data immediately or allocate memory and save a copy of it. In a seekable stream with byte range requests, you can use this parameter to track NPN_RequestRead requests.