1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIProtocolHandler.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,266 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIChannel;
1.13 +
1.14 +/**
1.15 + * nsIProtocolHandler
1.16 + */
1.17 +[scriptable, uuid(f5753fec-a051-4ddc-8891-11f1f1575072)]
1.18 +interface nsIProtocolHandler : nsISupports
1.19 +{
1.20 + /**
1.21 + * The scheme of this protocol (e.g., "file").
1.22 + */
1.23 + readonly attribute ACString scheme;
1.24 +
1.25 + /**
1.26 + * The default port is the port that this protocol normally uses.
1.27 + * If a port does not make sense for the protocol (e.g., "about:")
1.28 + * then -1 will be returned.
1.29 + */
1.30 + readonly attribute long defaultPort;
1.31 +
1.32 + /**
1.33 + * Returns the protocol specific flags (see flag definitions below).
1.34 + */
1.35 + readonly attribute unsigned long protocolFlags;
1.36 +
1.37 + /**
1.38 + * Makes a URI object that is suitable for loading by this protocol,
1.39 + * where the URI string is given as an UTF-8 string. The caller may
1.40 + * provide the charset from which the URI string originated, so that
1.41 + * the URI string can be translated back to that charset (if necessary)
1.42 + * before communicating with, for example, the origin server of the URI
1.43 + * string. (Many servers do not support UTF-8 IRIs at the present time,
1.44 + * so we must be careful about tracking the native charset of the origin
1.45 + * server.)
1.46 + *
1.47 + * @param aSpec - the URI string in UTF-8 encoding. depending
1.48 + * on the protocol implementation, unicode character
1.49 + * sequences may or may not be %xx escaped.
1.50 + * @param aOriginCharset - the charset of the document from which this URI
1.51 + * string originated. this corresponds to the
1.52 + * charset that should be used when communicating
1.53 + * this URI to an origin server, for example. if
1.54 + * null, then UTF-8 encoding is assumed (i.e.,
1.55 + * no charset transformation from aSpec).
1.56 + * @param aBaseURI - if null, aSpec must specify an absolute URI.
1.57 + * otherwise, aSpec may be resolved relative
1.58 + * to aBaseURI, depending on the protocol.
1.59 + * If the protocol has no concept of relative
1.60 + * URI aBaseURI will simply be ignored.
1.61 + */
1.62 + nsIURI newURI(in AUTF8String aSpec,
1.63 + in string aOriginCharset,
1.64 + in nsIURI aBaseURI);
1.65 +
1.66 + /**
1.67 + * Constructs a new channel from the given URI for this protocol handler.
1.68 + */
1.69 + nsIChannel newChannel(in nsIURI aURI);
1.70 +
1.71 + /**
1.72 + * Allows a protocol to override blacklisted ports.
1.73 + *
1.74 + * This method will be called when there is an attempt to connect to a port
1.75 + * that is blacklisted. For example, for most protocols, port 25 (Simple Mail
1.76 + * Transfer) is banned. When a URI containing this "known-to-do-bad-things"
1.77 + * port number is encountered, this function will be called to ask if the
1.78 + * protocol handler wants to override the ban.
1.79 + */
1.80 + boolean allowPort(in long port, in string scheme);
1.81 +
1.82 +
1.83 + /**************************************************************************
1.84 + * Constants for the protocol flags (the first is the default mask, the
1.85 + * others are deviations):
1.86 + *
1.87 + * NOTE: Implementation must ignore any flags they do not understand.
1.88 + */
1.89 +
1.90 + /**
1.91 + * standard full URI with authority component and concept of relative
1.92 + * URIs (http, ftp, ...)
1.93 + */
1.94 + const unsigned long URI_STD = 0;
1.95 +
1.96 + /**
1.97 + * no concept of relative URIs (about, javascript, finger, ...)
1.98 + */
1.99 + const unsigned long URI_NORELATIVE = (1<<0);
1.100 +
1.101 + /**
1.102 + * no authority component (file, ...)
1.103 + */
1.104 + const unsigned long URI_NOAUTH = (1<<1);
1.105 +
1.106 + /**
1.107 + * This protocol handler can be proxied via a proxy (socks or http)
1.108 + * (e.g., irc, smtp, http, etc.). If the protocol supports transparent
1.109 + * proxying, the handler should implement nsIProxiedProtocolHandler.
1.110 + *
1.111 + * If it supports only HTTP proxying, then it need not support
1.112 + * nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP
1.113 + * flag (see below).
1.114 + *
1.115 + * @see nsIProxiedProtocolHandler
1.116 + */
1.117 + const unsigned long ALLOWS_PROXY = (1<<2);
1.118 +
1.119 + /**
1.120 + * This protocol handler can be proxied using a http proxy (e.g., http,
1.121 + * ftp, etc.). nsIIOService::newChannelFromURI will feed URIs from this
1.122 + * protocol handler to the HTTP protocol handler instead. This flag is
1.123 + * ignored if ALLOWS_PROXY is not set.
1.124 + */
1.125 + const unsigned long ALLOWS_PROXY_HTTP = (1<<3);
1.126 +
1.127 + /**
1.128 + * The URIs for this protocol have no inherent security context, so
1.129 + * documents loaded via this protocol should inherit the security context
1.130 + * from the document that loads them.
1.131 + */
1.132 + const unsigned long URI_INHERITS_SECURITY_CONTEXT = (1<<4);
1.133 +
1.134 + /**
1.135 + * "Automatic" loads that would replace the document (e.g. <meta> refresh,
1.136 + * certain types of XLinks, possibly other loads that the application
1.137 + * decides are not user triggered) are not allowed if the originating (NOT
1.138 + * the target) URI has this protocol flag. Note that the decision as to
1.139 + * what constitutes an "automatic" load is made externally, by the caller
1.140 + * of nsIScriptSecurityManager::CheckLoadURI. See documentation for that
1.141 + * method for more information.
1.142 + *
1.143 + * A typical protocol that might want to set this flag is a protocol that
1.144 + * shows highly untrusted content in a viewing area that the user expects
1.145 + * to have a lot of control over, such as an e-mail reader.
1.146 + */
1.147 + const unsigned long URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT = (1<<5);
1.148 +
1.149 + /**
1.150 + * +-------------------------------------------------------------------+
1.151 + * | |
1.152 + * | ALL PROTOCOL HANDLERS MUST SET ONE OF THE FOLLOWING FIVE FLAGS. |
1.153 + * | |
1.154 + * +-------------------------------------------------------------------+
1.155 + *
1.156 + * These flags are used to determine who is allowed to load URIs for this
1.157 + * protocol. Note that if a URI is nested, only the flags for the
1.158 + * innermost URI matter. See nsINestedURI.
1.159 + *
1.160 + * If none of these five flags are set, the URI must be treated as if it
1.161 + * had the URI_LOADABLE_BY_ANYONE flag set, for compatibility with protocol
1.162 + * handlers written against Gecko 1.8 or earlier. In this case, there may
1.163 + * be run-time warning messages indicating that a "default insecure"
1.164 + * assumption is being made. At some point in the futures (Mozilla 2.0,
1.165 + * most likely), these warnings will become errors.
1.166 + */
1.167 +
1.168 + /**
1.169 + * The URIs for this protocol can be loaded by anyone. For example, any
1.170 + * website should be allowed to trigger a load of a URI for this protocol.
1.171 + * Web-safe protocols like "http" should set this flag.
1.172 + */
1.173 + const unsigned long URI_LOADABLE_BY_ANYONE = (1<<6);
1.174 +
1.175 + /**
1.176 + * The URIs for this protocol are UNSAFE if loaded by untrusted (web)
1.177 + * content and may only be loaded by privileged code (for example, code
1.178 + * which has the system principal). Various internal protocols should set
1.179 + * this flag.
1.180 + */
1.181 + const unsigned long URI_DANGEROUS_TO_LOAD = (1<<7);
1.182 +
1.183 + /**
1.184 + * The URIs for this protocol point to resources that are part of the
1.185 + * application's user interface. There are cases when such resources may
1.186 + * be made accessible to untrusted content such as web pages, so this is
1.187 + * less restrictive than URI_DANGEROUS_TO_LOAD but more restrictive than
1.188 + * URI_LOADABLE_BY_ANYONE. See the documentation for
1.189 + * nsIScriptSecurityManager::CheckLoadURI.
1.190 + */
1.191 + const unsigned long URI_IS_UI_RESOURCE = (1<<8);
1.192 +
1.193 + /**
1.194 + * Loading of URIs for this protocol from other origins should only be
1.195 + * allowed if those origins should have access to the local filesystem.
1.196 + * It's up to the application to decide what origins should have such
1.197 + * access. Protocols like "file" that point to local data should set this
1.198 + * flag.
1.199 + */
1.200 + const unsigned long URI_IS_LOCAL_FILE = (1<<9);
1.201 +
1.202 + /**
1.203 + * The URIs for this protocol can be loaded only by callers with a
1.204 + * principal that subsumes this uri. For example, privileged code and
1.205 + * websites that are same origin as this uri.
1.206 + */
1.207 + const unsigned long URI_LOADABLE_BY_SUBSUMERS = (1<<10);
1.208 +
1.209 + /**
1.210 + * Channels using this protocol never call OnDataAvailable
1.211 + * on the listener passed to AsyncOpen and they therefore
1.212 + * do not return any data that we can use.
1.213 + */
1.214 + const unsigned long URI_DOES_NOT_RETURN_DATA = (1<<11);
1.215 +
1.216 + /**
1.217 + * URIs for this protocol are considered to be local resources. This could
1.218 + * be a local file (URI_IS_LOCAL_FILE), a UI resource (URI_IS_UI_RESOURCE),
1.219 + * or something else that would not hit the network.
1.220 + */
1.221 + const unsigned long URI_IS_LOCAL_RESOURCE = (1<<12);
1.222 +
1.223 + /**
1.224 + * URIs for this protocol execute script when they are opened.
1.225 + */
1.226 + const unsigned long URI_OPENING_EXECUTES_SCRIPT = (1<<13);
1.227 +
1.228 + /**
1.229 + * Loading channels from this protocol has side-effects that make
1.230 + * it unsuitable for saving to a local file.
1.231 + */
1.232 + const unsigned long URI_NON_PERSISTABLE = (1<<14);
1.233 +
1.234 + /**
1.235 + * This protocol handler forbids accessing cookies e.g. for mail related
1.236 + * protocols.
1.237 + */
1.238 + const unsigned long URI_FORBIDS_COOKIE_ACCESS = (1<<15);
1.239 +
1.240 + /**
1.241 + * URIs for this protocol require the webapps permission on the principal
1.242 + * when opening URIs for a different domain. See bug#773886
1.243 + */
1.244 + const unsigned long URI_CROSS_ORIGIN_NEEDS_WEBAPPS_PERM = (1<<16);
1.245 +
1.246 + /**
1.247 + * Channels for this protocol don't need to spin the event loop to handle
1.248 + * Open() and reads on the resulting stream.
1.249 + */
1.250 + const unsigned long URI_SYNC_LOAD_IS_OK = (1<<17);
1.251 +
1.252 + /**
1.253 + * URI is secure to load in an https page and should not be blocked
1.254 + * by nsMixedContentBlocker
1.255 + */
1.256 + const unsigned long URI_SAFE_TO_LOAD_IN_SECURE_CONTEXT = (1<<18);
1.257 +
1.258 +
1.259 +};
1.260 +
1.261 +%{C++
1.262 +/**
1.263 + * Protocol handlers are registered with XPCOM under the following CONTRACTID prefix:
1.264 + */
1.265 +#define NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX "@mozilla.org/network/protocol;1?name="
1.266 +/**
1.267 + * For example, "@mozilla.org/network/protocol;1?name=http"
1.268 + */
1.269 +%}
