mozilla
Your Search Results

    nsIContentPolicy

    Interface for content policy mechanism. Implementations of this interface can be used to control loading of various types of out-of-line content, or processing of certain types of inline content.

    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 from shouldLoad() or shouldProcess() (for example, by launching a dialog to prompt the user for something.)")

    Please add a summary to this article.
      Last changed in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

    Inherits from: nsISupports

    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

    Constant Value Description
    TYPE_OTHER 1
    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 document at the top-level (that is in a browser).
    TYPE_SUBDOCUMENT 7 Indicates a document contained within another document (for example, IFRAMEs, FRAMES, and OBJECTs).
    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 Document.addBinding method.
    TYPE_PING 10 Indicates a ping triggered by a click on <A PING="..."> element.
    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.
    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: It is not meant to stop future requests for this type--only the current request.
    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: It is not meant to stop future requests for this server--only the current request.
    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.
    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()

    Should the resource at this location be loaded? ShouldLoad() will be called before loading the resource at aContentLocation to determine whether to start the load at all.

    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: http://mxr.mozilla.org/mozilla-central/source/content/base/src/nsContentPolicy.cpp#146.
    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 TYPE_* constants.
    aContentLocation
    The location of the content being checked; must not be null.
    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.
    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. The requesting principal.
    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.

    Document Tags and Contributors

    Contributors to this page: trevorh
    Last updated by: trevorh,