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.
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.
Posts data from a file or buffer to a URL.
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.
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.
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 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.