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
interface nsIProtocolHandler;
9
interface nsIChannel;
10
interface nsIURI;
11
interface nsIFile;
12
interface nsIPrincipal;
13
interface nsILoadInfo;
14
15
webidl Node;
16
17
%{C++
18
#include "mozilla/Maybe.h"
19
20
namespace mozilla {
21
namespace dom {
22
class ClientInfo;
23
class ServiceWorkerDescriptor;
24
} // namespace dom
25
} // namespace mozilla
26
%}
27
28
[ref] native const_MaybeClientInfoRef(const mozilla::Maybe<mozilla::dom::ClientInfo>);
29
[ref] native const_MaybeServiceWorkerDescriptorRef(const mozilla::Maybe<mozilla::dom::ServiceWorkerDescriptor>);
30
31
/**
32
* nsIIOService provides a set of network utility functions. This interface
33
* duplicates many of the nsIProtocolHandler methods in a protocol handler
34
* independent way (e.g., NewURI inspects the scheme in order to delegate
35
* creation of the new URI to the appropriate protocol handler). nsIIOService
36
* also provides a set of URL parsing utility functions. These are provided
37
* as a convenience to the programmer and in some cases to improve performance
38
* by eliminating intermediate data structures and interfaces.
39
*/
40
[scriptable, builtinclass, uuid(4286de5a-b2ea-446f-8f70-e2a461f42694)]
41
interface nsIIOService : nsISupports
42
{
43
/**
44
* Returns a protocol handler for a given URI scheme.
45
*
46
* @param aScheme the URI scheme
47
* @return reference to corresponding nsIProtocolHandler
48
*/
49
nsIProtocolHandler getProtocolHandler(in string aScheme);
50
51
/**
52
* Returns the protocol flags for a given scheme.
53
*
54
* @param aScheme the URI scheme
55
* @return value of corresponding nsIProtocolHandler::protocolFlags
56
*/
57
unsigned long getProtocolFlags(in string aScheme);
58
59
/**
60
* This method constructs a new URI by determining the scheme of the
61
* URI spec, and then delegating the construction of the URI to the
62
* protocol handler for that scheme. QueryInterface can be used on
63
* the resulting URI object to obtain a more specific type of URI.
64
*
65
* @see nsIProtocolHandler::newURI
66
*/
67
nsIURI newURI(in AUTF8String aSpec,
68
[optional] in string aOriginCharset,
69
[optional] in nsIURI aBaseURI);
70
71
/**
72
* This method constructs a new URI from a nsIFile.
73
*
74
* @param aFile specifies the file path
75
* @return reference to a new nsIURI object
76
*
77
* Note: in the future, for perf reasons we should allow
78
* callers to specify whether this is a file or directory by
79
* splitting this into newDirURI() and newActualFileURI().
80
*/
81
nsIURI newFileURI(in nsIFile aFile);
82
83
/**
84
* Creates a channel for a given URI.
85
*
86
* @param aURI
87
* nsIURI from which to make a channel
88
* @param aLoadingNode
89
* @param aLoadingPrincipal
90
* @param aTriggeringPrincipal
91
* @param aSecurityFlags
92
* @param aContentPolicyType
93
* These will be used as values for the nsILoadInfo object on the
94
* created channel. For details, see nsILoadInfo in nsILoadInfo.idl
95
* @return reference to the new nsIChannel object
96
*
97
* Please note, if you provide both a loadingNode and a loadingPrincipal,
98
* then loadingPrincipal must be equal to loadingNode->NodePrincipal().
99
* But less error prone is to just supply a loadingNode.
100
*
101
* Keep in mind that URIs coming from a webpage should *never* use the
102
* systemPrincipal as the loadingPrincipal.
103
*/
104
nsIChannel newChannelFromURI(in nsIURI aURI,
105
in Node aLoadingNode,
106
in nsIPrincipal aLoadingPrincipal,
107
in nsIPrincipal aTriggeringPrincipal,
108
in unsigned long aSecurityFlags,
109
in unsigned long aContentPolicyType);
110
111
[noscript, nostdcall, notxpcom]
112
nsresult NewChannelFromURIWithClientAndController(in nsIURI aURI,
113
in Node aLoadingNode,
114
in nsIPrincipal aLoadingPrincipal,
115
in nsIPrincipal aTriggeringPrincipal,
116
in const_MaybeClientInfoRef aLoadingClientInfo,
117
in const_MaybeServiceWorkerDescriptorRef aController,
118
in unsigned long aSecurityFlags,
119
in unsigned long aContentPolicyType,
120
out nsIChannel aResult);
121
122
/**
123
* Equivalent to newChannelFromURI(aURI, aLoadingNode, ...)
124
*/
125
nsIChannel newChannelFromURIWithLoadInfo(in nsIURI aURI,
126
in nsILoadInfo aLoadInfo);
127
128
/**
129
* Equivalent to newChannelFromURI(newURI(...))
130
*/
131
nsIChannel newChannel(in AUTF8String aSpec,
132
in string aOriginCharset,
133
in nsIURI aBaseURI,
134
in Node aLoadingNode,
135
in nsIPrincipal aLoadingPrincipal,
136
in nsIPrincipal aTriggeringPrincipal,
137
in unsigned long aSecurityFlags,
138
in unsigned long aContentPolicyType);
139
140
/**
141
* Returns true if networking is in "offline" mode. When in offline mode,
142
* attempts to access the network will fail (although this does not
143
* necessarily correlate with whether there is actually a network
144
* available -- that's hard to detect without causing the dialer to
145
* come up).
146
*
147
* Changing this fires observer notifications ... see below.
148
*/
149
attribute boolean offline;
150
151
/**
152
* Returns false if there are no interfaces for a network request
153
*/
154
readonly attribute boolean connectivity;
155
156
/**
157
* Checks if a port number is banned. This involves consulting a list of
158
* unsafe ports, corresponding to network services that may be easily
159
* exploitable. If the given port is considered unsafe, then the protocol
160
* handler (corresponding to aScheme) will be asked whether it wishes to
161
* override the IO service's decision to block the port. This gives the
162
* protocol handler ultimate control over its own security policy while
163
* ensuring reasonable, default protection.
164
*
165
* @see nsIProtocolHandler::allowPort
166
*/
167
boolean allowPort(in long aPort, in string aScheme);
168
169
/**
170
* Utility to extract the scheme from a URL string, consistently and
171
* according to spec (see RFC 2396).
172
*
173
* NOTE: Most URL parsing is done via nsIURI, and in fact the scheme
174
* can also be extracted from a URL string via nsIURI. This method
175
* is provided purely as an optimization.
176
*
177
* @param aSpec the URL string to parse
178
* @return URL scheme, lowercase
179
*
180
* @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
181
*/
182
ACString extractScheme(in AUTF8String urlString);
183
184
/**
185
* Checks if a URI host is a local IPv4 or IPv6 address literal.
186
*
187
* @param nsIURI the URI that contains the hostname to check
188
* @return true if the URI hostname is a local IP address
189
*/
190
boolean hostnameIsLocalIPAddress(in nsIURI aURI);
191
192
/**
193
* Checks if a URI host is a shared IPv4 address literal.
194
*
195
* @param nsIURI the URI that contains the hostname to check
196
* @return true if the URI hostname is a shared IP address
197
*/
198
boolean hostnameIsSharedIPAddress(in nsIURI aURI);
199
200
/**
201
* While this is set, IOService will monitor an nsINetworkLinkService
202
* (if available) and set its offline status to "true" whenever
203
* isLinkUp is false.
204
*
205
* Applications that want to control changes to the IOService's offline
206
* status should set this to false, watch for network:link-status-changed
207
* broadcasts, and change nsIIOService::offline as they see fit. Note
208
* that this means during application startup, IOService may be offline
209
* if there is no link, until application code runs and can turn off
210
* this management.
211
*/
212
attribute boolean manageOfflineStatus;
213
214
/**
215
* Creates a channel for a given URI.
216
*
217
* @param aURI
218
* nsIURI from which to make a channel
219
* @param aProxyURI
220
* nsIURI to use for proxy resolution. Can be null in which
221
* case aURI is used
222
* @param aProxyFlags flags from nsIProtocolProxyService to use
223
* when resolving proxies for this new channel
224
* @param aLoadingNode
225
* @param aLoadingPrincipal
226
* @param aTriggeringPrincipal
227
* @param aSecurityFlags
228
* @param aContentPolicyType
229
* These will be used as values for the nsILoadInfo object on the
230
* created channel. For details, see nsILoadInfo in nsILoadInfo.idl
231
* @return reference to the new nsIChannel object
232
*
233
* Please note, if you provide both a loadingNode and a loadingPrincipal,
234
* then loadingPrincipal must be equal to loadingNode->NodePrincipal().
235
* But less error prone is to just supply a loadingNode.
236
*/
237
nsIChannel newChannelFromURIWithProxyFlags(in nsIURI aURI,
238
in nsIURI aProxyURI,
239
in unsigned long aProxyFlags,
240
in Node aLoadingNode,
241
in nsIPrincipal aLoadingPrincipal,
242
in nsIPrincipal aTriggeringPrincipal,
243
in unsigned long aSecurityFlags,
244
in unsigned long aContentPolicyType);
245
};
246
247
%{C++
248
/**
249
* We send notifications through nsIObserverService with topic
250
* NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
251
* when 'offline' has changed from false to true, and we are about
252
* to shut down network services such as DNS. When those
253
* services have been shut down, we send a notification with
254
* topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
255
* NS_IOSERVICE_OFFLINE.
256
*
257
* When 'offline' changes from true to false, then after
258
* network services have been restarted, we send a notification
259
* with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
260
* NS_IOSERVICE_ONLINE.
261
*/
262
#define NS_IOSERVICE_GOING_OFFLINE_TOPIC "network:offline-about-to-go-offline"
263
#define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
264
#define NS_IOSERVICE_OFFLINE "offline"
265
#define NS_IOSERVICE_ONLINE "online"
266
267
%}
268
269
[builtinclass, uuid(6633c0bf-d97a-428f-8ece-cb6a655fb95a)]
270
interface nsIIOServiceInternal : nsISupports
271
{
272
/**
273
* This is an internal method that should only be called from ContentChild
274
* in order to pass the connectivity state from the chrome process to the
275
* content process. It throws if called outside the content process.
276
*/
277
void SetConnectivity(in boolean connectivity);
278
279
/**
280
* An internal method to asynchronously run our notifications that happen
281
* when we wake from sleep
282
*/
283
void NotifyWakeup();
284
};