netwerk/base/nsIProtocolHandler.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 %{C++
   9 #include "nsCOMPtr.h"
  10
  11 /**
  12  * Protocol handlers are registered with XPCOM under the following CONTRACTID prefix:
  13  */
  14 #define NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX "@mozilla.org/network/protocol;1?name="
  15 /**
  16  * For example, "@mozilla.org/network/protocol;1?name=http"
  17  */
  18
  19 #if defined(MOZ_THUNDERBIRD) || defined(MOZ_SUITE)
  20 #define IS_ORIGIN_IS_FULL_SPEC_DEFINED 1
  21 #endif
  22 %}
  23
  24 interface nsIURI;
  25 interface nsIChannel;
  26 interface nsILoadInfo;
  27
  28 /**
  29  * nsIProtocolHandlerWithDynamicFlags
  30  *
  31  * Protocols that wish to return different flags depending on the URI should
  32  * implement this interface.
  33  */
  34 [scriptable, builtinclass, uuid(65a8e823-0591-4fc0-a56a-03265e0a4ce8)]
  35 interface nsIProtocolHandlerWithDynamicFlags : nsISupports
  36 {
  37     /*
  38      * Returns protocol flags for the given URI, which may be different from the
  39      * flags for another URI of the same scheme.
  40      */
  41     unsigned long getFlagsForURI(in nsIURI aURI);
  42 };
  43
  44 /**
  45  * nsIProtocolHandler
  46  */
  47 [scriptable, uuid(a87210e6-7c8c-41f7-864d-df809015193e)]
  48 interface nsIProtocolHandler : nsISupports
  49 {
  50     /**
  51      * The scheme of this protocol (e.g., "file").
  52      */
  53     readonly attribute ACString scheme;
  54
  55     /**
  56      * The default port is the port that this protocol normally uses.
  57      * If a port does not make sense for the protocol (e.g., "about:")
  58      * then -1 will be returned.
  59      */
  60     readonly attribute long defaultPort;
  61
  62     /**
  63      * Returns the protocol specific flags (see flag definitions below).
  64      */
  65     readonly attribute unsigned long protocolFlags;
  66
  67 %{C++
  68   // Helper method to get the protocol flags in the right way.
  69   nsresult DoGetProtocolFlags(nsIURI* aURI, uint32_t* aFlags)
  70   {
  71       nsCOMPtr<nsIProtocolHandlerWithDynamicFlags> dh = do_QueryInterface(this);
  72       nsresult rv = dh ? dh->GetFlagsForURI(aURI, aFlags) : GetProtocolFlags(aFlags);
  73       if (NS_SUCCEEDED(rv)) {
  74 #if !IS_ORIGIN_IS_FULL_SPEC_DEFINED
  75         MOZ_RELEASE_ASSERT(!(*aFlags & nsIProtocolHandler::ORIGIN_IS_FULL_SPEC),
  76                            "ORIGIN_IS_FULL_SPEC is unsupported but used");
  77 #endif
  78       }
  79       return rv;
  80   }
  81 %}
  82
  83     /**
  84      * Makes a URI object that is suitable for loading by this protocol,
  85      * where the URI string is given as an UTF-8 string.  The caller may
  86      * provide the charset from which the URI string originated, so that
  87      * the URI string can be translated back to that charset (if necessary)
  88      * before communicating with, for example, the origin server of the URI
  89      * string.  (Many servers do not support UTF-8 IRIs at the present time,
  90      * so we must be careful about tracking the native charset of the origin
  91      * server.)
  92      *
  93      * @param aSpec          - the URI string in UTF-8 encoding. depending
  94      *                         on the protocol implementation, unicode character
  95      *                         sequences may or may not be %xx escaped.
  96      * @param aOriginCharset - the charset of the document from which this URI
  97      *                         string originated.  this corresponds to the
  98      *                         charset that should be used when communicating
  99      *                         this URI to an origin server, for example.  if
 100      *                         null, then UTF-8 encoding is assumed (i.e.,
 101      *                         no charset transformation from aSpec).
 102      * @param aBaseURI       - if null, aSpec must specify an absolute URI.
 103      *                         otherwise, aSpec may be resolved relative
 104      *                         to aBaseURI, depending on the protocol.
 105      *                         If the protocol has no concept of relative
 106      *                         URI aBaseURI will simply be ignored.
 107      */
 108     nsIURI newURI(in AUTF8String aSpec,
 109                   [optional] in string aOriginCharset,
 110                   [optional] in nsIURI aBaseURI);
 111
 112     /**
 113      * Constructs a new channel from the given URI for this protocol handler and
 114      * sets the loadInfo for the constructed channel.
 115      */
 116     nsIChannel newChannel2(in nsIURI aURI, in nsILoadInfo aLoadinfo);
 117
 118     /**
 119      * Constructs a new channel from the given URI for this protocol handler.
 120      */
 121     nsIChannel newChannel(in nsIURI aURI);
 122
 123     /**
 124      * Allows a protocol to override blacklisted ports.
 125      *
 126      * This method will be called when there is an attempt to connect to a port
 127      * that is blacklisted.  For example, for most protocols, port 25 (Simple Mail
 128      * Transfer) is banned.  When a URI containing this "known-to-do-bad-things"
 129      * port number is encountered, this function will be called to ask if the
 130      * protocol handler wants to override the ban.
 131      */
 132     boolean allowPort(in long port, in string scheme);
 133
 134
 135     /**************************************************************************
 136      * Constants for the protocol flags (the first is the default mask, the
 137      * others are deviations):
 138      *
 139      * NOTE: Implementation must ignore any flags they do not understand.
 140      */
 141
 142     /**
 143      * standard full URI with authority component and concept of relative
 144      * URIs (http, ftp, ...)
 145      */
 146     const unsigned long URI_STD = 0;
 147
 148     /**
 149      * no concept of relative URIs (about, javascript, finger, ...)
 150      */
 151     const unsigned long URI_NORELATIVE = (1<<0);
 152
 153     /**
 154      * no authority component (file, ...)
 155      */
 156     const unsigned long URI_NOAUTH = (1<<1);
 157
 158     /**
 159      * This protocol handler can be proxied via a proxy (socks or http)
 160      * (e.g., irc, smtp, http, etc.).  If the protocol supports transparent
 161      * proxying, the handler should implement nsIProxiedProtocolHandler.
 162      *
 163      * If it supports only HTTP proxying, then it need not support
 164      * nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP
 165      * flag (see below).
 166      *
 167      * @see nsIProxiedProtocolHandler
 168      */
 169     const unsigned long ALLOWS_PROXY = (1<<2);
 170
 171     /**
 172      * This protocol handler can be proxied using a http proxy (e.g., http,
 173      * ftp, etc.).  nsIIOService::newChannelFromURI will feed URIs from this
 174      * protocol handler to the HTTP protocol handler instead.  This flag is
 175      * ignored if ALLOWS_PROXY is not set.
 176      */
 177     const unsigned long ALLOWS_PROXY_HTTP = (1<<3);
 178
 179     /**
 180      * The URIs for this protocol have no inherent security context, so
 181      * documents loaded via this protocol should inherit the security context
 182      * from the document that loads them.
 183      */
 184     const unsigned long URI_INHERITS_SECURITY_CONTEXT = (1<<4);
 185
 186     /**
 187      * "Automatic" loads that would replace the document (e.g. <meta> refresh,
 188      * certain types of XLinks, possibly other loads that the application
 189      * decides are not user triggered) are not allowed if the originating (NOT
 190      * the target) URI has this protocol flag.  Note that the decision as to
 191      * what constitutes an "automatic" load is made externally, by the caller
 192      * of nsIScriptSecurityManager::CheckLoadURI.  See documentation for that
 193      * method for more information.
 194      *
 195      * A typical protocol that might want to set this flag is a protocol that
 196      * shows highly untrusted content in a viewing area that the user expects
 197      * to have a lot of control over, such as an e-mail reader.
 198      */
 199     const unsigned long URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT = (1<<5);
 200
 201     /**
 202      * +-------------------------------------------------------------------+
 203      * |                                                                   |
 204      * |  ALL PROTOCOL HANDLERS MUST SET ONE OF THE FOLLOWING FIVE FLAGS.  |
 205      * |                                                                   |
 206      * +-------------------------------------------------------------------+
 207      *
 208      * These flags are used to determine who is allowed to load URIs for this
 209      * protocol.  Note that if a URI is nested, only the flags for the
 210      * innermost URI matter.  See nsINestedURI.
 211      *
 212      * If none of these five flags are set, the URI must be treated as if it
 213      * had the URI_LOADABLE_BY_ANYONE flag set, for compatibility with protocol
 214      * handlers written against Gecko 1.8 or earlier.  In this case, there may
 215      * be run-time warning messages indicating that a "default insecure"
 216      * assumption is being made.  At some point in the futures (Mozilla 2.0,
 217      * most likely), these warnings will become errors.
 218      */
 219
 220     /**
 221      * The URIs for this protocol can be loaded by anyone.  For example, any
 222      * website should be allowed to trigger a load of a URI for this protocol.
 223      * Web-safe protocols like "http" should set this flag.
 224      */
 225     const unsigned long URI_LOADABLE_BY_ANYONE = (1<<6);
 226
 227     /**
 228      * The URIs for this protocol are UNSAFE if loaded by untrusted (web)
 229      * content and may only be loaded by privileged code (for example, code
 230      * which has the system principal).  Various internal protocols should set
 231      * this flag.
 232      */
 233     const unsigned long URI_DANGEROUS_TO_LOAD = (1<<7);
 234
 235     /**
 236      * The URIs for this protocol point to resources that are part of the
 237      * application's user interface.  There are cases when such resources may
 238      * be made accessible to untrusted content such as web pages, so this is
 239      * less restrictive than URI_DANGEROUS_TO_LOAD but more restrictive than
 240      * URI_LOADABLE_BY_ANYONE.  See the documentation for
 241      * nsIScriptSecurityManager::CheckLoadURI.
 242      */
 243     const unsigned long URI_IS_UI_RESOURCE = (1<<8);
 244
 245     /**
 246      * Loading of URIs for this protocol from other origins should only be
 247      * allowed if those origins should have access to the local filesystem.
 248      * It's up to the application to decide what origins should have such
 249      * access.  Protocols like "file" that point to local data should set this
 250      * flag.
 251      */
 252     const unsigned long URI_IS_LOCAL_FILE = (1<<9);
 253
 254     /**
 255      * The URIs for this protocol can be loaded only by callers with a
 256      * principal that subsumes this uri. For example, privileged code and
 257      * websites that are same origin as this uri.
 258      */
 259     const unsigned long URI_LOADABLE_BY_SUBSUMERS = (1<<10);
 260
 261     /**
 262      * Channels using this protocol never call OnDataAvailable
 263      * on the listener passed to AsyncOpen and they therefore
 264      * do not return any data that we can use.
 265      */
 266     const unsigned long URI_DOES_NOT_RETURN_DATA = (1<<11);
 267
 268     /**
 269      * URIs for this protocol are considered to be local resources.  This could
 270      * be a local file (URI_IS_LOCAL_FILE), a UI resource (URI_IS_UI_RESOURCE),
 271      * or something else that would not hit the network.
 272      */
 273     const unsigned long URI_IS_LOCAL_RESOURCE = (1<<12);
 274
 275     /**
 276      * URIs for this protocol execute script when they are opened.
 277      */
 278     const unsigned long URI_OPENING_EXECUTES_SCRIPT = (1<<13);
 279
 280     /**
 281      * Loading channels from this protocol has side-effects that make
 282      * it unsuitable for saving to a local file.
 283      */
 284     const unsigned long URI_NON_PERSISTABLE = (1<<14);
 285
 286     /**
 287      * URIs for this protocol require the webapps permission on the principal
 288      * when opening URIs for a different domain. See bug#773886
 289      */
 290     const unsigned long URI_CROSS_ORIGIN_NEEDS_WEBAPPS_PERM = (1<<15);
 291
 292     /**
 293      * Channels for this protocol don't need to spin the event loop to handle
 294      * Open() and reads on the resulting stream.
 295      */
 296     const unsigned long URI_SYNC_LOAD_IS_OK = (1<<16);
 297
 298     /**
 299      * All the origins whose URI has this scheme are considered potentially
 300      * trustworthy.
 301      * Per the SecureContext spec, https: and wss: should be considered
 302      * a priori secure, and implementations may consider other,
 303      * implementation-specific URI schemes as secure.
 304      */
 305     const unsigned long URI_IS_POTENTIALLY_TRUSTWORTHY = (1<<17);
 306
 307     /**
 308      * This URI may be fetched and the contents are visible to anyone. This is
 309      * semantically equivalent to the resource being served with all-access CORS
 310      * headers.
 311      */
 312     const unsigned long URI_FETCHABLE_BY_ANYONE = (1 << 18);
 313
 314     /**
 315      * If this flag is set, then the origin for this protocol is the full URI
 316      * spec, not just the scheme + host + port.
 317      *
 318      * Note: this is not supported in Firefox.  It is currently only available
 319      * in Thunderbird and SeaMonkey.
 320      */
 321     const unsigned long ORIGIN_IS_FULL_SPEC = (1 << 19);
 322
 323     /**
 324      * If this flag is set, the URI does not always allow content using the same
 325      * protocol to link to it.
 326      */
 327     const unsigned long URI_SCHEME_NOT_SELF_LINKABLE = (1 << 20);
 328
 329     /**
 330      * The URIs for this protocol can be loaded by extensions.
 331      */
 332     const unsigned long URI_LOADABLE_BY_EXTENSIONS = (1 << 21);
 333
 334     /**
 335      * The URIs for this protocol can not be loaded into private contexts.
 336      */
 337     const unsigned long URI_DISALLOW_IN_PRIVATE_CONTEXT = (1 << 22);
 338 };