Source code

Revision control

Other Tools

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
* Constructs a new channel from the given URI for this protocol handler and
85
* sets the loadInfo for the constructed channel.
86
*/
87
nsIChannel newChannel(in nsIURI aURI, in nsILoadInfo aLoadinfo);
88
89
/**
90
* Allows a protocol to override blacklisted ports.
91
*
92
* This method will be called when there is an attempt to connect to a port
93
* that is blacklisted. For example, for most protocols, port 25 (Simple Mail
94
* Transfer) is banned. When a URI containing this "known-to-do-bad-things"
95
* port number is encountered, this function will be called to ask if the
96
* protocol handler wants to override the ban.
97
*/
98
boolean allowPort(in long port, in string scheme);
99
100
101
/**************************************************************************
102
* Constants for the protocol flags (the first is the default mask, the
103
* others are deviations):
104
*
105
* NOTE: Implementation must ignore any flags they do not understand.
106
*/
107
108
/**
109
* standard full URI with authority component and concept of relative
110
* URIs (http, ftp, ...)
111
*/
112
const unsigned long URI_STD = 0;
113
114
/**
115
* no concept of relative URIs (about, javascript, finger, ...)
116
*/
117
const unsigned long URI_NORELATIVE = (1<<0);
118
119
/**
120
* no authority component (file, ...)
121
*/
122
const unsigned long URI_NOAUTH = (1<<1);
123
124
/**
125
* This protocol handler can be proxied via a proxy (socks or http)
126
* (e.g., irc, smtp, http, etc.). If the protocol supports transparent
127
* proxying, the handler should implement nsIProxiedProtocolHandler.
128
*
129
* If it supports only HTTP proxying, then it need not support
130
* nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP
131
* flag (see below).
132
*
133
* @see nsIProxiedProtocolHandler
134
*/
135
const unsigned long ALLOWS_PROXY = (1<<2);
136
137
/**
138
* This protocol handler can be proxied using a http proxy (e.g., http,
139
* ftp, etc.). nsIIOService::newChannelFromURI will feed URIs from this
140
* protocol handler to the HTTP protocol handler instead. This flag is
141
* ignored if ALLOWS_PROXY is not set.
142
*/
143
const unsigned long ALLOWS_PROXY_HTTP = (1<<3);
144
145
/**
146
* The URIs for this protocol have no inherent security context, so
147
* documents loaded via this protocol should inherit the security context
148
* from the document that loads them.
149
*/
150
const unsigned long URI_INHERITS_SECURITY_CONTEXT = (1<<4);
151
152
/**
153
* "Automatic" loads that would replace the document (e.g. <meta> refresh,
154
* certain types of XLinks, possibly other loads that the application
155
* decides are not user triggered) are not allowed if the originating (NOT
156
* the target) URI has this protocol flag. Note that the decision as to
157
* what constitutes an "automatic" load is made externally, by the caller
158
* of nsIScriptSecurityManager::CheckLoadURI. See documentation for that
159
* method for more information.
160
*
161
* A typical protocol that might want to set this flag is a protocol that
162
* shows highly untrusted content in a viewing area that the user expects
163
* to have a lot of control over, such as an e-mail reader.
164
*/
165
const unsigned long URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT = (1<<5);
166
167
/**
168
* +-------------------------------------------------------------------+
169
* | |
170
* | ALL PROTOCOL HANDLERS MUST SET ONE OF THE FOLLOWING FIVE FLAGS. |
171
* | |
172
* +-------------------------------------------------------------------+
173
*
174
* These flags are used to determine who is allowed to load URIs for this
175
* protocol. Note that if a URI is nested, only the flags for the
176
* innermost URI matter. See nsINestedURI.
177
*
178
* If none of these five flags are set, the URI must be treated as if it
179
* had the URI_LOADABLE_BY_ANYONE flag set, for compatibility with protocol
180
* handlers written against Gecko 1.8 or earlier. In this case, there may
181
* be run-time warning messages indicating that a "default insecure"
182
* assumption is being made. At some point in the futures (Mozilla 2.0,
183
* most likely), these warnings will become errors.
184
*/
185
186
/**
187
* The URIs for this protocol can be loaded by anyone. For example, any
188
* website should be allowed to trigger a load of a URI for this protocol.
189
* Web-safe protocols like "http" should set this flag.
190
*/
191
const unsigned long URI_LOADABLE_BY_ANYONE = (1<<6);
192
193
/**
194
* The URIs for this protocol are UNSAFE if loaded by untrusted (web)
195
* content and may only be loaded by privileged code (for example, code
196
* which has the system principal). Various internal protocols should set
197
* this flag.
198
*/
199
const unsigned long URI_DANGEROUS_TO_LOAD = (1<<7);
200
201
/**
202
* The URIs for this protocol point to resources that are part of the
203
* application's user interface. There are cases when such resources may
204
* be made accessible to untrusted content such as web pages, so this is
205
* less restrictive than URI_DANGEROUS_TO_LOAD but more restrictive than
206
* URI_LOADABLE_BY_ANYONE. See the documentation for
207
* nsIScriptSecurityManager::CheckLoadURI.
208
*/
209
const unsigned long URI_IS_UI_RESOURCE = (1<<8);
210
211
/**
212
* Loading of URIs for this protocol from other origins should only be
213
* allowed if those origins should have access to the local filesystem.
214
* It's up to the application to decide what origins should have such
215
* access. Protocols like "file" that point to local data should set this
216
* flag.
217
*/
218
const unsigned long URI_IS_LOCAL_FILE = (1<<9);
219
220
/**
221
* The URIs for this protocol can be loaded only by callers with a
222
* principal that subsumes this uri. For example, privileged code and
223
* websites that are same origin as this uri.
224
*/
225
const unsigned long URI_LOADABLE_BY_SUBSUMERS = (1<<10);
226
227
/**
228
* Channels using this protocol never call OnDataAvailable
229
* on the listener passed to AsyncOpen and they therefore
230
* do not return any data that we can use.
231
*/
232
const unsigned long URI_DOES_NOT_RETURN_DATA = (1<<11);
233
234
/**
235
* URIs for this protocol are considered to be local resources. This could
236
* be a local file (URI_IS_LOCAL_FILE), a UI resource (URI_IS_UI_RESOURCE),
237
* or something else that would not hit the network.
238
*/
239
const unsigned long URI_IS_LOCAL_RESOURCE = (1<<12);
240
241
/**
242
* URIs for this protocol execute script when they are opened.
243
*/
244
const unsigned long URI_OPENING_EXECUTES_SCRIPT = (1<<13);
245
246
/**
247
* Loading channels from this protocol has side-effects that make
248
* it unsuitable for saving to a local file.
249
*/
250
const unsigned long URI_NON_PERSISTABLE = (1<<14);
251
252
/**
253
* URIs for this protocol require the webapps permission on the principal
254
* when opening URIs for a different domain. See bug#773886
255
*/
256
const unsigned long URI_CROSS_ORIGIN_NEEDS_WEBAPPS_PERM = (1<<15);
257
258
/**
259
* Channels for this protocol don't need to spin the event loop to handle
260
* Open() and reads on the resulting stream.
261
*/
262
const unsigned long URI_SYNC_LOAD_IS_OK = (1<<16);
263
264
/**
265
* All the origins whose URI has this scheme are considered potentially
266
* trustworthy.
267
* Per the SecureContext spec, https: and wss: should be considered
268
* a priori secure, and implementations may consider other,
269
* implementation-specific URI schemes as secure.
270
*/
271
const unsigned long URI_IS_POTENTIALLY_TRUSTWORTHY = (1<<17);
272
273
/**
274
* This URI may be fetched and the contents are visible to anyone. This is
275
* semantically equivalent to the resource being served with all-access CORS
276
* headers.
277
*/
278
const unsigned long URI_FETCHABLE_BY_ANYONE = (1 << 18);
279
280
/**
281
* If this flag is set, then the origin for this protocol is the full URI
282
* spec, not just the scheme + host + port.
283
*
284
* Note: this is not supported in Firefox. It is currently only available
285
* in Thunderbird and SeaMonkey.
286
*/
287
const unsigned long ORIGIN_IS_FULL_SPEC = (1 << 19);
288
289
/**
290
* If this flag is set, the URI does not always allow content using the same
291
* protocol to link to it.
292
*/
293
const unsigned long URI_SCHEME_NOT_SELF_LINKABLE = (1 << 20);
294
295
/**
296
* The URIs for this protocol can be loaded by extensions.
297
*/
298
const unsigned long URI_LOADABLE_BY_EXTENSIONS = (1 << 21);
299
300
/**
301
* The URIs for this protocol can not be loaded into private contexts.
302
*/
303
const unsigned long URI_DISALLOW_IN_PRIVATE_CONTEXT = (1 << 22);
304
305
/**
306
* This protocol handler forbids accessing cookies e.g. for mail related
307
* protocols. Only used in Mailnews (comm-central).
308
*/
309
const unsigned long URI_FORBIDS_COOKIE_ACCESS = (1 << 23);
310
};