Stream Methods

NPP_DestroyStream 

NPN_DestroyStream

NPP_NewStream 

NPN_NewStream

NPP_StreamAsFile

NPN_RequestRead 

NPP_Write

NPN_Write 

NPP_WriteReady 

Streams represent URLs and the data they contain or data sent by a plug-in without an associated URL. A stream is associated with a specific instance of a plug-in, but a plug-in can have more than one stream object per instance.

The methods in this reference handle streams. See Chapter 5, "Streams," for information about using these methods.

[Top] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPP_DestroyStream

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPP_DestroyStream(NPP       instance, 
                          NPStream* stream, 
                          NPReason  reason);

Parameters

instance

stream

reason

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.

Description

You should delete any private data allocated in stream->pdata at this time, and should not make any further references to the stream object.

See Also

NPP_NewStream, NPN_DestroyStream, NPStream, NPP

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPP_NewStream

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPP_NewStream(NPP        instance, 
                      NPMIMEType type,
                      NPStream   *stream,
                      NPBool     seekable,
                      uint16*    stype);

Parameters

instance

type

stream

seekable

stype

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.

Description

The data in the stream can be the file specified in the SRC attribute of the EMBED tag, for an embedded instance, or the file itself, for a full-page instance. A plug-in can also request a stream with the function NPN_GetURL. Communicator calls NPP_DestroyStream when the stream completes (either successfully or abnormally). The plug-in can terminate the stream itself by calling NPN_DestroyStream.

The parameter stype defines the mode of the stream. Values:

• NP_NORMAL (Default): Delivers stream data to the instance in a series of calls to NPP_WriteReady and NPP_Write. The plug-in can process the data progressively as it arrives from the network or file system.
• NP_ASFILEONLY: New in Netscape Navigator 3.0. Communicator saves stream data to a file in the local cache. When the stream is complete, Communicator calls NPP_StreamAsFile to deliver the path of the file to the plug-in. If the stream comes from a local file, the NPP_Write and NPP_WriteReady functions are not called. NPP_StreamAsFile is simply called immediately. This mode allows the plug-in full random access to the data using platform-specific file operations.
• NP_ASFILE: File download. Differs from NP_ASFILEONLY in that data is delivered to the plug-in, through a series of calls to NPP_Write and NPP_Write, as it is saved to the file (as in mode NP_NORMAL). When the stream is complete, Communicator calls NPP_StreamAsFile to deliver the path of the file to the plug-in. If the data in the stream comes from a file that is already local, the data is read, sent to the plug-in through NPP_Write, and written to a file in the local cache.

NOTE: Most plug-ins that need the stream saved to a file should use the more efficient mode NP_ASFILEONLY (above); this mode is preserved for compatibility only. §

• NP_SEEK: Stream data is not automatically delivered to the instance, but can be randomly accessed by the plug-in as needed, through calls to NPN_RequestRead. If the stream is not seekable, placing the stream in NP_SEEK mode causes Communicator to save the entire stream to the disk cache. NPN_RequestRead requests are only fulfilled when all data has been read and stored in the cache. As an optimization to extract the maximum benefit from existing network connections, Communicator continues to read data sequentially out of the stream (as in mode NP_NORMAL) until the first NPN_RequestRead call is made.

NOTE: In any mode other than NP_SEEK, the application should call NPP_DestroyStream once all data in the stream has been written to the plug-in. The plug-in can also request termination of the stream at any time by calling NPN_DestroyStream. §

See Also

NPN_NewStream, NPP_StreamAsFile, NPP_Write, NPP_WriteReady, NPP_DestroyStream, NPN_RequestRead, NPStream, NPN_GetURL

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPP_StreamAsFile

Plug-in API Type

Syntax

#include <npapi.h>
void NPP_StreamAsFile(NPP        instance,
                      NPStream*  stream,
                      const char* fname);

Parameters

instance

stream

fname

Description

If an error occurs while retrieving the data or writing the file, the file name (fname) is null.

See Also

NPP_NewStream, NPP_Write, NPP_WriteReady, NPStream, NPP

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPP_Write

Plug-in API Type

Syntax

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

Parameters

instance

stream

offset

len

buf

Returns

• If successful, the function returns the number of bytes consumed by the instance.
• If unsuccessful, the function destroys the stream by returning a negative value.

Description

After a stream is created by a call to NPP_NewStream, Communicator 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 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. A negative return value causes an error on the stream, which causes Communicator to destroy the stream with NPP_DestroyStream.

See Also

NPP_DestroyStream, NPP_NewStream, NPP_WriteReady, NPStream, NPP

NPP_WriteReady

Plug-in API Type

Syntax

#include <npapi.h>
int32 NPP_WriteReady(NPP instance, NPStream* stream);

Parameters

instance

stream

Returns

Description

Communicator calls NPP_WriteReady before each call to NPP_Write to determine whether a plug-in can receive data and how many bytes it can receive. This function allows Communicator to send only as much data to the instance as it can handle at one time, making resource use more efficient for both Communicator and plug-in.

The NPP_Write function may pass a larger buffer, but the plug-in is required to consume only the amount of data returned by NPP_WriteReady.

The browser can write a smaller amount of data if desired or necessary; for example, if only 8K of data is available in a network buffer. If the plug-in is allocating memory for the entire stream at once (an AS_FILE stream), it can return a very large number. Because it is not processing streaming data, Communicator can pass as much data to the instance as necessary in a single NPP_Write.

If the plug-in receives a value of zero, the data flow temporarily stops. Communicator checks to see if the plug-in can receive data again by resending the data at regular intervals.

See Also

NPP_Write, NPStream, NPP

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_DestroyStream

Closes and deletes a stream

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPN_DestroyStream(NPP       instance,
                          NPStream* stream, 
                          NPError   reason);

Parameters

instance

stream

reason

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.

Description

See Also

NPP_DestroyStream, NPN_NewStream, NPStream, NPP

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_NewStream

Requests the creation of a new data stream produced by the plug-in and consumed by Communicator

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPN_NewStream(NPP         instance,
                      NPMIMEType  type, 
                      const char* target,
                      NPStream**  stream);

Parameters

instance

type

target

stream

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.

Description

NPN_NewStream creates a new stream of data produced by the plug-in and consumed by Communicator.

The MIME parameter is the MIME type of the plug-in to create. A plug-in can create another instance of itself by specifying its own MIME type and a new target name in a call to NPN_NewStream.

The stream is returned in the stream parameter. The plug-in can use this object in subsequent calls to NPN_Write to write data into the stream. When the plug-in has written all of its data into the stream, NPN_DestroyStream terminates the stream and deallocates the NPStream object.

The target parameter is the name of the target window or frame, or one of several special target names. For parameter values and information about how to use them, see NPN_GetURL. If the new stream has the target of _self, this function should return an INVALID_PARAM NPError.

For more information on named targets, see the Netscape document, "Targeting Windows."

WARNING: In Navigator 3.0, if the target parameter refers to the window or frame that contains the plug-in instance (for example, _current), Communicator returns an NPERR_INVALID_PARM error code to NPN_NewStream. This error occurs if you use _self or any other call that resolves to _self, which includes the _top target when the top frame is the current instance, or the _parent target when the current target has no parent. §

See Also

NPP_NewStream, NPP_Write, NPP_DestroyStream, NPStream, NPP

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_RequestRead

Plug-in API Type

Syntax

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

Parameters

stream

rangeList

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.

Description

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.

A NAME="1086850">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), Communicator 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 Communicator 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 Communicator 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.

See Also

NPP_NewStream, NPStream

NPN_Write

Pushes data into a stream produced by the plug-in and consumed by Communicator

Plug-in API Type

Syntax

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

Parameters

instance

stream

len

buf

Returns

• If successful, the function returns a positive integer representing the number of bytes written (consumed by Communicator). This number depends on the size of Communicator's memory buffers, the number of active streams, and other factors.
• If unsuccessful, the plug-in returns a negative integer. This indicates that Communicator encountered an error while processing the data, so the plug-in should terminate the stream by calling NPN_DestroyStream.

Description

See Also

NPP_NewStream, NPP_DestroyStream, NPP_Write, NPStream, NPP

[Top] [Stream Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

URL Methods

NPP_URLNotify

NPN_PostURL

NPN_GetURL

NPN_PostURLNotify

NPN_GetURLNotify

Plug-ins can retrieve data from or post data to a URL with all the network functionality of Netscape Communicator. These Netscape and Plug-in methods support URL access. See Chapter 6, "URLs," for information about using these methods.

[Top] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPP_URLNotify

Notifies the instance of the completion of a URL request made by NPN_GetURLNotify or NPN_PostURLNotify

Plug-in API Type

Syntax

#include <npapi.h>
void NPP_URLNotify(NPP         instance, 
                   const char* url,
                   NPReason    reason, 
                   void*       notifyData);

Parameters

instance

url

reason

notifyData

Description

The most common reason code is NPRES_DONE, indicating simply that the request completed normally. Other possible reason codes are NPRES_USER_BREAK, indicating that the request was halted due to a user action (for example, clicking the Stop button), and NPRES_NETWORK_ERR, indicating that the request could not be completed, perhaps because the URL could not be found.

The parameter notifyData is the plug-in-private value passed as an argument by a previous NPN_GetURLNotify or NPN_PostURLNotify call, and can be used as an identifier for the request.

See Also

NPN_GetURLNotify, NPN_GetURL, NPN_PostURLNotify, NPN_PostURL

NPN_GetURL

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPN_GetURL(NPP instance, 
                   const char* url,
                   const char* target);

Parameters

instance

url

target

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.

Description

For HTTP URLs, Communicator resolves this method as the HTTP server method GET, which requests URL objects.

Use NPN_PostURLNotify instead of NPN_PostURL in these cases:

• To request a stream and receive notification of the result.
• If the buffer contains header information (even a blank line).

If the target parameter refers to the window or frame containing the current plug-in instance, the instance is destroyed and the plug-in may be unloaded. If target is null, the application creates a new stream and delivers the data to the plug-in instance, through calls to NPP_NewStream, NPP_WriteReady and NPP_Write, and NPP_DestroyStream. This means that, if you want the plug-in to handle a new stream, no matter what the MIME type is, use null. If the application cannot locate the URL and retrieve the data, it does not create a stream for the instance.

When the plug-in instance is part of a regular Navigator window, and it uses a _blank target with a mailto or news URL, another blank navigator window is opened along with the mail or news window.

When the plug-in uses a _self target, no other instance is created; the plug-in usually continues to operate successfully in its own window. The safest target is _blank, even though this creates an extra blank Communicator instance.

For complete information on named targets for this function (as well as for normal HTML links), see the Netscape document, "Targeting Windows."

The plug-in developer cannot influence the way that Communicator handles NPN_GetURL. It is typically asynchronous but this is not guaranteed. The plug-in could call NPN_GetURL and receive data from the URL right away, but more often the data arrives later. The rest of the Communicator interface keeps running until the data is available.

NOTE: In Navigator 2.x or earlier, this method cannot reference relative URLs. §

See Also

NPN_GetURLNotify, NPN_PostURL, NPN_PostURLNotify, NPP_URLNotify

NPN_GetURLNotify

Requests creation of a new stream with the contents of the specified URL; gets notification of the result by calling NPP_URLNotify

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPN_GetURLNotify(NPP    instance,
                         const  char* url, 
                         const  char* target,
                         void*   notifyData);

Parameters

instance

url

target

notifyData

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.

Description

NPN_GetURLNotify typically handles the URL request asynchronously. It returns immediately and only later handles the request and calls NPP_URLNotify. This notification is the only way the plug-in can tell whether a request with a null target failed, or that a request with a non-null target completed.

For requests that complete unsuccessfully, Communicator calls NPP_URLNotify as soon as possible.

For requests that complete successfully:

• If the target is non-null, Communicator calls NPP_URLNotify after it has finished loading the URL.
• If the target is null, Communicator calls NPP_URLNotify after closing the stream by calling NPN_DestroyStream.

See Also

NPN_GetURL, NPN_PostURL, NPN_PostURLNotify, NPP_URLNotify, NPP

NPN_PostURL

Called by the plug-in to post data from a file or buffer to a URL

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPN_PostURL(NPP instance, const char *url,
                    const char *target, uint32 len,
                    const char *buf, NPBool file);

Parameters

instance

url

target

len

buf

file

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.

Description

• NPN_GetURL reads data from the URL and either displays it in the target window or delivers it to the plug-in.
• NPN_PostURL writes data from a file or buffer to the URL and either displays the server's response in the target window or delivers it to the plug-in. If the target parameter is null, the new stream is passed to the plug-in regardless of MIME type.

• If target is null, the server response is sent back to the plug-in. You can get the data and save it in a file or use it in a program.
• If you specify _current, _self, or _top, the response data is written to the same plug-in window and the plug-in is unloaded.
• If you specify _new or _blank, the response data is written to a new browser window. You can also write the response data to a frame by specifying the frame name as the target parameter.

The data to post can be contained either in a local temporary file or a new memory buffer.

• To post to a temporary file, set the flag file to true, the buffer buf to the path name string for a file, and len to the length of the path string. The file-type URL prefix "file://" is optional.

MS Windows and Mac OS

• To post data from a memory buffer, set the flag file to false, the buffer buf to the data to post, and len to the length of buffer.

You cannot use NPN_PostURL to specify headers (even a blank line) in a memory buffer. To do this, use NPN_PostURLNotify.

For protocols in which the headers must be distinguished from the body, such as HTTP, the buffer or file should contain the headers, followed by a blank line, then the body. If no custom headers are required, simply add a blank line ('\n') to the beginning of the file or buffer.

NPN_PostURL is typically asynchronous: it returns immediately and only later handles the request. For this reason, you may find it useful to call NPN_PostURLNotify instead; this function notifies your plug-in upon successful or unsuccessful completion of the request.

NOTE: In Navigator 2.x or earlier, this method cannot reference relative URLs. §

See Also

NPN_GetURL, NPN_GetURLNotify, NPN_PostURLNotify, NPP_URLNotify, NPP

NPN_PostURLNotify

Posts data to a URL; gets notification of the result by calling NPP_URLNotify

Plug-in API Type

Syntax

#include <npapi.h>
NPError NPN_PostURLNotify(NPP         instance,
                          const char* url, 
                          const char* target,
                          uint32      len, 
                          const char* buf,
                          NPBool      file, 
                          void*       notifyData);

Parameters

instance

url

target

len

buf

file

notifydata

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.

Description

• NPN_PostURLNotify supports specifying headers when posting a memory buffer.
• NPN_PostURLNotify calls NPP_URLNotify upon successful or unsuccessful completion of the request. For more information, see NPN_PostURL.

If this function is called with a target parameter value of _self or a parent to _self, this function should return an INVALID_PARAM NPError. This is the only way to notify the plug-in once it is deleted. See NPN_GetURL for information about this parameter.

See Also

NPN_GetURL, NPP_URLNotify, NPN_PostURL