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/. */
6 #include
"nsISupports.idl"
7 #include
"nsIContentPolicy.idl"
9 interface nsIProtocolHandler
;
13 interface nsIPrincipal
;
14 interface nsILoadInfo
;
15 interface nsIWebTransport
;
20 #include
"mozilla/Maybe.h"
25 class ServiceWorkerDescriptor
;
27 } // namespace mozilla
30 [ref] native const_MaybeClientInfoRef
(const mozilla
::Maybe<mozilla
::dom
::ClientInfo
>);
31 [ref] native const_MaybeServiceWorkerDescriptorRef
(const mozilla
::Maybe<mozilla
::dom
::ServiceWorkerDescriptor
>);
34 * nsIIOService provides a set of network utility functions. This interface
35 * duplicates many of the nsIProtocolHandler methods in a protocol handler
36 * independent way (e.g., NewURI inspects the scheme in order to delegate
37 * creation of the new URI to the appropriate protocol handler). nsIIOService
38 * also provides a set of URL parsing utility functions. These are provided
39 * as a convenience to the programmer and in some cases to improve performance
40 * by eliminating intermediate data structures and interfaces.
42 [scriptable
, builtinclass
, uuid(4286de5a
-b2ea
-446f
-8f70
-e2a461f42694
)]
43 interface nsIIOService
: nsISupports
46 * Returns a protocol handler for a given URI scheme.
48 * @param aScheme the URI scheme
49 * @return reference to corresponding nsIProtocolHandler
51 nsIProtocolHandler getProtocolHandler
(in string aScheme
);
54 * Returns the protocol flags for a given scheme.
56 * @param aScheme the URI scheme
57 * @return protocol flags for the corresponding protocol
59 unsigned long getProtocolFlags
(in string aScheme
);
62 * Returns the dynamic protocol flags for a given URI.
64 * @param aURI the URI to get all dynamic flags for
65 * @return protocol flags for that URI
67 unsigned long getDynamicProtocolFlags
(in nsIURI aURI
);
70 * Returns the default port for a given scheme.
72 * @param aScheme the URI scheme
73 * @return default port for the corresponding protocol
75 long getDefaultPort
(in string aScheme
);
78 * This method constructs a new URI based on the scheme of the URI spec.
79 * QueryInterface can be used on the resulting URI object to obtain a more
80 * specific type of URI.
82 nsIURI newURI
(in AUTF8String aSpec
,
83 [optional] in string aOriginCharset
,
84 [optional] in nsIURI aBaseURI
);
87 * This method constructs a new URI from a nsIFile.
89 * @param aFile specifies the file path
90 * @return reference to a new nsIURI object
92 * Note: in the future, for perf reasons we should allow
93 * callers to specify whether this is a file or directory by
94 * splitting this into newDirURI() and newActualFileURI().
96 nsIURI newFileURI
(in nsIFile aFile
);
99 * Converts an internal URI (e.g. one that has a username and password in
100 * it) into one which we can expose to the user, for example on the URL bar.
102 * @param aURI The URI to be converted.
103 * @return nsIURI The converted, exposable URI.
105 nsIURI createExposableURI
(in nsIURI aURI
);
108 * Creates a channel for a given URI.
111 * nsIURI from which to make a channel
112 * @param aLoadingNode
113 * @param aLoadingPrincipal
114 * @param aTriggeringPrincipal
115 * @param aSecurityFlags
116 * @param aContentPolicyType
117 * These will be used as values for the nsILoadInfo object on the
118 * created channel. For details, see nsILoadInfo in nsILoadInfo.idl
119 * @return reference to the new nsIChannel object
121 * Please note, if you provide both a loadingNode and a loadingPrincipal,
122 * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
123 * But less error prone is to just supply a loadingNode.
125 * Keep in mind that URIs coming from a webpage should *never* use the
126 * systemPrincipal as the loadingPrincipal.
128 nsIChannel newChannelFromURI
(in nsIURI aURI
,
129 in Node aLoadingNode
,
130 in nsIPrincipal aLoadingPrincipal
,
131 in nsIPrincipal aTriggeringPrincipal
,
132 in unsigned long aSecurityFlags
,
133 in nsContentPolicyType aContentPolicyType
);
135 [noscript
, nostdcall
, notxpcom
]
136 nsresult NewChannelFromURIWithClientAndController
(in nsIURI aURI
,
137 in Node aLoadingNode
,
138 in nsIPrincipal aLoadingPrincipal
,
139 in nsIPrincipal aTriggeringPrincipal
,
140 in const_MaybeClientInfoRef aLoadingClientInfo
,
141 in const_MaybeServiceWorkerDescriptorRef aController
,
142 in unsigned long aSecurityFlags
,
143 in nsContentPolicyType aContentPolicyType
,
144 in unsigned long aSandboxFlags
,
145 in boolean aSkipCheckForBrokenURLOrZeroSized
,
146 out nsIChannel aResult
);
149 * Equivalent to newChannelFromURI(aURI, aLoadingNode, ...)
151 nsIChannel newChannelFromURIWithLoadInfo
(in nsIURI aURI
,
152 in nsILoadInfo aLoadInfo
);
155 * Equivalent to newChannelFromURI(newURI(...))
157 nsIChannel newChannel
(in AUTF8String aSpec
,
158 in string aOriginCharset
,
160 in Node aLoadingNode
,
161 in nsIPrincipal aLoadingPrincipal
,
162 in nsIPrincipal aTriggeringPrincipal
,
163 in unsigned long aSecurityFlags
,
164 in nsContentPolicyType aContentPolicyType
);
167 * Creates a WebTransport.
169 nsIWebTransport newWebTransport
();
172 * Returns true if networking is in "offline" mode. When in offline mode,
173 * attempts to access the network will fail (although this does not
174 * necessarily correlate with whether there is actually a network
175 * available -- that's hard to detect without causing the dialer to
178 * Changing this fires observer notifications ... see below.
180 attribute
boolean offline
;
183 * Returns false if there are no interfaces for a network request
185 readonly attribute
boolean connectivity
;
188 * Checks if a port number is banned. This involves consulting a list of
189 * unsafe ports, corresponding to network services that may be easily
190 * exploitable. If the given port is considered unsafe, then the protocol
191 * handler (corresponding to aScheme) will be asked whether it wishes to
192 * override the IO service's decision to block the port. This gives the
193 * protocol handler ultimate control over its own security policy while
194 * ensuring reasonable, default protection.
196 * @see nsIProtocolHandler::allowPort
198 boolean allowPort
(in long aPort
, in string aScheme
);
201 * Utility to extract the scheme from a URL string, consistently and
202 * according to spec (see RFC 2396).
204 * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme
205 * can also be extracted from a URL string via nsIURI. This method
206 * is provided purely as an optimization.
208 * @param aSpec the URL string to parse
209 * @return URL scheme, lowercase
211 * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
213 ACString extractScheme
(in AUTF8String urlString
);
216 * Checks if a URI host is a local IPv4 or IPv6 address literal.
218 * @param nsIURI the URI that contains the hostname to check
219 * @return true if the URI hostname is a local IP address
221 boolean hostnameIsLocalIPAddress
(in nsIURI aURI
);
224 * Checks if a URI host is a shared IPv4 address literal.
226 * @param nsIURI the URI that contains the hostname to check
227 * @return true if the URI hostname is a shared IP address
229 boolean hostnameIsSharedIPAddress
(in nsIURI aURI
);
232 * While this is set, IOService will monitor an nsINetworkLinkService
233 * (if available) and set its offline status to "true" whenever
236 * Applications that want to control changes to the IOService's offline
237 * status should set this to false, watch for network:link-status-changed
238 * broadcasts, and change nsIIOService::offline as they see fit. Note
239 * that this means during application startup, IOService may be offline
240 * if there is no link, until application code runs and can turn off
243 attribute
boolean manageOfflineStatus
;
246 * Creates a channel for a given URI.
249 * nsIURI from which to make a channel
251 * nsIURI to use for proxy resolution. Can be null in which
253 * @param aProxyFlags flags from nsIProtocolProxyService to use
254 * when resolving proxies for this new channel
255 * @param aLoadingNode
256 * @param aLoadingPrincipal
257 * @param aTriggeringPrincipal
258 * @param aSecurityFlags
259 * @param aContentPolicyType
260 * These will be used as values for the nsILoadInfo object on the
261 * created channel. For details, see nsILoadInfo in nsILoadInfo.idl
262 * @return reference to the new nsIChannel object
264 * Please note, if you provide both a loadingNode and a loadingPrincipal,
265 * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
266 * But less error prone is to just supply a loadingNode.
268 nsIChannel newChannelFromURIWithProxyFlags
(in nsIURI aURI
,
270 in unsigned long aProxyFlags
,
271 in Node aLoadingNode
,
272 in nsIPrincipal aLoadingPrincipal
,
273 in nsIPrincipal aTriggeringPrincipal
,
274 in unsigned long aSecurityFlags
,
275 in nsContentPolicyType aContentPolicyType
);
278 * Return true if socket process is launched.
280 readonly attribute
boolean socketProcessLaunched
;
283 * The pid for socket process.
285 readonly attribute
unsigned long long socketProcessId
;
288 * Register a protocol handler at runtime, given protocol flags and a
291 * Statically registered protocol handlers cannot be overridden, and an
292 * error will be returned if that is attempted.
294 * Runtime registered protocol handlers are never QueryInterface-ed into
295 * `nsIProtocolHandlerWithDynamicFlags`, so that interface will be ignored.
297 * @param aScheme the scheme handled by the protocol handler.
298 * @param aHandler the protocol handler instance.
299 * @param aProtocolFlags protocol flags for this protocol, see
300 * nsIProtocolHandler for values.
301 * @param aDefaultPort default port for this scheme, or -1.
303 void registerProtocolHandler
(in ACString aScheme
,
304 in nsIProtocolHandler aHandler
,
305 in unsigned long aProtocolFlags
,
306 in long aDefaultPort
);
309 * Unregister a protocol handler which was previously registered using
310 * registerProtocolHandler.
312 * @param aScheme the scheme to unregister a handler for.
314 void unregisterProtocolHandler
(in ACString aScheme
);
319 * We send notifications through nsIObserverService with topic
320 * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
321 * when 'offline' has changed from false to true, and we are about
322 * to shut down network services such as DNS. When those
323 * services have been shut down, we send a notification with
324 * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
325 * NS_IOSERVICE_OFFLINE.
327 * When 'offline' changes from true to false, then after
328 * network services have been restarted, we send a notification
329 * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
330 * NS_IOSERVICE_ONLINE.
332 #define NS_IOSERVICE_GOING_OFFLINE_TOPIC
"network:offline-about-to-go-offline"
333 #define NS_IOSERVICE_OFFLINE_STATUS_TOPIC
"network:offline-status-changed"
334 #define NS_IOSERVICE_OFFLINE
"offline"
335 #define NS_IOSERVICE_ONLINE
"online"
339 [uuid(6633c0bf
-d97a
-428f
-8ece
-cb6a655fb95a
)]
340 interface nsIIOServiceInternal
: nsISupports
343 * This is an internal method that should only be called from ContentChild
344 * in order to pass the connectivity state from the chrome process to the
345 * content process. It throws if called outside the content process.
347 void SetConnectivity
(in boolean connectivity
);
350 * An internal method to asynchronously run our notifications that happen
351 * when we wake from sleep