Closes and deletes a stream.
The NPN_DestroyStream function closes and deletes the stream identified by stream for the plug-in instance denoted by instance. The stream can be either a stream that Netscape created and passed to the plug-in in NPP_NewStream, or a stream created by the plug-in via a call to NPN_NewStream.
The reason the stream was destroyed is indicated by the by the parameter reason. The most common reason code is NPRES_DONE, indicating simply that the stream completed normally because all data was sent by the plug-in to Netscape. Other possible reason codes are NPRES_USER_BREAK, indicating that the plug-in is terminating the stream due to a user request, and NPRES_NETWORK_ERR, indicating that the stream failed due to network problems. The complete list of reason codes is found in npapi.h.
Returns the Java execution environment, needed to make any calls to Java methods from your plug-in using the JRI. For more information, read about accessing Java methods from plug-ins.
Returns the Java object associated with the plug-in instance. For more information, read about calling plug-in native methods from Java.
NPN_GetURL requests the creation of a new stream for the URL identified by url for the plug-in instance specified by instance. The parameter target determines the recipient of the stream. Note that this operation is asynchronous: control will always immediately return to your plug-in, but the stream will not be created until some point in the future, or never created in the event of network problems or user cancellation.
If target is non-NULL, the stream is sent to Netscape and Netscape displays the contents of the stream in the named target window or frame. (For more information on named targets, see Netscape's documentation on targeting windows.) Note that if the target refers to the window or frame containing the instance, the instance will be destroyed and the plug-in may be unloaded. For example, a plug-in instance could draw a button that acts like a link to another web page. When the user clicks the button, the plug-in would call NPN_GetURL to go to the page:
Note that NPN_GetURL is typically asynchronous: it returns immediately and only later handles the request. For this reason you may find it useful to instead call NPN_GetURLNotify so your plug-in is notified upon successful or unsuccessful completion of the request.
Requests that a new stream be created with the contents of the specified URL, and receives notification of the result.
NPN_GetURLNotify functions identically to NPN_GetURL except that it calls NPN_URLNotify upon successful or unsuccessful completion of the request. The parameter notifyData is a plug-in-private value that can be used to uniquely identify the request; it will be returned to the plug-in as a parameter to the corresponding NPP_URLNotify call. Note that NPN_GetURLNotify is typically asynchronous: it returns immediately and only later handles the request and calls NPP_URLNotify.
Call NPN_MemAlloc to allocate size bytes of memory in the Navigator's memory space. Netscape returns NULL if insufficient memory is available. NPN_MemAlloc is particularly important on the Macintosh, since the Macintosh version of Netscape Navigator frequently fills its memory partition with cached data which is only purged as necessary. Since NPN_MemAlloc automatically frees cached information if necessary to fulfill the request, calls to NPN_MemAlloc may succeed where direct calls to NewPtr() would fail.
If you allocate saved instance data in NPP_Destroy, be sure to allocate the memory with this function, since Netscape may delete the saved data with the equivalent of NPN_MemFree at any time. See the code example in the documentation for NPP_Destroy for an example of allocating saved data using this function.
Requests that Navigator free size bytes of memory, and returns the amount freed.
Generally, plug-ins should use NPN_MemAlloc to allocate memory in Navigator's memory space, since this function automatically frees cached data if necessary to fulfill the request. Use NPN_MemFlush in cases when calling NPN_MemAlloc is not possible, for example when calling system APIs that indirectly allocate memory. To request that Netscape free as much memory as possible, call NPN_MemFlush repeatedly until it returns 0.
Requests the creation of a new stream of data produced by the plug-in and consumed by Netscape.
NPN_NewStream asks Netscape to create a new stream for the instance specified by instance. The MIME type of the stream is specified by type, and the target window or frame is denoted by target. For more information on named targets, see Netscape's frames documentation.
The stream created by Netscape is returned in the variable stream. This stream object can then be used by the plug-in in subsequent calls to NPN_Write to write data into the stream for consumption by Netscape. When the plug-in has written all data into the stream, call NPN_DestroyStream to terminate the stream and deallocate the NPStream object.
For example, the following code creates a new stream of HTML text displayed by Netscape in a new window (error handling has been omitted for simplicity):
Posts data from a file or buffer to a URL. To post data and receive notification of the result, use NPN_PostURLNotify.
NPN_PostURL works similarly to NPN_GetURL, but in reverse. Like NPN_GetURL, an instance, url, and target are specified by the plug-in. But while 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 to the URL and displays the server's response in the target window or delivers it to the plug-in.
The data to post can be either contained in a file or a memory buffer. To post a 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 the file-type URL prefix "file://" is optional. Note that on Windows and the Macintosh, if a file is posted with any protocol other than FTP the file must be text with UNIX-style line breaks ('\n' separators only).
To post data in a memory buffer, set the flag file to FALSE, the buffer buf to the data to post, and len to the length of buffer. NPN_PostURL works identically with buffers and files.
Possible URL types include FTP, HTTP, mail, and news. For protocols where 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. NOTE: Passing headers (even a blank line) in a memory buffer is not supported by NPN_PostURL. If you need to specify headers (or leave a blank line for the defaults) in a memory buffer, you must use NPN_PostURLNotify.
For example, the following code posts two name-value pairs to a CGI script via HTTP. The response from the server will be sent to the plug-in in a new stream created with NPP_NewStream.
Posts data from a file or buffer to a URL, and receives notification of the result.
NPN_PostURLNotify functions identically NPN_PostURL in most ways except that (1) it supports specifying headers when posting a memory buffer, and (2) it calls NPN_URLNotify upon successful or unsuccessful completion of the request. The parameter notifyData is a plug-in-private value that can be used to uniquely identify the request; it will be returned to the plug-in as a parameter to the corresponding NPP_URLNotify call. Note that NPN_PostURLNotify is typically asynchronous: it returns immediately and only later handles the request and calls NPP_URLNotify.
NPN_RequestRead requests a range of bytes identified by rangeList to be read from the stream denoted by stream. The rangeList is a linked list of NPByteRange objects, each of which specifies an offset and length into the stream. The data will be written to the plug-in via subsequent calls to NPP_WriteReady and NPP_Write.
The plug-in can call NPN_RequestRead on streams that were not initially placed NP_SEEK mode as long as the stream is inherently seekable (see NPP_NewStream); NPN_RequestRead simply 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 Netscape 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.
NPN_Status displays the status message indicated by message for the instance denoted by instance. The message appears in the Navigator client user interface; in Navigator 2.0 or later the message is drawn at the bottom of the browser window on all platforms.
This function is useful for simulating the Navigator's behavior for links. When the user moves the mouse over a link in a browser window, the Navigator displays the URL of the link in the status message area. If your plug-in has a button or other object that will act as a link when clicked, you should make your user interface consistent with the rest of the Navigator by calling NPN_Status to display the URL of the link when user moves the mouse over the button.
NPN_Version returns the plug-in version number in plugin_major and plugin_minor, and Netscape Navigator version in netscape_major and netscape_minor. The plug-in version is determined by the constants defined in npapi.h when the plug-in is compiled; the Netscape verion is determine by the same constants when Netscape is compiled.
The plug-in glue code (in npmac.cpp for the Macintosh and npwin.cpp for Windows) checks the major version numbers and refuses to load the plug-in if the major version of Netscape is greater than the major version of the plug-in. Thus the major version number in npapi.h will only change if old plug-ins will be strictly and explicitly incompatible with a new version of Netscape Navigator. The minor version number will change whenever the plug-in API functionality changes with a new version of Navigator. For example, if new capabilities or API entry points are added in a new Navigator version, plug-ins should check the minor version of Netscape to ensure that the capabilities exist before using them.
Writes data to a stream for consumption by Netscape.
A plug-in can call NPN_Write after creating a stream with NPN_NewStream. The function delivers a buffer buf of len bytes of data from the stream identified by stream to the instance. The parameter offset is the logical position of buf from the beginning of the data in the stream.
The function returns the number of bytes written (consumed by Netscape), which may depend on the size of Netscape's memory buffers, the number of active streams, and other factors. A negative return value indicates that Netscape encountered an error while processing the data, so the plug-in should terminate the stream by calling NPN_DestroyStream. See the documentation for NPN_NewStream for an example showing the use of NPN_Write.