NPAPI:HTTPRedirectHandling: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
 
(28 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Status =
= Status =


Under consideration.
Accepted, ready for implementation.


= Contributors =
= Contributors =


* Last modified: October 8, 2010
* Last modified: November 5, 2010
* Authors: Rudi Sherry (Adobe), Josh Aas (Mozilla), Johnny Stenback (Mozilla)
* Authors: Josh Aas (Mozilla), Johnny Stenback (Mozilla)
* Contributors: Darin Fisher (Google), Dimcho Balev (Adobe), Deneb Meketa (Adobe), Stuart Morgan (Google)
* Contributors: Rudi Sherry (Adobe), Darin Fisher (Google), Dimcho Balev (Adobe), Deneb Meketa (Adobe), Stuart Morgan (Google), Jimson Xu (Adobe), Julian Reschke


= Overview =
= Overview =


Plugins need the opportunity to participate in HTTP redirect handling for requests
Plugins need the opportunity to participate in HTTP redirect handling for requests
started with 'NPN_PostURLNotify' and 'NPN_GetURLNotify'.
started with 'NPN_PostURLNotify' and 'NPN_GetURLNotify' with null window targets.


= Specification =
= Specification =


The following function can be implemented by plugins to allow for HTTP redirect handling:
== Notification ==


  /* Callback function type used by NPP_URLRedirectNotify */
The following function can be implemented by plugins to allow for URL redirect handling:
  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
  void NPP_URLRedirectNotify(NPP instance, const char* url,
* url: the new target url for the redirect
                            int32_t status, void* notifyData);
* 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:
* instance: The plug-in instance that made the request.
* url: The resolved strictly-ASCII URI for the redirect.
* status: The HTTP status code returned from the server (will be 3xx).
* notifyData: The plugin's private request data.
 
== Response ==
 
Plugins must respond to URL redirect requests by calling the following function in the browser's function table:
 
  void NPN_URLRedirectResponse(NPP instance, void* notifyData, NPBool allow);
 
* instance: The plug-in instance that made the request.
* notifyData: The plugin's private request data.
* allow: The plugin's response to the last URL redirect request.
 
This function must be available if the browser has called 'NPP_URLRedirectNotify' on the plugin.


  NPVERS_HAS_HTTP_REDIRECT_HANDLER = 26
In 'NPN_URLRedirectResponse', the applicable query getting the redirect is identified by the combination of 'instance' and 'notifyData'.  If there are extant calls to NPN_GetURLNotify() or NPN_PostURLNotify() with particular values for 'instance' and 'notifyData' that have not finished, any subsequent calls to those with the same values of 'instance' and 'notifyData' will result in undefined behavior.


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 can respond from within 'NPP_URLRedirectNotify' but the API is asynchronous so this is not necessary. It is recommended that plugins always respond to redirect notifications as soon as possible because browsers will have to track outstanding requests. If a response is not received before the relevant plugin instance is destroyed then the outstanding request will be canceled upon destruction.


Plugins have the option of synchronously or asynchronously responding to the redirect notification.
There may be further redirect notifications when a redirect is allowed. When a redirect is disallowed the browser will subsequently issue an 'NPP_URLNotify' call with reason 'NPRES_USER_BREAK' and the last allowed or original url.


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:
== Threading ==


  #define NPERR_ASYNC_RESPONSE (NPERR_BASE + 14)
With respect to threading, this specification conforms to standard NPAPI thread rules. Unless otherwise explicitly noted, all NPAPI functions must be called on the main thread.


Network requests may time out if an asynchronous response is not received in a reasonable amount of time. If this happens, the browser will subsequently issue an "NPP_URLNotify" call with reason "NPRES_USER_BREAK" and the last redirected url (the same one passed to the NPP_URLNotifyRedirect the last time).
== Querying for Support ==


There may be further redirect notifications when a redirect is allowed. When a redirect is disallowed the browser will subsequently issue an "NPP_URLNotify" call with reason "NPRES_USER_BREAK" and the last redirected url (the same one passed to the NPP_URLNotifyRedirect the last time).
The browser will look for 'NPP_URLRedirectNotify' only if the plugin function structure's version field is set to the following value or higher:


Plugins can query the browser for support for this specification using the following variable:
  NPVERS_HAS_URL_REDIRECT_HANDLER = 26


  NPNVsupportsRedirectNotification = 22
The slot for this handler in the plugin function structure can be 'NULL'. If this handler is not provided then redirect behavior is up to the browser.


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.
Plugins can query the browser for support for this specification by examining the browser's function table. If the version number is equal to or higher than 'NPVERS_HAS_URL_REDIRECT_HANDLER' and the slot for 'NPN_URLRedirectResponse' is non-NULL then the browser will call 'NPP_URLRedirectNotify' when appropriate.

Latest revision as of 02:03, 19 November 2010

Status

Accepted, ready for implementation.

Contributors

  • Last modified: November 5, 2010
  • Authors: Josh Aas (Mozilla), Johnny Stenback (Mozilla)
  • Contributors: Rudi Sherry (Adobe), Darin Fisher (Google), Dimcho Balev (Adobe), Deneb Meketa (Adobe), Stuart Morgan (Google), Jimson Xu (Adobe), Julian Reschke

Overview

Plugins need the opportunity to participate in HTTP redirect handling for requests started with 'NPN_PostURLNotify' and 'NPN_GetURLNotify' with null window targets.

Specification

Notification

The following function can be implemented by plugins to allow for URL redirect handling: 

 void NPP_URLRedirectNotify(NPP instance, const char* url,
                            int32_t status, void* notifyData);
  • instance: The plug-in instance that made the request.
  • url: The resolved strictly-ASCII URI for the redirect.
  • status: The HTTP status code returned from the server (will be 3xx).
  • notifyData: The plugin's private request data.

Response

Plugins must respond to URL redirect requests by calling the following function in the browser's function table: 

 void NPN_URLRedirectResponse(NPP instance, void* notifyData, NPBool allow);
  • instance: The plug-in instance that made the request.
  • notifyData: The plugin's private request data.
  • allow: The plugin's response to the last URL redirect request.

This function must be available if the browser has called 'NPP_URLRedirectNotify' on the plugin.

In 'NPN_URLRedirectResponse', the applicable query getting the redirect is identified by the combination of 'instance' and 'notifyData'. If there are extant calls to NPN_GetURLNotify() or NPN_PostURLNotify() with particular values for 'instance' and 'notifyData' that have not finished, any subsequent calls to those with the same values of 'instance' and 'notifyData' will result in undefined behavior.

Plugins can respond from within 'NPP_URLRedirectNotify' but the API is asynchronous so this is not necessary. It is recommended that plugins always respond to redirect notifications as soon as possible because browsers will have to track outstanding requests. If a response is not received before the relevant plugin instance is destroyed then the outstanding request will be canceled upon destruction.

There may be further redirect notifications when a redirect is allowed. When a redirect is disallowed the browser will subsequently issue an 'NPP_URLNotify' call with reason 'NPRES_USER_BREAK' and the last allowed or original url.

Threading

With respect to threading, this specification conforms to standard NPAPI thread rules. Unless otherwise explicitly noted, all NPAPI functions must be called on the main thread.

Querying for Support

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_URL_REDIRECT_HANDLER = 26

The slot for this handler in the plugin function structure can be 'NULL'. If this handler is not provided then redirect behavior is up to the browser.

Plugins can query the browser for support for this specification by examining the browser's function table. If the version number is equal to or higher than 'NPVERS_HAS_URL_REDIRECT_HANDLER' and the slot for 'NPN_URLRedirectResponse' is non-NULL then the browser will call 'NPP_URLRedirectNotify' when appropriate.

Retrieved from "https://wiki.mozilla.org/index.php?title=NPAPI:HTTPRedirectHandling&oldid=268882"