NPP_Write

  • Revision slug: NPP_Write
  • Revision title: NPP_Write
  • Revision id: 129374
  • Created:
  • Creator: Benjamin Smedberg
  • Is current revision? Yes
  • Comment Make the docs consistent and correct, and such.; 71 words removed

Revision Content

{{ Np-plugin-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.

See Also

NPP_DestroyStream, NPP_NewStream, NPP_WriteReady, NPStream, NPP

Revision Source

<p>
</p><p>
{{ Np-plugin-api() }}
</p>
<h3 id="Summary" name="Summary">Summary</h3>
<p>Delivers data to a plug-in instance.
(Remark: Hence the name "NPP_Write" is misleading - just think of:"Data_Arrived")
</p>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<pre>#include &lt;npapi.h&gt;
 
int32 NPP_Write(NPP instance, 
                NPStream* stream,
                int32 offset, 
                int32 len, 
                void* buf);
</pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<p>The function has the following parameters:
</p>
<dl><dt>instance
</dt><dd>Pointer to the current plug-in instance.
</dd></dl>
<dl><dt>stream
</dt><dd>Pointer to the current stream.
</dd></dl>
<dl><dt>offset
</dt><dd>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 <a href="en/NPN_RequestRead">NPN_RequestRead</a>.
</dd></dl>
<dl><dt>len
</dt><dd>Length in bytes of buf; number of bytes accepted.
</dd></dl>
<dl><dt>buf
</dt><dd>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.
</dd></dl>
<h3 id="Returns" name="Returns">Returns</h3>
<ul> <li>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 <a href="../../../../en/NPP_WriteReady" rel="internal">NPP_WriteReady</a> and <code>NPP_Write</code>.</li> <li>If unsuccessful, the function signals an error by returning a negative value. The browser will destroy the stream by calling <a href="/en/NPP_DestroyStream" title="en/NPP DestroyStream">NPP_DestroyStream</a>.</li>
</ul><h3 id="Description" name="Description">Description</h3>
<p>The browser calls the <code>NPP_Write</code> function to deliver the data specified in a previous <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> call to the plug-in. A plug-in must consume at least as many bytes as indicated in the <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> call.</p>
<p>After a stream is created by a call to <a href="/en/NPP_NewStream" title="en/NPP_NewStream">NPP_NewStream</a>, the browser calls <code>NPP_Write</code> either:</p>
<ul> <li>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 <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> and <code>NPP_Write</code>.</li> <li>If the plug-in requested a seekable stream, the <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a> function requests reads of a specified byte range that results in a series of calls to <a href="/en/NPP_WriteReady" title="en/NPP_WriteReady">NPP_WriteReady</a> and <code>NPP_Write</code>.</li>
</ul>
<p>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 <a href="/en/NPN_RequestRead" title="en/NPN_RequestRead">NPN_RequestRead</a> requests.</p><h3 id="See_Also" name="See_Also">See Also</h3>
<p><a href="en/NPP_DestroyStream">NPP_DestroyStream</a>, <a href="en/NPP_NewStream">NPP_NewStream</a>, <a href="en/NPP_WriteReady">NPP_WriteReady</a>, <a href="en/NPStream">NPStream</a>, <a href="en/NPP">NPP</a>
</p>
Revert to this revision