nsIContentPolicy

Interface used to implement a content policy mechanism. Implementations of this interface can be used to control the loading of various types of out-of-line content, or the processing of certain types of inline content.
63
Introduced
Gecko 1.0
Inherits from: nsIContentPolicyBase Last changed in Gecko 42 (Firefox 42 / Thunderbird 42 / SeaMonkey 2.39)

You can observe content that is being loaded into your browser by implementing nsIContentPolicy. This interface can be very useful if you are developing a content-aware plugin (blocking ads or altering the look of content, for example), or if you want to stop or allow user-browsed URLs.

Warning: Do not block the caller in your implementations of shouldLoad() or shouldProcess() (for example, by launching a dialog to prompt the user for something).")

Note: In reality, much of this interface is defined in the nsIContentPolicyBase interface, but for now is documented here until someone has time to split things up.

Method overview

short shouldLoad(in unsigned long aContentType, in nsIURI aContentLocation, in nsIURI aRequestOrigin, in nsISupports aContext, in ACString aMimeTypeGuess, in nsISupports aExtra, in nsIPrincipal aRequestPrincipal);
short shouldProcess(in unsigned long aContentType, in nsIURI aContentLocation, in nsIURI aRequestOrigin, in nsISupports aContext, in ACString aMimeType, in nsISupports aExtra, in nsIPrincipal aRequestPrincipal);

Constants

Content types

Constant Value Description
TYPE_OTHER 1 Indicates content whose type is unknown, or is not interesting outside a limited use case. In general, you should try not to use this type unless none of the others is a fit.
TYPE_SCRIPT 2 Indicates an executable script (such as JavaScript).
TYPE_IMAGE 3 Indicates an image (for example, <img> elements).
TYPE_STYLESHEET 4 Indicates a stylesheet (for example, <style> elements).
TYPE_OBJECT 5 Indicates a generic object (plugin-handled content typically falls under this category).
TYPE_DOCUMENT 6 Indicates a DOM document at the top-level (that is, directly within a browser tab).
TYPE_SUBDOCUMENT 7

Indicates a document contained within another document (for example, <iframe> and <frame> elements).

Note: Gecko uses TYPE_INTERNAL_FRAME and TYPE_INTERNAL_IFRAME in order to discern the difference internally. These types are mapped to TYPE_SUBDOCUMENT before being passed into the implementation of the content policy and should not be used outside Gecko code.

TYPE_REFRESH 8

Indicates a timed refresh.

shouldLoad() will never get this, because it does not represent content to be loaded (the actual load triggered by the refresh will go through shouldLoad() as expected).

shouldProcess() will get this for, for example <meta> Refresh elements and HTTP Refresh headers.
TYPE_XBL 9 Indicates an XBL binding request, triggered either by -moz-binding CSS property or the Document.addBinding() method.
TYPE_PING 10 Indicates a ping triggered by a click on an <a> element using the ping attribute.
TYPE_XMLHTTPREQUEST 11 Indicates an XMLHttpRequest. Also used for Document.load()
TYPE_OBJECT_SUBREQUEST 12 Indicates a request by a plugin.
TYPE_DTD 13 Indicates a DTD loaded by an XML document.
TYPE_FONT 14 Indicates a font loaded via @font-face rule.
TYPE_MEDIA 15 Indicates a video or audio load.
TYPE_WEBSOCKET 16 Indicates a WebSocket load.
TYPE_CSP_REPORT 17 Indicates a Content Security Policy report.
TYPE_XSLT 18 Indicates a style sheet transformation.
TYPE_BEACON 19 Indicates a beacon post.
TYPE_FETCH 20 Indicates a load initiated by the GlobalFetch.fetch() method, which is available as a global in both Window and Worker contexts.
TYPE_IMAGESET 21 Indicates a request to load an <img> (with the srcset attribute or <picture>.
TYPE_WEB_MANIFEST 22 Indicates a request to load a Web manifest.
TYPE_INTERNAL_SCRIPT 23

An internal constant used to represent scripts loaded using <script> elements.

Important: This type is mapped to TYPE_SCRIPT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_WORKER 24

An internal constant used to represent scripts loaded through a dedicated worker.

Important: This type is mapped to TYPE_SCRIPT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_SHARED_WORKER 25

An internal constant used to represent scripts loaded through a shared worker.

Important: This type is mapped to TYPE_SCRIPT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_EMBED 26

An internal constant used to represent content loaded from <embed> elements.

Important: This type is mapped to TYPE_OBJECT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_OBJECT 27

An internal constant used to represent content loaded from <object> elements.

Important: This type is mapped to TYPE_OBJECT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_FRAME 28

An internal constant used to represent content loaded from <frame> elements.

Important: This type is mapped to TYPE_SUBDOCUMENT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_IFRAME 29

An internal constant used to represent content loaded from <iframe> elements.

Important: This type is mapped to TYPE_SUBDOCUMENT before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_AUDIO 30

An internal constant used to represent content loaded from <audio> elements.

Important: This type is mapped to TYPE_MEDIA before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_VIDEO 31

An internal constant used to represent content loaded from <video> elements.

Important: This type is mapped to TYPE_MEDIA before being passed to content policy implementations, and should not be used outside Gecko core code.

TYPE_INTERNAL_TRACK 32

An internal constant used to represent content loaded from <track> elements.

Important: This type is mapped to TYPE_MEDIA before being passed to content policy implementations, and should not be used outside Gecko core code.

REJECT_REQUEST -1 Returned from shouldLoad() or shouldProcess() if the load or process request is rejected based on details of the request.
REJECT_TYPE -2

Returned from shouldLoad() or shouldProcess() if the load/process is rejected based solely on its type (of the above flags).

Note: This rejection only applies to the current request on this server, not to future requests of the same type.

REJECT_SERVER -3

Returned from shouldLoad() or shouldProcess() if the load/process is rejected based on the server it is hosted on or requested from (aContentLocation or aRequestOrigin), e.g., if you block an IMAGE because it is served from goatse.cx (even if you don't necessarily block other types from that server/domain).

Note: This rejection only applies to the current request on this server, not to future requests of the same type.

REJECT_OTHER -4

Returned from shouldLoad() or shouldProcess() if the load/process is rejected based on some other criteria. Mozilla callers will handle this like REJECT_REQUEST; third-party implementors may, for example, use this to direct their own callers to consult the extra parameter for additional details.

Note: This rejection only applies to the current request on this server, not to future requests of the same type.

ACCEPT 1 Returned from shouldLoad() or shouldProcess() if the load or process request is not rejected.
OTHER 0 Obsolete since Gecko 1.8
SCRIPT 1 Obsolete since Gecko 1.8
IMAGE 2 Obsolete since Gecko 1.8
STYLESHEET 3 Obsolete since Gecko 1.8
OBJECT 4 Obsolete since Gecko 1.8
SUBDOCUMENT 5 Obsolete since Gecko 1.8
CONTROL_TAG 6 Obsolete since Gecko 1.8
RAW_URL 7 Obsolete since Gecko 1.8
DOCUMENT 8 Obsolete since Gecko 1.8

Methods

shouldLoad()

Called to let your content policy implementation decide whether or not the resource at a given location should be loaded. This method is called before loading the resource specified by aContentLocation to determine whether or not to start loading the requested resource.

shouldLoad() can be called while the DOM and layout of the document involved is in an inconsistent state. This means that implementers of this method must not do any of the following:

  1. Modify the DOM in any way (e.g., setting attributes is a no-no).
  2. Query any DOM properties that depend on layout (e.g., offset* properties).
  3. Query any DOM properties that depend on style (e.g., computed style).
  4. Query any DOM properties that depend on the current state of the DOM outside the "context" node (e.g., lengths of node lists).
  5. [JavaScript implementations only] Access properties of any sort on any object without using XPCNativeWrapper (either explicitly or implicitly). Due to various DOM0 things, this leads to item 4.

If you do any of these things in your shouldLoad() implementation, expect unpredictable behavior, possibly including crashes, content not showing up, content showing up doubled, etc. If you need to do any of the things above, do them off timeout or event.

Note: When multiple content policies are used (for example through several extensions), if one of them rejects a request, the rest of the policies are not called. Reference: //github.com/RealityRipple/UXP/blob/master/dom/base/nsContentPolicy.cpp#L129.

Note: The order of content policies in the above case depends on the precedence of installation.

short shouldLoad(
  in unsigned long aContentType,
  in nsIURI aContentLocation,
  in nsIURI aRequestOrigin,
  in nsISupports aContext,
  in ACString aMimeTypeGuess,
  in nsISupports aExtra,
  in nsIPrincipal aRequestPrincipal
);
Parameters
aContentType
The type of content being tested. This will be one one of the Content types listed above.
aContentLocation
The URI of the content being checked; must not be null.
aRequestOrigin {optional_inline}}
The location of the resource that initiated this load request; can be null if inapplicable.
aContext {optional_inline}}
The nsIDOMNode or nsIDOMWindow that initiated the request, or something that can QueryInterface() to one of those; can be null if inapplicable.

Note: aContext is the new tab/window when a user uses the context menu to open a link in a new tab/window or cmd/ctrl + clicks the link (i.e., aContext is not the tab which the link was on in these cases).

aMimeTypeGuess
OPTIONAL. a guess for the requested content's MIME type, based on information available to the request initiator (e.g., an OBJECT's type attribute); does not reliably reflect the actual MIME type of the requested content.
aExtra
An OPTIONAL argument, pass-through for non-Gecko callers to pass extra data to callees.
aRequestPrincipal
OPTIONAL. defines the principal that caused the load. This is optional only for non-gecko code: all gecko code should set this argument. For navigation events, this is the principal of the page that caused this load.
Return value

ACCEPT or REJECT_*

shouldProcess()

Should the resource be processed? ShouldProcess() will be called once all the information passed to it has been determined about the resource, typically after part of the resource has been loaded. "Processing" means handling by the application. For instance, shouldProcess could be used to allow a response from a server to be handled or ignored depending on the MIME type of the response.

Note: shouldProcess() can be called while the DOM and layout of the document involved is in an inconsistent state. See the note on shouldLoad() to see what this means for implementors of this method.

short shouldProcess(
  in unsigned long aContentType,
  in nsIURI aContentLocation,
  in nsIURI aRequestOrigin,
  in nsISupports aContext,
  in ACString aMimeType,
  in nsISupports aExtra,
  in nsIPrincipal aRequestPrincipal
);
Parameters
aContentType
The type of content being tested. This will be one of the TYPE_* constants.
aContentLocation
OPTIONAL. The location of the resource being requested: MAY be, e.g., a post-redirection URI for the resource.
aRequestOrigin
OPTIONAL. The location of the resource that initiated this load request; can be null if inapplicable.
aContext
OPTIONAL. The nsIDOMNode or nsIDOMWindow that initiated the request, or something that can Query Interface to one of those; can be null if inapplicable.
aMimeType
The MIME type of the requested resource (for example, image/png), as reported by the networking library, if available (may be empty if inappropriate for the type, e.g., TYPE_REFRESH).
aExtra
An OPTIONAL argument, pass-through for non-Gecko callers to pass extra data to callees.
aRequestPrincipal
OPTIONAL. The requesting principal.
Return value

ACCEPT or REJECT_*

Example

You can implement this interface easily by including the nsIContentPolicy.h header file and implementing public nsIContentPolicy into your class, like this:

// Put this into your header file

#include "_path_to_sdk/include/content/nsIContentPolicy.h"

class MyClass: public nsISupports, public nsIContentPolicy {
  ...
  NS_DECL_NSICONTENTPOLICY
  ...
}

// And this into your implementation file
NS_IMPL_ISUPPORTSn(MyClass, nsISupports, nsIContentPolicy, ...)

Note: Before you can recieve notifications, you must register your plugin with nsICategoryManager. See example below.

char* previous = nsnull;

nsCOMPtr<nsICategoryManager> catman;

servman->GetServiceByContractID(NS_CATEGORYMANAGER_CONTRACTID,
NS_GET_IID(nsICategoryManager),
getter_AddRefs(catman));

rv = catman->AddCategoryEntry("content-policy",
COMPONENT_CLASSNAME,
COMPONENT_CONTRACTID,
PR_TRUE,
PR_TRUE,
&previous);

JavaScript developers can also implement an XPCOM component that extends nsIContentPolicy.