This chapter describes retrieving URLs and displaying them on specified target pages, posting data to an HTTP server, uploading files to an FTP server, and sending mail.
Table 6.1 summarizes URLs supported by the Netscape browser. In addition, Netscape may support URLs not listed on this table.
This chapter describes retrieving URLs and displaying them on specified target pages, posting data to an HTTP server, uploading files to an FTP server, and sending mail.Uniform resource locator (URL) protocols provide a means for locating and accessing resources that are available on the Internet and on intranets. Plug-ins can request and receive the data associated with URLs of any type that the browser can handle, including
Table 6.1 Supported URL schemes
|Locates browser information or "fun" pages. Netscape proprietary.|
|(Host-specific filenames) Locates files on a specific host computer rather than an Internet resource.|
|(File Transfer Protocol) Locates files and directories on Internet hosts for file download.|
|(Gopher protocol) Locates specified items on a Gopher server.|
|(Hypertext Transfer Protocol) Locates resources on the Internet.|
|(Electronic mail address) Locates the Internet mailing address of an individual or service.|
|Displays a NetHelp topic in a NetHelp window. Communicator-specific.|
|(USENET news) Locates USENET news groups or individual USENET articles.|
(USENET news using |
|(Prospero Directory Service) Locates a resource on a Prospero directory server.|
|(Reference to interactive sessions) Locates an interactive service.|
|(Wide Area Information Servers) Locates WAIS databases and their documents.|
For more information, see RFC 1738, "Uniform Resource Locators (URL).
For a reference entry that describes each function discussed in this chapter, see "URL Methods" in the API reference.
functions. This section describes the methods and procedure used for getting the URL and displaying the page.
The plug-in uses the
NPN_GetURL function to ask Communicator to display data retrieved from a URL in a specified target window or frame, or deliver it to the plug-in instance in a new stream. This is the way that plug-ins provide hyperlinks to other documents or retrieve data from the network.
If Communicator cannot locate the URL and retrieve the data, it does not create a stream for the instance; in this case, the plug-in receives notification of the result. To request a stream and receive notification of the result in all cases, use
For HTTP URLs, Communicator resolves
NPN_GetURL as the HTTP server method
GET, which requests URL objects.
NPN_GetURL is typically asynchronous: it returns immediately and only later handles the request, such as displaying the URL or creating the stream for the instance and writing the data. For this reason as well, calling
NPN_GetURLNotify may be more useful than
NPN_GetURL; the plug-in is notified upon either successful or unsuccessful completion of the request.
instance, const char *url, const char *target);
instance parameter represents the current plug-in instance. The
url parameter is the URL of the request, which can be of any type, including
target parameter represents the destination where the URL will be displayed, a window or frame. If
target refers to the window or frame containing the plug-in instance, it is destroyed and the plug-in may be unloaded. If the
target parameter is set to
null, the application creates a new stream and delivers the data to the plug-in instance, through calls to
In general, if a URL works in the location box of the Navigator, it works as a target for
NPN_GetURL, except for the
Make sure that the target matches the URL type sent to it. For example, a
null target does not make sense for some URL types (such as
mailto). For some recommendations to help you with
target parameter choice, see the reference entry for
For complete information on named targets for this function (as well as for normal HTML links), see the Netscape document, "Targeting Windows."
NPN_GetURLNotify method acts like
NPN_GetURL. Both request the creation of a new stream with the contents of the specified URL, and, in addition,
NPN_GetURLNotify notifies the plug-in of the successful or unsuccessful completion of the request. Communicator notifies the plug-in by calling the plug-in's
NPP_URLNotify function and passing it the
notifyData value, which may be used to track multiple requests.
NPN_GetURLNotify handles the URL request asynchronously. It returns immediately and only later handles the request and calls
NPP_URLNotify. Without this notification, the plug-in cannot tell whether a request with a
null target failed or a request with a non-
null target was completed.
instance, const char* url,
const char* target, void* notifyData); The
target parameters have the same definitions as those of
notifyData parameter contains private plug-in data that can be used to associate the request with the subsequent
NPP_URLNotify call (which returns this value) and/or to pass a pointer to some request-related payload.
If a request is not completed successfully (for example, because the URL is invalid or a HTTP server is down), Communicator should call
NPP_URLNotify as soon as possible. If a request completes successfully, and the target is non-
null, Communicator calls
NPP_URLNotify after it has finished loading the URL. If the target is
null, it calls
NPP_URLNotify after calling
NPP_DestroyStream to close the stream.
NPN_PostURLNotify functions call the
NPP_URLNotify method to notify the plug-in of the result of a request. Both functions pass the
notifyData value to
NPP_URLNotify, which tells the plug-in that the URL request was completed and the reason for completion.
void NPP_URLNotify( instance, const char* url,
NPReason reason, void* notifyData); The
url parameters have the same definitions as those of
notifyData parameter contains the private plug-in data passed to the corresponding call to
[Top] [Getting URLs]
NPN_GetURLNotifyfunctions. The URL can be displayed in the same window or frame, a new window, or a different window or frame, depending on the value of the
targetparameter. Specify the display target with one of these special target names:
_self or _current: Load the URL into the same window the plug-in instance occupies. If this target refers to the window or frame containing the instance, the instance is destroyed and the plug-in may be unloaded.
NPN_GetURLto go to the page.
err = NPN_GetURL(instance, "http://home.netscape.com/", "_blank");[Top] [Getting URLs]
NPN_PostURLto post data from a file or buffer to a URL. This function is the counterpart of
POST, which transmits data to the server. You can use
NPN_PostURLto post data to a URL from a memory buffer or file. The result from the server can also be sent to a particular Communicator 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. Communicator resolves this method as the
POST, which transmits data to the server. The data to post can be contained either in a local temporary file or a new memory buffer. To post a file, set the flag
true, the buffer
bufto the path name string for a file, and
lento the length of the path string. The file-type URL prefix
NPN_PostURLis typically asynchronous: it returns immediately and only later handles the request and calls
NPP_Notify(which, in turn, calls
NPError NPN_PostURL(instance, const char *url,
targetparameters have the same definitions as those of
buf parameter identifies a local temporary file or data buffer that contains the data to post.
Windows and Mac OS
If a file is posted with any protocol other than FTP, the file must be text with
Unix-style line breaks (
'\n' separators only). §
NPN_PostURL works identically with buffers and files. To post data from a memory buffer, set the flag
false, the buffer
buf to the data to post, and
len to the length of the buffer.
Possible URL types include
http (similar to an HTML form submission),
mailto (sending mail),
news (posting a news article), and
ftp (uploading a file). 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. For a list of URL schemes supported by Netscape, see Supported URL Schemes.
NOTE: You cannot useThe
NPN_PostURLto specify headers (even a blank line) in a memory buffer. To do this, use
NPN_PostURLNotifyfor this purpose. §
NPN_PostURLNotifyfunction has all the same capabilities and works like
NPN_PostURLin most ways except that (1) it supports specifying headers when posting a memory buffer, and (2) it calls
NPP_URLNotifyupon successful or unsuccessful completion of the request.
NPN_PostURLNotifyis typically asynchronous: it returns immediately and only later handles the request and calls
instance, const char *url,
notifyDataparameter contains plug-in-private data passed by
NPP_URLNotifyand may be used for tracking multiple posts.
[Top] [Posting URLs]
char* myData = "Content Type:\tapplication/
uint32 myLength = strlen(myData) + 1;
err = NPN_PostURL(instance, "http://hoohoo.ncsa.uiuc.edu/[Top] [Posting URLs]
cgi-bin/post-query","_blank", myLength, myData, FALSE);
NPN_PostURLNotifyto upload files to a remote server using FTP. This example uploads a file from the root of the local file system to an FTP server and displays the response in a frame named
char* myData = "file:///c\/myDirectory/myFileName";
uint32 myLength = strlen(myData) + 1;
err = NPN_PostURL(instance, "ftp://email@example.com/pub/",[Top] [Posting URLs]
"response", myLength, myData, TRUE);
NPN_PostURLNotify. The following code sends a mail message with the default headers from the client machine.
char* myData = "\nHi Fred, this is a message from my plug-in!";
uint32 myLength = strlen(myData) + 1;
err = NPN_PostURLNotify(instance, "mailto:firstname.lastname@example.org",The example starts by defining the mail message,
NULL, myLength, myData, FALSE);
myData, and its length,
myLength. It sends
mailto:email@example.com. The target window for displaying the message is
nullin the example. Normally, using a
nulltarget window causes the response to be delivered from the server to the plug-in instance in a new stream, but no response is expected for a
mailtoURL. You cannot use either of these functions to set the body or attachments of an email message. [Top] [Posting URLs]
Last Updated: 01/15/97 16:36:54