Chapter 5
Streams

This chapter describes using Plug-in API functions to receive and send streams.

Streams are objects that represent URLs and the data they contain, or data sent by a plug-in without an associated URL. Although a single stream is associated with one specific instance of a plug-in, a plug-in can have more than one stream object per instance. Streams can be produced by Netscape Communicator and consumed by a plug-in instance, or produced by an instance and consumed by Communicator. Each stream has an associated MIME type identifying the format of the data in the stream.

Streams produced by Communicator can be automatically sent to or requested by the plug-in instance. Communicator calls the Plug-in methods NPP_NewStream, NPP_WriteReady, NPP_Write, and NPP_DestroyStream to, respectively, create a stream, find out how much data the plug-in can handle, push data into the stream, and delete it.

The plug-in instance selects a transmission mode for streams produced by Communicator. Stream data can be pushed by Communicator, pulled by the plug-in, or saved to a local file and passed to the plug-in.

• Normal mode: Communicator uses the NPP_Write method to "push" stream data to the instance incrementally as it is available.
• Random-access mode: The plug-in calls the NPN_RequestRead method to "pull" stream data. In general, this mode is more expensive, because the entire stream must be downloaded to a temporary file before use unless the stream comes from a local file or an HTTP server that supports the proposed byte-range extension to HTTP.
• File mode: Communicator saves the entire stream to a local file and passes the file path to the plug-in instance through the NPP_StreamAsFile method. Use this feature only as a last resort; plug-ins should implement an incremental stream-based interface wherever possible.

For a detailed description of the methods discussed in this chapter, see "Stream Methods" in the API reference.

• Receiving a Stream
• Sending a Stream

• Telling the Plug-in When a Stream Is Created
• Telling the Plug-in When a Stream Is Deleted
• Finding Out How Much Data the Plug-in Can Accept
• Writing the Stream to the Plug-in
• Sending the Stream in Random-Access Mode
• Sending the Stream in File Mode

• for the file specified in the SRC attribute of the EMBED tag
• for a data file
• for a full-page instance

NPError NPP_NewStream(NPP instance, NPMIMEType type,
                        NPStream *stream, NPBool seekable, uint16* stype);

The stream parameter is a pointer to the new stream, which is valid until the stream is destroyed.

The seekable parameter specifies whether the stream is seekable (true) or not (false). Seekable streams support random access (for example, local files or HTTP servers that support byte-range requests).

The plug-in can set the output parameter stype to one of these transmission modes:

• NP_NORMAL (Default): The plug-in can process the data progressively as it arrives from the network or file system through series of calls to NPP_WriteReady and NPP_Write.
• NP_ASFILEONLY: New in Netscape Navigator 3.0. This plug-in gets full random access to the data using platform-specific file operations. Communicator saves stream data to a local file, and, when the stream is complete, delivers the path of the file through a call to NPP_StreamAsFile.
• NP_ASFILE: This mode is like NP_ASFILEONLY except that data is delivered to the plug-in as it is saved to the file, through a series of calls to NPP_Write. You should use NP_ASFILEONLY whenever possible in preference to NP_ASFILE, which is less efficient because it uses successive calls to NPP_Write to send the data.
• NP_SEEK: The plug-in instance can randomly access stream data as needed, through calls to NPN_RequestRead. If the stream is not seekable, these requests are fulfilled only when all the data has been read and stored in the cache.

NOTE: A plug-in can also use the NPN_GetURL method to request a stream for an arbitrary URL. §

You should delete any private data allocated in the plug-in's stream->pdata field when you destroy a stream. The plug-in can store private data associated with the stream in stream->pdata. Communicator stores private data in stream->ndata; this value should not be changed by the plug-in.

NPError NPP_DestroyStream(NPP instance, 
                            NPStream *stream, NPError reason);

The reason parameter specifies why the stream was destroyed. It can have one of these values:

• NPRES_DONE (Most common): Normal completion; all data was sent to the instance.
• NPRES_USER_BREAK: The user canceled the stream directly by clicking the Stop button or indirectly by some action, such as by deleting the instance or initiating higher-priority network operations.
• NPRES_NETWORK_ERR: The stream failed because of problems with the network, disk I/O error, lack of memory, or some other problem.

After a call to NPP_NewStream, in which the plug-in requested a normal-mode stream, Communicator delivers the data in the stream progressively in a series of calls to NPP_WriteReady and NPP_Write. Communicator calls NPP_WriteReady before each call to NPP_Write.

The value returned by NPP_WriteReady indicates how many bytes the plug-in instance can accept for this stream. If the plug-in allocates memory for the entire stream at once, it can return a large number. This number tells Communicator that it can pass as much data to the instance as possible in a single call to NPP_Write. Communicator can write a smaller amount of data if desired or necessary (for example, if only 8K of data is available in a network buffer).

For instance, suppose the plug-in allocates, in NPP_NewStream, an 8K buffer to hold the data written from that stream. In the first call, NPP_WriteReady could return 8192, resulting in a call to NPP_Write with a buffer of up to 8K bytes. After this data is copied from Communicator's buffer to the plug-in's buffer, the plug-in begins to process the data asynchronously. At the next NPP_WriteReady call, only half of the data has been processed. To avoid allocating additional buffers, the plug-in could return 4096, resulting in a call to NPP_Write with a buffer of up to 4K bytes.

The buffer passed to NPP_Write may accommodate more bytes than the maximum number returned from NPP_WriteReady. This maximum is only a promise to consume a certain amount of data from the buffer, not an upper limit on the buffer size. In the example above, suppose that the plug-in allocates an 8K buffer and returns 8192 from NPP_WriteReady. If the plug-in gets 10000 bytes from Communicator in a subsequent call to NPP_Write, the plug-in should copy the first 8192 bytes from Communicator's buffer into its own buffer and return 8192 (the number of bytes actually consumed) from NPP_Write.

int32 NPP_WriteReady(NPP instance, NPStream *stream);

[Top] [Receiving a Stream]

The NPP_Write function should return the number of bytes consumed by the instance. If this is a negative number, Communicator calls NPP_DestroyStream to destroy the stream. If the number returned is smaller than the size of the buffer, Communicator sends the remaining data in the buffer to the plug-in through repeated calls to NPP_WriteReady and NPP_Write.

int32 NPP_Write(NPP instance, NPStream *stream,
                 int32 offset, int32 len, void *buf);

As an example, suppose that a plug-in (and the HTTP server) supports byte-range requests, and that Communicator is in the process of pushing data to the plug-in. If the user now requests a specific page of the document, the plug-in calls NPN_RequestRead with a list of byte ranges. The open stream is converted from normal mode to seek mode in an effort to pass the plug-in the data that was already on the way, rather than just discarding it. All NPP_Write calls for streaming data eventually stop, and NPP_Write calls will be completed only for data requested with NPN_RequestRead.

Communicator does not create a new stream for each byte range it requests. Instead, additional NPP_WriteReady and NPP_Write calls occur on the same stream. An individual call to NPN_RequestRead can request discontiguous ranges, and you can have many outstanding NPN_RequestRead calls. There is no guarantee that NPP_Write will receive requests for ranges in the same order as you requested (although this typically is the case; the server controls the order). So, you'll need to pay attention to the offsets as data is being written.

The stream processes all byte-range requests, and then is placed in seek mode (either explicitly in NPP_NewStream, or implicitly by a call to NPN_RequestRead). It remains open until the plug-in closes it by calling NPN_DestroyStream, or until the instance is destroyed.

NOTE: If you want to be sure that the NPN_*Stream functions are called in the order you want and behave the way you expect, combine NPN_NewStream, NPN_Write, and NPN_Destroy_Stream in the same callback. §

Random-access mode is determined in NPP_NewStream by setting the mode NP_SEEK. This mode gives the plug-in instance random access to stream data as needed, through calls to NPN_RequestRead. If the stream is not seekable, these requests are fulfilled only when all the data has been read and stored in the cache.

The NPN_RequestRead method requests a range of bytes from a seekable stream. Typically, the only streams that are seekable are from data that is in memory or on the disk, or from HTTP servers that support byte-range requests.

• For streams that are not in NP_SEEK mode: The plug-in can call NPN_RequestRead as long as the stream is inherently seekable; NPN_RequestRead automatically changes the mode to NP_SEEK.
• For streams that are not inherently seekable: The stream must be put in NP_SEEK mode initially, because Communicator must cache all the stream data on disk in order to access it randomly.
• For streams that are not inherently seekable and not initially in mode NP_SEEK: NPN_RequestRead returns the error code NPERR_STREAM_NOT_SEEKABLE.

NPError NPN_RequestRead(NPStream *stream, NPByteRange *rangeList);

The plug-in can request multiple ranges, either through a list of NPByteRange objects in a single call to NPN_RequestRead or through multiple calls to NPN_RequestRead. In this case, Communicator can write individual ranges in any order, with any number of NPP_WriteReady and NPP_Write calls.

[Top] [Receiving a Stream]

File mode is determined in NPP_NewStream by setting the mode NP_ASFILEONLY. This mode gives the plug-in full random access to the data with platform-specific file operations. Communicator saves stream data to a local file, and, when the stream is complete, delivers the path of the file through a call to NPP_StreamAsFile.

NOTE: Most plug-ins that need the stream saved to a file should use NP_ASFILEONLY mode rather than the older NP_ASFILE; this mode is less efficient because it uses successive calls to NPP_Write. §

void NPP_StreamAsFile(NPP instance, NPStream *stream, 
                        const char* fname);

[Top] [Receiving a Stream]

• Creating a Stream
• Pushing Data into the Stream
• Deleting the Stream

[Top] [Sending a Stream]

The plug-in can use this stream object in subsequent NPN_Write calls to Communicator. When all the plug-in data is written into the stream, the plug-in must terminate the stream and deallocate the NPStream object by calling the NPN_DestroyStream function.

NPError NPN_NewStream(NPP instance,
                      NPMIMEType type, 
                      const char* target,
                      NPStream** stream);

The target parameter specifies the window or frame. For the possible values for named targets, see the reference entry for NPN_NewStream. The target should not be the same window.

The stream parameter represents the stream that Communicator creates.

For an example that demonstrates using this function with NPN_Write and NPN_DestroyStream, see "Example of Sending a Stream."

[Top] [Sending a Stream]

int32 NPN_Write(NPP instance, NPStream *stream,
                int32 len, void *buf);

The instance parameter is the current plug-in; the stream parameter is a pointer to the stream being written to. The len parameter specifies the length, in bytes, of data written to the stream. The buf parameter is a pointer to the buffer holding the data to write to the stream.

For an example that demonstrates using this function with NPN_NewStream and NPN_DestroyStream, see "Example of Sending a Stream."

[Top] [Sending a Stream]

NPError NPN_DestroyStream(NPP instance, NPStream* stream, 
                           NPError reason);

• NPRES_DONE (most common): The stream completed normally; the plug-in sent all data to Communicator.
• NPRES_USER_BREAK: The plug-in terminated the stream because of a user request.
• NPRES_NETWORK_ERR: The stream failed because of network problems.

For an example that demonstrates using this function with NPN_NewStream and NPN_Write, see "Example of Sending a Stream."

[Top] [Sending a Stream]

NPStream* stream;
char* myData = "<HTML><B>This is a message from my plug-in!</B></HTML>";
int32 myLength = strlen(myData) + 1;

/* Create the stream. */
err = NPN_NewStream(instance, "text/html", "_blank", &stream);

/* Push data into the stream. */
err = NPN_Write(instance, stream, myLength, myData);

/* Delete the stream. */
err = NPN_DestroyStream(instance, stream, NPRES_DONE);

[Top] [Sending a Stream]

Last Updated: 01/15/97 16:36:52