NPN_GetURL

« Gecko Plugin API Reference « Plug-in Side Plug-in API

Summary

Asks the browser to create a stream for the specified URL.

Syntax

#include <npapi.h>
NPError NPN_GetURL(NPP instance, 
                   const char* url,
                   const char* target);

Parameters

The function has the following parameters:

instance: Pointer to the current plug-in instance.

url: Pointer to the URL of the request. Can be of any type, such as HTTP, FTP, news, or mailto.

target

Name of the target window or frame, or one of the following special target names. Values:

_blank or _new: Load the link in a new blank unnamed window. Safest target, even though, when used with a mailto or news URL, this creates an extra blank the browser instance.
_self or _current: Load the link into the same window the plug-in instance occupies. Not recommended; if target refers to the window or frame containing the instance, the instance is destroyed and the plug-in may be unloaded. Use with NPN_GetURL() only if you want to terminate the plug-in.
_parent: Load the link into the immediate <frameset> parent of the plug-in instance's document. If the plug-in instance's document has no parent, the default is _self.
_top: Load the link into the plug-in instance window. The default is _self, if the plug-in instance's document is already at the top. Use for breaking out of a deep frame nesting.

If the target is null, the browser creates a new stream and delivers the data to the current instance regardless of the MIME type of the URL. In general, if a URL works in the location box of the browser, it works here, except for the _self target.

Returns

If successful, the function returns NPERR_NO_ERROR.
If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see Error codes.

Description

NPN_GetURL() is used to load a URL into the current window or another target or stream. Plug-ins can use this capability to provide hyperlinks to other documents or to retrieve data from anywhere on the network. This is especially useful for enabling an existing application to operate on the web.

For HTTP URLs, the browser resolves this method as the HTTP server method GET, which requests URL objects.

Use NPN_GetURLNotify() instead of NPN_GetURL() in these cases:

To request a stream and receive notification of the result.
If the buffer contains header information (even a blank line).

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). The following recommendations about target choice apply to other methods that handle URLs as well.

If the target parameter refers to the window or frame containing the current plug-in instance, the instance is destroyed and the plug-in may be unloaded. If target is null, the application creates a new stream and delivers the data to the plug-in instance, through calls to NPP_NewStream(), NPP_WriteReady() and NPP_Write(), and NPP_DestroyStream(). This means that if you want the plug-in to handle a new stream, no matter what the MIME type is, use null. If the application cannot locate the URL and retrieve the data, it does not create a stream for the instance.

When the plug-in instance is part of a regular browser window, and it uses a _blank target with a mailto or news URL, another blank window is opened along with the mail or news window.

When the plug-in uses a _self target, no other instance is created; the plug-in usually continues to operate successfully in its own window. The safest target is _blank, even though this creates an extra blank the browser instance.

The plug-in developer cannot influence the way that the browser handles NPN_GetURL(). It is typically asynchronous but this is not guaranteed. The plug-in could call NPN_GetURL() and receive data from the URL right away, but more often the data arrives later. The rest of the the browser interface keeps running until the data is available.