content/base/public/nsIContentPolicy.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ft=cpp tw=78 sw=2 et ts=8 : */
   3 /* ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Zero-Knowledge Systems, Inc.
  20  * Portions created by the Initial Developer are Copyright (C) 2000
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Timothy Watt <riceman+bmo@mail.rit.edu>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 interface nsIURI;
  43 interface nsIDOMNode;
  44
  45 /**
  46  * Interface for content policy mechanism.  Implementations of this
  47  * interface can be used to control loading of various types of out-of-line
  48  * content, or processing of certain types of in-line content.
  49  *
  50  * WARNING: do not block the caller from shouldLoad or shouldProcess (e.g.,
  51  * by launching a dialog to prompt the user for something).
  52  */
  53
  54 [scriptable,uuid(58cf9dca-40b3-6211-a508-7351f437a53e)]
  55 interface nsIContentPolicy : nsISupports
  56 {
  57   const unsigned long TYPE_OTHER       = 1;
  58
  59   /**
  60    * Indicates an executable script (such as JavaScript).
  61    */
  62   const unsigned long TYPE_SCRIPT      = 2;
  63
  64   /**
  65    * Indicates an image (e.g., IMG elements).
  66    */
  67   const unsigned long TYPE_IMAGE       = 3;
  68
  69   /**
  70    * Indicates a stylesheet (e.g., STYLE elements).
  71    */
  72   const unsigned long TYPE_STYLESHEET  = 4;
  73
  74   /**
  75    * Indicates a generic object (plugin-handled content typically falls under
  76    * this category).
  77    */
  78   const unsigned long TYPE_OBJECT      = 5;
  79
  80   /**
  81    * Indicates a document at the top-level (i.e., in a browser).
  82    */
  83   const unsigned long TYPE_DOCUMENT    = 6;
  84
  85   /**
  86    * Indicates a document contained within another document (e.g., IFRAMEs,
  87    * FRAMES, and OBJECTs).
  88    */
  89   const unsigned long TYPE_SUBDOCUMENT = 7;
  90
  91   /**
  92    * Indicates a timed refresh.
  93    *
  94    * shouldLoad will never get this, because it does not represent content
  95    * to be loaded (the actual load triggered by the refresh will go through
  96    * shouldLoad as expected).
  97    *
  98    * shouldProcess will get this for, e.g., META Refresh elements and HTTP
  99    * Refresh headers.
 100    */
 101   const unsigned long TYPE_REFRESH     = 8;
 102
 103   /**
 104    * Indicates an XBL binding request, triggered either by -moz-binding CSS
 105    * property or Document.addBinding method.
 106    */
 107   const unsigned long TYPE_XBL         = 9;
 108
 109   /**
 110    * Indicates a ping triggered by a click on <A PING="..."> element.
 111    */
 112   const unsigned long TYPE_PING        = 10;
 113
 114   /**
 115    * Indicates an XMLHttpRequest.
 116    */
 117   const unsigned long TYPE_XMLHTTPREQUEST = 11;
 118
 119   /**
 120    * Indicates a request by a plugin.
 121    */
 122   const unsigned long TYPE_OBJECT_SUBREQUEST = 12;
 123
 124   /**
 125    * Indicates a DTD loaded by an XML document.
 126    */
 127   const unsigned long TYPE_DTD = 13;
 128
 129   /**
 130    * Indicates a font loaded via @font-face rule.
 131    */
 132   const unsigned long TYPE_FONT = 14;
 133
 134   //////////////////////////////////////////////////////////////////////
 135
 136   /**
 137    * Returned from shouldLoad or shouldProcess if the load or process request
 138    * is rejected based on details of the request.
 139    */
 140   const short REJECT_REQUEST = -1;
 141
 142   /**
 143    * Returned from shouldLoad or shouldProcess if the load/process is rejected
 144    * based solely on its type (of the above flags).
 145    *
 146    * NOTE that it is not meant to stop future requests for this type--only the
 147    * current request.
 148    */
 149   const short REJECT_TYPE = -2;
 150
 151   /**
 152    * Returned from shouldLoad or shouldProcess if the load/process is rejected
 153    * based on the server it is hosted on or requested from (aContentLocation or
 154    * aRequestOrigin), e.g., if you block an IMAGE because it is served from
 155    * goatse.cx (even if you don't necessarily block other types from that
 156    * server/domain).
 157    *
 158    * NOTE that it is not meant to stop future requests for this server--only the
 159    * current request.
 160    */
 161   const short REJECT_SERVER = -3;
 162
 163   /**
 164    * Returned from shouldLoad or shouldProcess if the load/process is rejected
 165    * based on some other criteria. Mozilla callers will handle this like
 166    * REJECT_REQUEST; third-party implementors may, for example, use this to
 167    * direct their own callers to consult the extra parameter for additional
 168    * details.
 169    */
 170   const short REJECT_OTHER = -4;
 171
 172   /**
 173    * Returned from shouldLoad or shouldProcess if the load or process request
 174    * is not rejected.
 175    */
 176   const short ACCEPT = 1;
 177
 178   //////////////////////////////////////////////////////////////////////
 179
 180   /**
 181    * Should the resource at this location be loaded?
 182    * ShouldLoad will be called before loading the resource at aContentLocation
 183    * to determine whether to start the load at all.
 184    *
 185    * @param aContentType      the type of content being tested. This will be one
 186    *                          one of the TYPE_* constants.
 187    *
 188    * @param aContentLocation  the location of the content being checked; must
 189    *                          not be null
 190    *
 191    * @param aRequestOrigin    OPTIONAL. the location of the resource that
 192    *                          initiated this load request; can be null if
 193    *                          inapplicable
 194    *
 195    * @param aContext          OPTIONAL. the nsIDOMNode or nsIDOMWindow that
 196    *                          initiated the request, or something that can QI
 197    *                          to one of those; can be null if inapplicable.
 198    *
 199    * @param aMimeTypeGuess    OPTIONAL. a guess for the requested content's
 200    *                          MIME type, based on information available to
 201    *                          the request initiator (e.g., an OBJECT's type
 202    *                          attribute); does not reliably reflect the
 203    *                          actual MIME type of the requested content
 204    *
 205    * @param aExtra            an OPTIONAL argument, pass-through for non-Gecko
 206    *                          callers to pass extra data to callees.
 207    *
 208    * @return ACCEPT or REJECT_*
 209    *
 210    * @note shouldLoad can be called while the DOM and layout of the document
 211    * involved is in an inconsistent state.  This means that implementors of
 212    * this method MUST NOT do any of the following:
 213    * 1)  Modify the DOM in any way (e.g. setting attributes is a no-no).
 214    * 2)  Query any DOM properties that depend on layout (e.g. offset*
 215    *     properties).
 216    * 3)  Query any DOM properties that depend on style (e.g. computed style).
 217    * 4)  Query any DOM properties that depend on the current state of the DOM
 218    *     outside the "context" node (e.g. lengths of node lists).
 219    * 5)  [JavaScript implementations only] Access properties of any sort on any
 220    *     object without using XPCNativeWrapper (either explicitly or
 221    *     implicitly).  Due to various DOM0 things, this leads to item 4.
 222    * If you do any of these things in your shouldLoad implementation, expect
 223    * unpredictable behavior, possibly including crashes, content not showing
 224    * up, content showing up doubled, etc.  If you need to do any of the things
 225    * above, do them off timeout or event.
 226    */
 227   short shouldLoad(in unsigned long aContentType,
 228                    in nsIURI        aContentLocation,
 229                    in nsIURI        aRequestOrigin,
 230                    in nsISupports   aContext,
 231                    in ACString      aMimeTypeGuess,
 232                    in nsISupports   aExtra);
 233
 234   /**
 235    * Should the resource be processed?
 236    * ShouldProcess will be called once all the information passed to it has
 237    * been determined about the resource, typically after part of the resource
 238    * has been loaded.
 239    *
 240    * @param aContentType      the type of content being tested. This will be one
 241    *                          one of the TYPE_* constants.
 242    *
 243    * @param aContentLocation  OPTIONAL; the location of the resource being
 244    *                          requested: MAY be, e.g., a post-redirection URI
 245    *                          for the resource.
 246    *
 247    * @param aRequestOrigin    OPTIONAL. the location of the resource that
 248    *                          initiated this load request; can be null if
 249    *                          inapplicable
 250    *
 251    * @param aContext          OPTIONAL. the nsIDOMNode or nsIDOMWindow that
 252    *                          initiated the request, or something that can QI
 253    *                          to one of those; can be null if inapplicable.
 254    *
 255    * @param aMimeType         the MIME type of the requested resource (e.g.,
 256    *                          image/png), as reported by the networking library,
 257    *                          if available (may be empty if inappropriate for
 258    *                          the type, e.g., TYPE_REFRESH).
 259    *
 260    * @param aExtra            an OPTIONAL argument, pass-through for non-Gecko
 261    *                          callers to pass extra data to callees.
 262    *
 263    * @return ACCEPT or REJECT_*
 264    *
 265    * @note shouldProcess can be called while the DOM and layout of the document
 266    * involved is in an inconsistent state.  See the note on shouldLoad to see
 267    * what this means for implementors of this method.
 268    */
 269   short shouldProcess(in unsigned long aContentType,
 270                       in nsIURI        aContentLocation,
 271                       in nsIURI        aRequestOrigin,
 272                       in nsISupports   aContext,
 273                       in ACString      aMimeType,
 274                       in nsISupports   aExtra);
 275
 276 };