nsIIOService.idl (17051B)
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 #include "nsIContentPolicy.idl" 8 9 interface nsIProtocolHandler; 10 interface nsIChannel; 11 interface nsIURI; 12 interface nsIFile; 13 interface nsIPrincipal; 14 interface nsILoadInfo; 15 interface nsIWebTransport; 16 interface nsISuspendableChannelWrapper; 17 18 webidl Node; 19 20 %{C++ 21 #include "mozilla/Maybe.h" 22 23 namespace mozilla { 24 namespace dom { 25 class ClientInfo; 26 class ServiceWorkerDescriptor; 27 } // namespace dom 28 } // namespace mozilla 29 %} 30 31 [ref] native const_MaybeClientInfoRef(const mozilla::Maybe<mozilla::dom::ClientInfo>); 32 [ref] native const_MaybeServiceWorkerDescriptorRef(const mozilla::Maybe<mozilla::dom::ServiceWorkerDescriptor>); 33 34 /** 35 * nsIIOService provides a set of network utility functions. This interface 36 * duplicates many of the nsIProtocolHandler methods in a protocol handler 37 * independent way (e.g., NewURI inspects the scheme in order to delegate 38 * creation of the new URI to the appropriate protocol handler). nsIIOService 39 * also provides a set of URL parsing utility functions. These are provided 40 * as a convenience to the programmer and in some cases to improve performance 41 * by eliminating intermediate data structures and interfaces. 42 */ 43 [scriptable, builtinclass, uuid(4286de5a-b2ea-446f-8f70-e2a461f42694)] 44 interface nsIIOService : nsISupports 45 { 46 /** 47 * Returns a protocol handler for a given URI scheme. 48 * 49 * @param aScheme the URI scheme 50 * @return reference to corresponding nsIProtocolHandler 51 */ 52 nsIProtocolHandler getProtocolHandler(in string aScheme); 53 54 /** 55 * Returns the protocol flags for a given scheme. 56 * 57 * @param aScheme the URI scheme 58 * @return protocol flags for the corresponding protocol 59 */ 60 unsigned long getProtocolFlags(in string aScheme); 61 62 /** 63 * Returns the dynamic protocol flags for a given URI. 64 * 65 * @param aURI the URI to get all dynamic flags for 66 * @return protocol flags for that URI 67 */ 68 unsigned long getDynamicProtocolFlags(in nsIURI aURI); 69 70 /** 71 * Returns the default port for a given scheme. 72 * 73 * @param aScheme the URI scheme 74 * @return default port for the corresponding protocol 75 */ 76 long getDefaultPort(in string aScheme); 77 78 /** 79 * This method constructs a new URI based on the scheme of the URI spec. 80 * QueryInterface can be used on the resulting URI object to obtain a more 81 * specific type of URI. 82 */ 83 nsIURI newURI(in AUTF8String aSpec, 84 [optional] in string aOriginCharset, 85 [optional] in nsIURI aBaseURI); 86 87 /** 88 * This method constructs a new URI from a nsIFile. 89 * 90 * @param aFile specifies the file path 91 * @return reference to a new nsIURI object 92 * 93 * Note: in the future, for perf reasons we should allow 94 * callers to specify whether this is a file or directory by 95 * splitting this into newDirURI() and newActualFileURI(). 96 */ 97 nsIURI newFileURI(in nsIFile aFile); 98 99 /** 100 * Converts an internal URI (e.g. one that has a username and password in 101 * it) into one which we can expose to the user, for example on the URL bar. 102 * 103 * @param aURI The URI to be converted. 104 * @return nsIURI The converted, exposable URI. 105 */ 106 nsIURI createExposableURI(in nsIURI aURI); 107 108 /** 109 * Creates a channel for a given URI. 110 * 111 * @param aURI 112 * nsIURI from which to make a channel 113 * @param aLoadingNode 114 * @param aLoadingPrincipal 115 * @param aTriggeringPrincipal 116 * @param aSecurityFlags 117 * @param aContentPolicyType 118 * These will be used as values for the nsILoadInfo object on the 119 * created channel. For details, see nsILoadInfo in nsILoadInfo.idl 120 * @return reference to the new nsIChannel object 121 * 122 * Please note, if you provide both a loadingNode and a loadingPrincipal, 123 * then loadingPrincipal must be equal to loadingNode->NodePrincipal(). 124 * But less error prone is to just supply a loadingNode. 125 * 126 * Keep in mind that URIs coming from a webpage should *never* use the 127 * systemPrincipal as the loadingPrincipal. 128 */ 129 nsIChannel newChannelFromURI(in nsIURI aURI, 130 in Node aLoadingNode, 131 in nsIPrincipal aLoadingPrincipal, 132 in nsIPrincipal aTriggeringPrincipal, 133 in unsigned long aSecurityFlags, 134 in nsContentPolicyType aContentPolicyType); 135 136 [noscript, nostdcall, notxpcom] 137 nsresult NewChannelFromURIWithClientAndController(in nsIURI aURI, 138 in Node aLoadingNode, 139 in nsIPrincipal aLoadingPrincipal, 140 in nsIPrincipal aTriggeringPrincipal, 141 in const_MaybeClientInfoRef aLoadingClientInfo, 142 in const_MaybeServiceWorkerDescriptorRef aController, 143 in unsigned long aSecurityFlags, 144 in nsContentPolicyType aContentPolicyType, 145 in unsigned long aSandboxFlags, 146 out nsIChannel aResult); 147 148 /** 149 * Equivalent to newChannelFromURI(aURI, aLoadingNode, ...) 150 */ 151 nsIChannel newChannelFromURIWithLoadInfo(in nsIURI aURI, 152 in nsILoadInfo aLoadInfo); 153 154 /** 155 * Equivalent to newChannelFromURI(newURI(...)) 156 */ 157 nsIChannel newChannel(in AUTF8String aSpec, 158 in string aOriginCharset, 159 in nsIURI aBaseURI, 160 in Node aLoadingNode, 161 in nsIPrincipal aLoadingPrincipal, 162 in nsIPrincipal aTriggeringPrincipal, 163 in unsigned long aSecurityFlags, 164 in nsContentPolicyType aContentPolicyType); 165 166 /** 167 * Creates a channel that wraps an innerChannel. The 168 * nsISuspendableChannelWrapper can be suspended before asyncOpen is called 169 * on it. Beyond suspend(), resume() and asyncOpen(), all other calls are 170 * forwarded to the innerChannel. 171 */ 172 nsISuspendableChannelWrapper newSuspendableChannelWrapper(in nsIChannel innerChannel); 173 174 /** 175 * Creates a WebTransport. 176 */ 177 nsIWebTransport newWebTransport(); 178 179 180 /** 181 * Calls GetOriginAttributesForNetworkState 182 * see StoragePrincipalHelper.h 183 */ 184 [implicit_jscontext] 185 jsval originAttributesForNetworkState(in nsIChannel aChannel); 186 187 /** 188 * Returns true if networking is in "offline" mode. When in offline mode, 189 * attempts to access the network will fail (although this does not 190 * necessarily correlate with whether there is actually a network 191 * available -- that's hard to detect without causing the dialer to 192 * come up). 193 * 194 * Changing this fires observer notifications ... see below. 195 */ 196 attribute boolean offline; 197 198 /** 199 * Returns false if there are no interfaces for a network request 200 */ 201 readonly attribute boolean connectivity; 202 203 /** 204 * This is a method to set connectivity for testing purposes 205 */ 206 void setConnectivityForTesting(in boolean connectivity); 207 208 /** 209 * Checks if a port number is banned. This involves consulting a list of 210 * unsafe ports, corresponding to network services that may be easily 211 * exploitable. If the given port is considered unsafe, then the protocol 212 * handler (corresponding to aScheme) will be asked whether it wishes to 213 * override the IO service's decision to block the port. This gives the 214 * protocol handler ultimate control over its own security policy while 215 * ensuring reasonable, default protection. 216 * 217 * @see nsIProtocolHandler::allowPort 218 */ 219 boolean allowPort(in long aPort, in string aScheme); 220 221 /** 222 * Utility to extract the scheme from a URL string, consistently and 223 * according to spec (see RFC 2396). 224 * 225 * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme 226 * can also be extracted from a URL string via nsIURI. This method 227 * is provided purely as an optimization. 228 * 229 * @param aSpec the URL string to parse 230 * @return URL scheme, lowercase 231 * 232 * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form. 233 */ 234 ACString extractScheme(in AUTF8String urlString); 235 236 /** 237 * Checks if a URI host is a local IPv4 or IPv6 address literal. 238 * 239 * @param nsIURI the URI that contains the hostname to check 240 * @return true if the URI hostname is a local IP address 241 */ 242 boolean hostnameIsLocalIPAddress(in nsIURI aURI); 243 244 /** 245 * Checks if a URI host is a shared IPv4 address literal. 246 * 247 * @param nsIURI the URI that contains the hostname to check 248 * @return true if the URI hostname is a shared IP address 249 */ 250 boolean hostnameIsSharedIPAddress(in nsIURI aURI); 251 252 /* Checks if a URI host is a INADDR_ANY 253 * 254 * @param nsIURI the URI that contains the hostname to check 255 * @return true if the URI hostname is a INADDR_ANY 256 */ 257 boolean hostnameIsIPAddressAny(in nsIURI aURI); 258 259 260 /** 261 * Checks if characters not allowed in DNS are present in the hostname 262 * and if the hostname ends in a number it also checks if it's a valid 263 * IPv4 address. Any failure indicates that parsing this host will fail at a 264 * later point when using it in the URL parser. 265 * 266 * @param AUTF8String hostname is the hostname to validate 267 * @return true if the hostname is valid, else false 268 */ 269 boolean isValidHostname(in AUTF8String hostname); 270 271 /** 272 * While this is set, IOService will monitor an nsINetworkLinkService 273 * (if available) and set its offline status to "true" whenever 274 * isLinkUp is false. 275 * 276 * Applications that want to control changes to the IOService's offline 277 * status should set this to false, watch for network:link-status-changed 278 * broadcasts, and change nsIIOService::offline as they see fit. Note 279 * that this means during application startup, IOService may be offline 280 * if there is no link, until application code runs and can turn off 281 * this management. 282 */ 283 attribute boolean manageOfflineStatus; 284 285 /** 286 * Creates a channel for a given URI. 287 * 288 * @param aURI 289 * nsIURI from which to make a channel 290 * @param aProxyURI 291 * nsIURI to use for proxy resolution. Can be null in which 292 * case aURI is used 293 * @param aProxyFlags flags from nsIProtocolProxyService to use 294 * when resolving proxies for this new channel 295 * @param aLoadingNode 296 * @param aLoadingPrincipal 297 * @param aTriggeringPrincipal 298 * @param aSecurityFlags 299 * @param aContentPolicyType 300 * These will be used as values for the nsILoadInfo object on the 301 * created channel. For details, see nsILoadInfo in nsILoadInfo.idl 302 * @return reference to the new nsIChannel object 303 * 304 * Please note, if you provide both a loadingNode and a loadingPrincipal, 305 * then loadingPrincipal must be equal to loadingNode->NodePrincipal(). 306 * But less error prone is to just supply a loadingNode. 307 */ 308 nsIChannel newChannelFromURIWithProxyFlags(in nsIURI aURI, 309 in nsIURI aProxyURI, 310 in unsigned long aProxyFlags, 311 in Node aLoadingNode, 312 in nsIPrincipal aLoadingPrincipal, 313 in nsIPrincipal aTriggeringPrincipal, 314 in unsigned long aSecurityFlags, 315 in nsContentPolicyType aContentPolicyType); 316 317 /** 318 * Return true if socket process is launched. 319 */ 320 readonly attribute boolean socketProcessLaunched; 321 322 /** 323 * The pid for socket process. 324 */ 325 readonly attribute unsigned long long socketProcessId; 326 327 /** 328 * Register a protocol handler at runtime, given protocol flags and a 329 * default port. 330 * 331 * Statically registered protocol handlers cannot be overridden, and an 332 * error will be returned if that is attempted. 333 * 334 * Runtime registered protocol handlers are never QueryInterface-ed into 335 * `nsIProtocolHandlerWithDynamicFlags`, so that interface will be ignored. 336 * 337 * @param aScheme the scheme handled by the protocol handler. 338 * @param aHandler the protocol handler instance. 339 * @param aProtocolFlags protocol flags for this protocol, see 340 * nsIProtocolHandler for values. 341 * @param aDefaultPort default port for this scheme, or -1. 342 */ 343 void registerProtocolHandler(in ACString aScheme, 344 in nsIProtocolHandler aHandler, 345 in unsigned long aProtocolFlags, 346 in long aDefaultPort); 347 348 /** 349 * Unregister a protocol handler which was previously registered using 350 * registerProtocolHandler. 351 * 352 * @param aScheme the scheme to unregister a handler for. 353 */ 354 void unregisterProtocolHandler(in ACString aScheme); 355 356 /** 357 * Updates the RemoteSettings-specified portion of the defaultURI bypass 358 * scheme list. The list is then merged with the user-specified pref list 359 * before broadcasting to all alive content processes that may need for URL 360 * parsing. 361 */ 362 void setSimpleURIUnknownRemoteSchemes(in Array<ACString> aRemoteSchemes); 363 364 /** 365 * Checks if the provided scheme is in the list of unknown schemes that 366 * should use simpleURI as it's default parser. Where "unknown" scheme means 367 * non-special and otherwise non-common shemes like: 368 * http, about, jar, blob, ssh, etc 369 * See netwerk/base/nsNetUtil.cpp::NS_NewURI for the full list 370 */ 371 [noscript] boolean isSimpleURIUnknownScheme(in ACString aScheme); 372 373 /** 374 * returns an array of the remote-settings specified unknown schemes that 375 * should use SimpleURI parser instead of defaultURI parser. 376 */ 377 [noscript] Array<ACString> getSimpleURIUnknownRemoteSchemes(); 378 379 /** 380 * When a failure is encountered connecting to an essential domain 381 * with a system-principal channel, we may attempt to retry the load 382 * with a fallback domain. 383 */ 384 void addEssentialDomainMapping(in ACString aFrom, in ACString aTo); 385 386 /** 387 * Clears the essential domain mapping. 388 */ 389 void clearEssentialDomainMapping(); 390 391 /** 392 * Runs a string through the CacheControlParser and attempts to extract 393 * and return relevant parsed values. The structure that is returned is 394 * a HTTPCacheControlParseResult dictionary (see ChromeUtils.webidl). 395 */ 396 [implicit_jscontext] 397 jsval parseCacheControlHeader(in ACString aCacheControlHeader); 398 }; 399 400 %{C++ 401 /** 402 * We send notifications through nsIObserverService with topic 403 * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE 404 * when 'offline' has changed from false to true, and we are about 405 * to shut down network services such as DNS. When those 406 * services have been shut down, we send a notification with 407 * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data 408 * NS_IOSERVICE_OFFLINE. 409 * 410 * When 'offline' changes from true to false, then after 411 * network services have been restarted, we send a notification 412 * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data 413 * NS_IOSERVICE_ONLINE. 414 */ 415 #define NS_IOSERVICE_GOING_OFFLINE_TOPIC "network:offline-about-to-go-offline" 416 #define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed" 417 #define NS_IOSERVICE_OFFLINE "offline" 418 #define NS_IOSERVICE_ONLINE "online" 419 420 %} 421 422 [uuid(6633c0bf-d97a-428f-8ece-cb6a655fb95a)] 423 interface nsIIOServiceInternal : nsISupports 424 { 425 /** 426 * This is an internal method that should only be called from ContentChild 427 * in order to pass the connectivity state from the chrome process to the 428 * content process. It throws if called outside the content process. 429 */ 430 void SetConnectivity(in boolean connectivity); 431 432 /** 433 * An internal method to asynchronously run our notifications that happen 434 * when we wake from sleep 435 */ 436 void NotifyWakeup(); 437 };