michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* vim: set ft=cpp tw=78 sw=2 et ts=8 : */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIURI; michael@0: interface nsIDOMNode; michael@0: interface nsIPrincipal; michael@0: michael@0: /** michael@0: * The type of nsIContentPolicy::TYPE_* michael@0: */ michael@0: typedef unsigned long nsContentPolicyType; michael@0: michael@0: /** michael@0: * Interface for content policy mechanism. Implementations of this michael@0: * interface can be used to control loading of various types of out-of-line michael@0: * content, or processing of certain types of in-line content. michael@0: * michael@0: * WARNING: do not block the caller from shouldLoad or shouldProcess (e.g., michael@0: * by launching a dialog to prompt the user for something). michael@0: */ michael@0: michael@0: [scriptable,uuid(b6a71698-c117-441d-86b9-480cf06e3952)] michael@0: interface nsIContentPolicy : nsISupports michael@0: { michael@0: /** michael@0: * Gecko/Firefox developers: Do not use TYPE_OTHER under any circumstances. michael@0: * michael@0: * Extension developers: Whenever it is reasonable, use one of the existing michael@0: * content types. If none of the existing content types are right for michael@0: * something you are doing, file a bug in the Core/DOM component that michael@0: * includes a patch that adds your new content type to the end of the list of michael@0: * TYPE_* constants here. But, don't start using your new content type until michael@0: * your patch has been accepted, because it will be uncertain what exact michael@0: * value and name your new content type will have; in that interim period, michael@0: * use TYPE_OTHER. In your patch, document your new content type in the style michael@0: * of the existing ones. In the bug you file, provide a more detailed michael@0: * description of the new type of content you want Gecko to support, so that michael@0: * the existing implementations of nsIContentPolicy can be properly modified michael@0: * to deal with that new type of content. michael@0: * michael@0: * Implementations of nsIContentPolicy should treat this the same way they michael@0: * treat unknown types, because existing users of TYPE_OTHER may be converted michael@0: * to use new content types. michael@0: */ michael@0: const nsContentPolicyType TYPE_OTHER = 1; michael@0: michael@0: /** michael@0: * Indicates an executable script (such as JavaScript). michael@0: */ michael@0: const nsContentPolicyType TYPE_SCRIPT = 2; michael@0: michael@0: /** michael@0: * Indicates an image (e.g., IMG elements). michael@0: */ michael@0: const nsContentPolicyType TYPE_IMAGE = 3; michael@0: michael@0: /** michael@0: * Indicates a stylesheet (e.g., STYLE elements). michael@0: */ michael@0: const nsContentPolicyType TYPE_STYLESHEET = 4; michael@0: michael@0: /** michael@0: * Indicates a generic object (plugin-handled content typically falls under michael@0: * this category). michael@0: */ michael@0: const nsContentPolicyType TYPE_OBJECT = 5; michael@0: michael@0: /** michael@0: * Indicates a document at the top-level (i.e., in a browser). michael@0: */ michael@0: const nsContentPolicyType TYPE_DOCUMENT = 6; michael@0: michael@0: /** michael@0: * Indicates a document contained within another document (e.g., IFRAMEs, michael@0: * FRAMES, and OBJECTs). michael@0: */ michael@0: const nsContentPolicyType TYPE_SUBDOCUMENT = 7; michael@0: michael@0: /** michael@0: * Indicates a timed refresh. michael@0: * michael@0: * shouldLoad will never get this, because it does not represent content michael@0: * to be loaded (the actual load triggered by the refresh will go through michael@0: * shouldLoad as expected). michael@0: * michael@0: * shouldProcess will get this for, e.g., META Refresh elements and HTTP michael@0: * Refresh headers. michael@0: */ michael@0: const nsContentPolicyType TYPE_REFRESH = 8; michael@0: michael@0: /** michael@0: * Indicates an XBL binding request, triggered either by -moz-binding CSS michael@0: * property. michael@0: */ michael@0: const nsContentPolicyType TYPE_XBL = 9; michael@0: michael@0: /** michael@0: * Indicates a ping triggered by a click on element. michael@0: */ michael@0: const nsContentPolicyType TYPE_PING = 10; michael@0: michael@0: /** michael@0: * Indicates an XMLHttpRequest. Also used for document.load and for EventSource. michael@0: */ michael@0: const nsContentPolicyType TYPE_XMLHTTPREQUEST = 11; michael@0: const nsContentPolicyType TYPE_DATAREQUEST = 11; // alias michael@0: michael@0: /** michael@0: * Indicates a request by a plugin. michael@0: */ michael@0: const nsContentPolicyType TYPE_OBJECT_SUBREQUEST = 12; michael@0: michael@0: /** michael@0: * Indicates a DTD loaded by an XML document. michael@0: */ michael@0: const nsContentPolicyType TYPE_DTD = 13; michael@0: michael@0: /** michael@0: * Indicates a font loaded via @font-face rule. michael@0: */ michael@0: const nsContentPolicyType TYPE_FONT = 14; michael@0: michael@0: /** michael@0: * Indicates a video or audio load. michael@0: */ michael@0: const nsContentPolicyType TYPE_MEDIA = 15; michael@0: michael@0: /** michael@0: * Indicates a WebSocket load. michael@0: */ michael@0: const nsContentPolicyType TYPE_WEBSOCKET = 16; michael@0: michael@0: /** michael@0: * Indicates a Content Security Policy report. michael@0: */ michael@0: const nsContentPolicyType TYPE_CSP_REPORT = 17; michael@0: michael@0: /** michael@0: * Indicates a style sheet transformation. michael@0: */ michael@0: const nsContentPolicyType TYPE_XSLT = 18; michael@0: michael@0: /** michael@0: * Indicates a beacon post. michael@0: */ michael@0: const nsContentPolicyType TYPE_BEACON = 19; michael@0: michael@0: /* When adding new content types, please update nsContentBlocker, michael@0: * NS_CP_ContentTypeName, contentSecurityPolicy.js, all nsIContentPolicy michael@0: * implementations, and other things that are not listed here that are michael@0: * related to nsIContentPolicy. */ michael@0: michael@0: ////////////////////////////////////////////////////////////////////// michael@0: michael@0: /** michael@0: * Returned from shouldLoad or shouldProcess if the load or process request michael@0: * is rejected based on details of the request. michael@0: */ michael@0: const short REJECT_REQUEST = -1; michael@0: michael@0: /** michael@0: * Returned from shouldLoad or shouldProcess if the load/process is rejected michael@0: * based solely on its type (of the above flags). michael@0: * michael@0: * NOTE that it is not meant to stop future requests for this type--only the michael@0: * current request. michael@0: */ michael@0: const short REJECT_TYPE = -2; michael@0: michael@0: /** michael@0: * Returned from shouldLoad or shouldProcess if the load/process is rejected michael@0: * based on the server it is hosted on or requested from (aContentLocation or michael@0: * aRequestOrigin), e.g., if you block an IMAGE because it is served from michael@0: * goatse.cx (even if you don't necessarily block other types from that michael@0: * server/domain). michael@0: * michael@0: * NOTE that it is not meant to stop future requests for this server--only the michael@0: * current request. michael@0: */ michael@0: const short REJECT_SERVER = -3; michael@0: michael@0: /** michael@0: * Returned from shouldLoad or shouldProcess if the load/process is rejected michael@0: * based on some other criteria. Mozilla callers will handle this like michael@0: * REJECT_REQUEST; third-party implementors may, for example, use this to michael@0: * direct their own callers to consult the extra parameter for additional michael@0: * details. michael@0: */ michael@0: const short REJECT_OTHER = -4; michael@0: michael@0: /** michael@0: * Returned from shouldLoad or shouldProcess if the load or process request michael@0: * is not rejected. michael@0: */ michael@0: const short ACCEPT = 1; michael@0: michael@0: ////////////////////////////////////////////////////////////////////// michael@0: michael@0: /** michael@0: * Should the resource at this location be loaded? michael@0: * ShouldLoad will be called before loading the resource at aContentLocation michael@0: * to determine whether to start the load at all. michael@0: * michael@0: * @param aContentType the type of content being tested. This will be one michael@0: * one of the TYPE_* constants. michael@0: * michael@0: * @param aContentLocation the location of the content being checked; must michael@0: * not be null michael@0: * michael@0: * @param aRequestOrigin OPTIONAL. the location of the resource that michael@0: * initiated this load request; can be null if michael@0: * inapplicable michael@0: * michael@0: * @param aContext OPTIONAL. the nsIDOMNode or nsIDOMWindow that michael@0: * initiated the request, or something that can QI michael@0: * to one of those; can be null if inapplicable. michael@0: * Note that for navigation events (new windows and michael@0: * link clicks), this is the NEW window. michael@0: * michael@0: * @param aMimeTypeGuess OPTIONAL. a guess for the requested content's michael@0: * MIME type, based on information available to michael@0: * the request initiator (e.g., an OBJECT's type michael@0: * attribute); does not reliably reflect the michael@0: * actual MIME type of the requested content michael@0: * michael@0: * @param aExtra an OPTIONAL argument, pass-through for non-Gecko michael@0: * callers to pass extra data to callees. michael@0: * michael@0: * @param aRequestPrincipal an OPTIONAL argument, defines the principal that michael@0: * caused the load. This is optional only for michael@0: * non-gecko code: all gecko code should set this michael@0: * argument. For navigation events, this is michael@0: * the principal of the page that caused this load. michael@0: * michael@0: * @return ACCEPT or REJECT_* michael@0: * michael@0: * @note shouldLoad can be called while the DOM and layout of the document michael@0: * involved is in an inconsistent state. This means that implementors of michael@0: * this method MUST NOT do any of the following: michael@0: * 1) Modify the DOM in any way (e.g. setting attributes is a no-no). michael@0: * 2) Query any DOM properties that depend on layout (e.g. offset* michael@0: * properties). michael@0: * 3) Query any DOM properties that depend on style (e.g. computed style). michael@0: * 4) Query any DOM properties that depend on the current state of the DOM michael@0: * outside the "context" node (e.g. lengths of node lists). michael@0: * 5) [JavaScript implementations only] Access properties of any sort on any michael@0: * object without using XPCNativeWrapper (either explicitly or michael@0: * implicitly). Due to various DOM0 things, this leads to item 4. michael@0: * If you do any of these things in your shouldLoad implementation, expect michael@0: * unpredictable behavior, possibly including crashes, content not showing michael@0: * up, content showing up doubled, etc. If you need to do any of the things michael@0: * above, do them off timeout or event. michael@0: */ michael@0: short shouldLoad(in nsContentPolicyType aContentType, michael@0: in nsIURI aContentLocation, michael@0: in nsIURI aRequestOrigin, michael@0: in nsISupports aContext, michael@0: in ACString aMimeTypeGuess, michael@0: in nsISupports aExtra, michael@0: [optional] in nsIPrincipal aRequestPrincipal); michael@0: michael@0: /** michael@0: * Should the resource be processed? michael@0: * ShouldProcess will be called once all the information passed to it has michael@0: * been determined about the resource, typically after part of the resource michael@0: * has been loaded. michael@0: * michael@0: * @param aContentType the type of content being tested. This will be one michael@0: * one of the TYPE_* constants. michael@0: * michael@0: * @param aContentLocation OPTIONAL; the location of the resource being michael@0: * requested: MAY be, e.g., a post-redirection URI michael@0: * for the resource. michael@0: * michael@0: * @param aRequestOrigin OPTIONAL. the location of the resource that michael@0: * initiated this load request; can be null if michael@0: * inapplicable michael@0: * michael@0: * @param aContext OPTIONAL. the nsIDOMNode or nsIDOMWindow that michael@0: * initiated the request, or something that can QI michael@0: * to one of those; can be null if inapplicable. michael@0: * michael@0: * @param aMimeType the MIME type of the requested resource (e.g., michael@0: * image/png), as reported by the networking library, michael@0: * if available (may be empty if inappropriate for michael@0: * the type, e.g., TYPE_REFRESH). michael@0: * michael@0: * @param aExtra an OPTIONAL argument, pass-through for non-Gecko michael@0: * callers to pass extra data to callees. michael@0: * michael@0: * @return ACCEPT or REJECT_* michael@0: * michael@0: * @note shouldProcess can be called while the DOM and layout of the document michael@0: * involved is in an inconsistent state. See the note on shouldLoad to see michael@0: * what this means for implementors of this method. michael@0: */ michael@0: short shouldProcess(in nsContentPolicyType aContentType, michael@0: in nsIURI aContentLocation, michael@0: in nsIURI aRequestOrigin, michael@0: in nsISupports aContext, michael@0: in ACString aMimeType, michael@0: in nsISupports aExtra, michael@0: [optional] in nsIPrincipal aRequestPrincipal); michael@0: michael@0: };