NPAPI:HTTPRedirectHandling: Difference between revisions
| Line 29: | Line 29: | ||
* url: the new target url for the redirect | * url: the new target url for the redirect | ||
* status: the status code returned from the server (will be 3xx) | * status: the status code returned from the server (will be 3xx) | ||
* notifyData: the data passed into NPN_PostURLNotify | * notifyData: the data passed into 'NPN_PostURLNotify' or 'NPN_GetURLNotify' | ||
* callback: the address of a callback function for asynchronous responses | * callback: the address of a callback function for asynchronous responses | ||
| Line 36: | Line 36: | ||
NPVERS_HAS_HTTP_REDIRECT_HANDLER = 26 | NPVERS_HAS_HTTP_REDIRECT_HANDLER = 26 | ||
The slot for this handler in the plugin function structure can be NULL. If this function is not provided then redirect behavior is up to the browser. The recommended default behavior is to allow all same-origin redirects and disallow all cross-origin redirects. | The slot for this handler in the plugin function structure can be 'NULL'. If this function is not provided then redirect behavior is up to the browser. The recommended default behavior is to allow all same-origin redirects and disallow all cross-origin redirects. | ||
Plugins have the option of synchronously or asynchronously responding to the redirect notification. | Plugins have the option of synchronously or asynchronously responding to the redirect notification. | ||
Returning | Returning 'NPERR_NO_ERR' will synchronously allow the redirect, returning 'NPERR_INVALID_URL' will synchronously disallow the redirect. To respond asynchronously via the provided callback function plugins can return a newly defined error: | ||
#define NPERR_ASYNC_RESPONSE (NPERR_BASE + 14) | #define NPERR_ASYNC_RESPONSE (NPERR_BASE + 14) | ||
Network requests may time out if an asynchronous response is not received in a reasonable amount of time | Network requests may time out if an asynchronous response is not received in a reasonable amount of time. | ||
There may be further redirect notifications when a redirect is allowed. When a redirect is disallowed the browser will subsequently issue an | There may be further redirect notifications when a redirect is allowed. When a redirect is disallowed or an asynchronous redirect response is not received within a reasonable amount of time the browser will subsequently issue an 'NPP_URLNotify' call with reason 'NPRES_USER_BREAK' and the last allowed or original url. | ||
Plugins can query the browser for support for this specification using the following variable: | Plugins can query the browser for support for this specification using the following variable: | ||
Revision as of 21:49, 11 October 2010
Status
Under consideration.
Contributors
- Last modified: October 8, 2010
- Authors: Rudi Sherry (Adobe), Josh Aas (Mozilla), Johnny Stenback (Mozilla)
- Contributors: Darin Fisher (Google), Dimcho Balev (Adobe), Deneb Meketa (Adobe), Stuart Morgan (Google)
Overview
Plugins need the opportunity to participate in HTTP redirect handling for requests started with 'NPN_PostURLNotify' and 'NPN_GetURLNotify'.
Specification
The following function can be implemented by plugins to allow for HTTP redirect handling:
/* Callback function type used by NPP_URLRedirectNotify */
typedef NPError (*NPN_HTTPRedirectResponseFunc)(NPNetscapeFuncs*,
NPPluginFuncs*);
NPError NPP_URLRedirectNotify(NPP instance, const char* url,
int32 status, void* notifyData,
NPN_HTTPRedirectResponseFunc callback);
- instance: the plug-in instance that made the request
- url: the new target url for the redirect
- status: the status code returned from the server (will be 3xx)
- notifyData: the data passed into 'NPN_PostURLNotify' or 'NPN_GetURLNotify'
- callback: the address of a callback function for asynchronous responses
The browser will look for 'NPP_URLRedirectNotify' only if the plugin function structure's version field is set to the following value or higher:
NPVERS_HAS_HTTP_REDIRECT_HANDLER = 26
The slot for this handler in the plugin function structure can be 'NULL'. If this function is not provided then redirect behavior is up to the browser. The recommended default behavior is to allow all same-origin redirects and disallow all cross-origin redirects.
Plugins have the option of synchronously or asynchronously responding to the redirect notification.
Returning 'NPERR_NO_ERR' will synchronously allow the redirect, returning 'NPERR_INVALID_URL' will synchronously disallow the redirect. To respond asynchronously via the provided callback function plugins can return a newly defined error:
#define NPERR_ASYNC_RESPONSE (NPERR_BASE + 14)
Network requests may time out if an asynchronous response is not received in a reasonable amount of time.
There may be further redirect notifications when a redirect is allowed. When a redirect is disallowed or an asynchronous redirect response is not received within a reasonable amount of time the browser will subsequently issue an 'NPP_URLNotify' call with reason 'NPRES_USER_BREAK' and the last allowed or original url.
Plugins can query the browser for support for this specification using the following variable:
NPNVsupportsRedirectNotification = 22
If the browser returns "true" for this variable then plugins can depend on the browser calling the HTTP redirect handler when appropriate, if it is provided by the plugin.