1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/base/public/nsIContentPolicy.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,310 @@
1.4 +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim: set ft=cpp tw=78 sw=2 et ts=8 : */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIURI;
1.13 +interface nsIDOMNode;
1.14 +interface nsIPrincipal;
1.15 +
1.16 +/**
1.17 + * The type of nsIContentPolicy::TYPE_*
1.18 + */
1.19 +typedef unsigned long nsContentPolicyType;
1.20 +
1.21 +/**
1.22 + * Interface for content policy mechanism. Implementations of this
1.23 + * interface can be used to control loading of various types of out-of-line
1.24 + * content, or processing of certain types of in-line content.
1.25 + *
1.26 + * WARNING: do not block the caller from shouldLoad or shouldProcess (e.g.,
1.27 + * by launching a dialog to prompt the user for something).
1.28 + */
1.29 +
1.30 +[scriptable,uuid(b6a71698-c117-441d-86b9-480cf06e3952)]
1.31 +interface nsIContentPolicy : nsISupports
1.32 +{
1.33 + /**
1.34 + * Gecko/Firefox developers: Do not use TYPE_OTHER under any circumstances.
1.35 + *
1.36 + * Extension developers: Whenever it is reasonable, use one of the existing
1.37 + * content types. If none of the existing content types are right for
1.38 + * something you are doing, file a bug in the Core/DOM component that
1.39 + * includes a patch that adds your new content type to the end of the list of
1.40 + * TYPE_* constants here. But, don't start using your new content type until
1.41 + * your patch has been accepted, because it will be uncertain what exact
1.42 + * value and name your new content type will have; in that interim period,
1.43 + * use TYPE_OTHER. In your patch, document your new content type in the style
1.44 + * of the existing ones. In the bug you file, provide a more detailed
1.45 + * description of the new type of content you want Gecko to support, so that
1.46 + * the existing implementations of nsIContentPolicy can be properly modified
1.47 + * to deal with that new type of content.
1.48 + *
1.49 + * Implementations of nsIContentPolicy should treat this the same way they
1.50 + * treat unknown types, because existing users of TYPE_OTHER may be converted
1.51 + * to use new content types.
1.52 + */
1.53 + const nsContentPolicyType TYPE_OTHER = 1;
1.54 +
1.55 + /**
1.56 + * Indicates an executable script (such as JavaScript).
1.57 + */
1.58 + const nsContentPolicyType TYPE_SCRIPT = 2;
1.59 +
1.60 + /**
1.61 + * Indicates an image (e.g., IMG elements).
1.62 + */
1.63 + const nsContentPolicyType TYPE_IMAGE = 3;
1.64 +
1.65 + /**
1.66 + * Indicates a stylesheet (e.g., STYLE elements).
1.67 + */
1.68 + const nsContentPolicyType TYPE_STYLESHEET = 4;
1.69 +
1.70 + /**
1.71 + * Indicates a generic object (plugin-handled content typically falls under
1.72 + * this category).
1.73 + */
1.74 + const nsContentPolicyType TYPE_OBJECT = 5;
1.75 +
1.76 + /**
1.77 + * Indicates a document at the top-level (i.e., in a browser).
1.78 + */
1.79 + const nsContentPolicyType TYPE_DOCUMENT = 6;
1.80 +
1.81 + /**
1.82 + * Indicates a document contained within another document (e.g., IFRAMEs,
1.83 + * FRAMES, and OBJECTs).
1.84 + */
1.85 + const nsContentPolicyType TYPE_SUBDOCUMENT = 7;
1.86 +
1.87 + /**
1.88 + * Indicates a timed refresh.
1.89 + *
1.90 + * shouldLoad will never get this, because it does not represent content
1.91 + * to be loaded (the actual load triggered by the refresh will go through
1.92 + * shouldLoad as expected).
1.93 + *
1.94 + * shouldProcess will get this for, e.g., META Refresh elements and HTTP
1.95 + * Refresh headers.
1.96 + */
1.97 + const nsContentPolicyType TYPE_REFRESH = 8;
1.98 +
1.99 + /**
1.100 + * Indicates an XBL binding request, triggered either by -moz-binding CSS
1.101 + * property.
1.102 + */
1.103 + const nsContentPolicyType TYPE_XBL = 9;
1.104 +
1.105 + /**
1.106 + * Indicates a ping triggered by a click on <A PING="..."> element.
1.107 + */
1.108 + const nsContentPolicyType TYPE_PING = 10;
1.109 +
1.110 + /**
1.111 + * Indicates an XMLHttpRequest. Also used for document.load and for EventSource.
1.112 + */
1.113 + const nsContentPolicyType TYPE_XMLHTTPREQUEST = 11;
1.114 + const nsContentPolicyType TYPE_DATAREQUEST = 11; // alias
1.115 +
1.116 + /**
1.117 + * Indicates a request by a plugin.
1.118 + */
1.119 + const nsContentPolicyType TYPE_OBJECT_SUBREQUEST = 12;
1.120 +
1.121 + /**
1.122 + * Indicates a DTD loaded by an XML document.
1.123 + */
1.124 + const nsContentPolicyType TYPE_DTD = 13;
1.125 +
1.126 + /**
1.127 + * Indicates a font loaded via @font-face rule.
1.128 + */
1.129 + const nsContentPolicyType TYPE_FONT = 14;
1.130 +
1.131 + /**
1.132 + * Indicates a video or audio load.
1.133 + */
1.134 + const nsContentPolicyType TYPE_MEDIA = 15;
1.135 +
1.136 + /**
1.137 + * Indicates a WebSocket load.
1.138 + */
1.139 + const nsContentPolicyType TYPE_WEBSOCKET = 16;
1.140 +
1.141 + /**
1.142 + * Indicates a Content Security Policy report.
1.143 + */
1.144 + const nsContentPolicyType TYPE_CSP_REPORT = 17;
1.145 +
1.146 + /**
1.147 + * Indicates a style sheet transformation.
1.148 + */
1.149 + const nsContentPolicyType TYPE_XSLT = 18;
1.150 +
1.151 + /**
1.152 + * Indicates a beacon post.
1.153 + */
1.154 + const nsContentPolicyType TYPE_BEACON = 19;
1.155 +
1.156 + /* When adding new content types, please update nsContentBlocker,
1.157 + * NS_CP_ContentTypeName, contentSecurityPolicy.js, all nsIContentPolicy
1.158 + * implementations, and other things that are not listed here that are
1.159 + * related to nsIContentPolicy. */
1.160 +
1.161 + //////////////////////////////////////////////////////////////////////
1.162 +
1.163 + /**
1.164 + * Returned from shouldLoad or shouldProcess if the load or process request
1.165 + * is rejected based on details of the request.
1.166 + */
1.167 + const short REJECT_REQUEST = -1;
1.168 +
1.169 + /**
1.170 + * Returned from shouldLoad or shouldProcess if the load/process is rejected
1.171 + * based solely on its type (of the above flags).
1.172 + *
1.173 + * NOTE that it is not meant to stop future requests for this type--only the
1.174 + * current request.
1.175 + */
1.176 + const short REJECT_TYPE = -2;
1.177 +
1.178 + /**
1.179 + * Returned from shouldLoad or shouldProcess if the load/process is rejected
1.180 + * based on the server it is hosted on or requested from (aContentLocation or
1.181 + * aRequestOrigin), e.g., if you block an IMAGE because it is served from
1.182 + * goatse.cx (even if you don't necessarily block other types from that
1.183 + * server/domain).
1.184 + *
1.185 + * NOTE that it is not meant to stop future requests for this server--only the
1.186 + * current request.
1.187 + */
1.188 + const short REJECT_SERVER = -3;
1.189 +
1.190 + /**
1.191 + * Returned from shouldLoad or shouldProcess if the load/process is rejected
1.192 + * based on some other criteria. Mozilla callers will handle this like
1.193 + * REJECT_REQUEST; third-party implementors may, for example, use this to
1.194 + * direct their own callers to consult the extra parameter for additional
1.195 + * details.
1.196 + */
1.197 + const short REJECT_OTHER = -4;
1.198 +
1.199 + /**
1.200 + * Returned from shouldLoad or shouldProcess if the load or process request
1.201 + * is not rejected.
1.202 + */
1.203 + const short ACCEPT = 1;
1.204 +
1.205 + //////////////////////////////////////////////////////////////////////
1.206 +
1.207 + /**
1.208 + * Should the resource at this location be loaded?
1.209 + * ShouldLoad will be called before loading the resource at aContentLocation
1.210 + * to determine whether to start the load at all.
1.211 + *
1.212 + * @param aContentType the type of content being tested. This will be one
1.213 + * one of the TYPE_* constants.
1.214 + *
1.215 + * @param aContentLocation the location of the content being checked; must
1.216 + * not be null
1.217 + *
1.218 + * @param aRequestOrigin OPTIONAL. the location of the resource that
1.219 + * initiated this load request; can be null if
1.220 + * inapplicable
1.221 + *
1.222 + * @param aContext OPTIONAL. the nsIDOMNode or nsIDOMWindow that
1.223 + * initiated the request, or something that can QI
1.224 + * to one of those; can be null if inapplicable.
1.225 + * Note that for navigation events (new windows and
1.226 + * link clicks), this is the NEW window.
1.227 + *
1.228 + * @param aMimeTypeGuess OPTIONAL. a guess for the requested content's
1.229 + * MIME type, based on information available to
1.230 + * the request initiator (e.g., an OBJECT's type
1.231 + * attribute); does not reliably reflect the
1.232 + * actual MIME type of the requested content
1.233 + *
1.234 + * @param aExtra an OPTIONAL argument, pass-through for non-Gecko
1.235 + * callers to pass extra data to callees.
1.236 + *
1.237 + * @param aRequestPrincipal an OPTIONAL argument, defines the principal that
1.238 + * caused the load. This is optional only for
1.239 + * non-gecko code: all gecko code should set this
1.240 + * argument. For navigation events, this is
1.241 + * the principal of the page that caused this load.
1.242 + *
1.243 + * @return ACCEPT or REJECT_*
1.244 + *
1.245 + * @note shouldLoad can be called while the DOM and layout of the document
1.246 + * involved is in an inconsistent state. This means that implementors of
1.247 + * this method MUST NOT do any of the following:
1.248 + * 1) Modify the DOM in any way (e.g. setting attributes is a no-no).
1.249 + * 2) Query any DOM properties that depend on layout (e.g. offset*
1.250 + * properties).
1.251 + * 3) Query any DOM properties that depend on style (e.g. computed style).
1.252 + * 4) Query any DOM properties that depend on the current state of the DOM
1.253 + * outside the "context" node (e.g. lengths of node lists).
1.254 + * 5) [JavaScript implementations only] Access properties of any sort on any
1.255 + * object without using XPCNativeWrapper (either explicitly or
1.256 + * implicitly). Due to various DOM0 things, this leads to item 4.
1.257 + * If you do any of these things in your shouldLoad implementation, expect
1.258 + * unpredictable behavior, possibly including crashes, content not showing
1.259 + * up, content showing up doubled, etc. If you need to do any of the things
1.260 + * above, do them off timeout or event.
1.261 + */
1.262 + short shouldLoad(in nsContentPolicyType aContentType,
1.263 + in nsIURI aContentLocation,
1.264 + in nsIURI aRequestOrigin,
1.265 + in nsISupports aContext,
1.266 + in ACString aMimeTypeGuess,
1.267 + in nsISupports aExtra,
1.268 + [optional] in nsIPrincipal aRequestPrincipal);
1.269 +
1.270 + /**
1.271 + * Should the resource be processed?
1.272 + * ShouldProcess will be called once all the information passed to it has
1.273 + * been determined about the resource, typically after part of the resource
1.274 + * has been loaded.
1.275 + *
1.276 + * @param aContentType the type of content being tested. This will be one
1.277 + * one of the TYPE_* constants.
1.278 + *
1.279 + * @param aContentLocation OPTIONAL; the location of the resource being
1.280 + * requested: MAY be, e.g., a post-redirection URI
1.281 + * for the resource.
1.282 + *
1.283 + * @param aRequestOrigin OPTIONAL. the location of the resource that
1.284 + * initiated this load request; can be null if
1.285 + * inapplicable
1.286 + *
1.287 + * @param aContext OPTIONAL. the nsIDOMNode or nsIDOMWindow that
1.288 + * initiated the request, or something that can QI
1.289 + * to one of those; can be null if inapplicable.
1.290 + *
1.291 + * @param aMimeType the MIME type of the requested resource (e.g.,
1.292 + * image/png), as reported by the networking library,
1.293 + * if available (may be empty if inappropriate for
1.294 + * the type, e.g., TYPE_REFRESH).
1.295 + *
1.296 + * @param aExtra an OPTIONAL argument, pass-through for non-Gecko
1.297 + * callers to pass extra data to callees.
1.298 + *
1.299 + * @return ACCEPT or REJECT_*
1.300 + *
1.301 + * @note shouldProcess can be called while the DOM and layout of the document
1.302 + * involved is in an inconsistent state. See the note on shouldLoad to see
1.303 + * what this means for implementors of this method.
1.304 + */
1.305 + short shouldProcess(in nsContentPolicyType aContentType,
1.306 + in nsIURI aContentLocation,
1.307 + in nsIURI aRequestOrigin,
1.308 + in nsISupports aContext,
1.309 + in ACString aMimeType,
1.310 + in nsISupports aExtra,
1.311 + [optional] in nsIPrincipal aRequestPrincipal);
1.312 +
1.313 +};
