# Network and Streams

Streams are objects representing URLs and the data in them. Streams are associated with a specific instance of a plug-in, and there can be more than one stream object per instance. Streams can be produced by Navigator and consumed by a plug-in instance, or produced by an instance and consumed by Navigator. Each stream has an associated MIME type identifying the format of the data in the stream.

Streams produced by Navigator can be automatically sent to the instance or explicitly requested by the plug-in. An initial stream is automatically sent to each full-page instance (containing the contents of the file that invoked the instance) and each embedded instance with a SRC attribute in its EMBED tag (containing the contents of the file specified by the SRC). Navigator informs an instance of the creation of a new stream with the API call NPP_NewStream, and of the deletion of a stream with the call NPP_DestroyStream.

Streams produced by Navigator can have one of several modes, selectable by the plug-in instance. In the default mode, stream data is "pushed" by Navigator to the instance incrementally as it is available, via the API NPP_Write. The plug-in instance may also place the stream in random-access mode, in which the stream data is "pulled" by the plug-in by calling Navigator's NPN_RequestRead API. In general this mode is more expensive, since unless the stream comes from a local file or an HTTP server supporting the proposed byte range extension to HTTP, the entire stream must be downloaded to a temporary file before use. A third mode simply saves the entire stream to a local file and passes the plug-in instance the path of the file via the API NPP_StreamAsFile. The use of this feature is strongly discouraged; plug-ins should implement an incremental stream-based interface wherever possible.

Streams produced by the plug-in for consumption by Navigator are analagous to default-mode streams produced by Navigator, but in reverse. Instead of Navigator calling the plug-in to inform it of the creation of the stream and push more data, the plug-in calls the Navigator API calls NPN_NewStream, NPN_Write, and NPN_DestroyStream to create a stream, push data into the stream, and delete the stream. Streams produced by a plug-in have a specific MIME type and can be sent to a particular Navigator window or frame for display.

Plug-ins may also retrieve data from or post data to a URL with all the network functionality of the Navigator. Data retrieved from a URL, via the API call NPN_GetURL, may be sent to a particular Navigator window or frame for display, or delivered to the plug-in instance in a new stream. Plug-ins can use this capability to provide hyperlinks to other documents or to retrieve data from anywhere on the network. Data posted to a URL, via the API call NPN_PostURL, may be contained in a memory buffer or file; the result from the server may also be sent to a particular Navigator window or frame for display, or delivered to the plug-in instance in a new stream. Plug-ins can use this capability to post form data to CGI scripts using HTTP or upload files to a remote server using FTP.