nsIContentPolicy

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.

Method overview

Constants

Content types

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.

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.

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, ...)

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.