netwerk/base/nsIIOService.idl

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