Asks the browser to create a stream for the specified URL.
#include <npapi.h> NPError NPN_GetURL(NPP instance, const char* url, const char* target);
The function has the following parameters:
- Pointer to the current plug-in instance.
- Pointer to the URL of the request. Can be of any type, such as HTTP, FTP, news, or mailto.
Name of the target window or frame, or one of the following special target names. Values:
_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.
_current: Load the link into the same window the plug-in instance occupies. Not recommended; if
targetrefers 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
_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.
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
- If successful, the function returns
- If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see Error codes.
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.
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_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.