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                                                       in boolean aSkipCheckForBrokenURLOrZeroSized,
 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 WebTransport.
 168      */
 169     nsIWebTransport newWebTransport();
 170
 171     /**
 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
 176      * come up).
 177      *
 178      * Changing this fires observer notifications ... see below.
 179      */
 180     attribute boolean offline;
 181
 182     /**
 183      * Returns false if there are no interfaces for a network request
 184      */
 185     readonly attribute boolean connectivity;
 186
 187     /**
 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.
 195      *
 196      * @see nsIProtocolHandler::allowPort
 197      */
 198     boolean allowPort(in long aPort, in string aScheme);
 199
 200     /**
 201      * Utility to extract the scheme from a URL string, consistently and
 202      * according to spec (see RFC 2396).
 203      *
 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.
 207      *
 208      * @param aSpec the URL string to parse
 209      * @return URL scheme, lowercase
 210      *
 211      * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
 212      */
 213     ACString extractScheme(in AUTF8String urlString);
 214
 215     /**
 216      * Checks if a URI host is a local IPv4 or IPv6 address literal.
 217      *
 218      * @param nsIURI the URI that contains the hostname to check
 219      * @return true if the URI hostname is a local IP address
 220      */
 221     boolean hostnameIsLocalIPAddress(in nsIURI aURI);
 222
 223     /**
 224      * Checks if a URI host is a shared IPv4 address literal.
 225      *
 226      * @param nsIURI the URI that contains the hostname to check
 227      * @return true if the URI hostname is a shared IP address
 228      */
 229     boolean hostnameIsSharedIPAddress(in nsIURI aURI);
 230
 231     /**
 232      * Checks if a hostname is valid.
 233      *
 234      * @param AUTF8String hostname is the hostname to validate
 235      * @return true if the hostname is valid, else false
 236      */
 237     boolean isValidHostname(in AUTF8String hostname);
 238
 239     /**
 240      * While this is set, IOService will monitor an nsINetworkLinkService
 241      * (if available) and set its offline status to "true" whenever
 242      * isLinkUp is false.
 243      *
 244      * Applications that want to control changes to the IOService's offline
 245      * status should set this to false, watch for network:link-status-changed
 246      * broadcasts, and change nsIIOService::offline as they see fit. Note
 247      * that this means during application startup, IOService may be offline
 248      * if there is no link, until application code runs and can turn off
 249      * this management.
 250      */
 251     attribute boolean manageOfflineStatus;
 252
 253     /**
 254      * Creates a channel for a given URI.
 255      *
 256      * @param aURI
 257      *        nsIURI from which to make a channel
 258      * @param aProxyURI
 259      *        nsIURI to use for proxy resolution. Can be null in which
 260      *        case aURI is used
 261      * @param aProxyFlags flags from nsIProtocolProxyService to use
 262      *        when resolving proxies for this new channel
 263      * @param aLoadingNode
 264      * @param aLoadingPrincipal
 265      * @param aTriggeringPrincipal
 266      * @param aSecurityFlags
 267      * @param aContentPolicyType
 268      *        These will be used as values for the nsILoadInfo object on the
 269      *        created channel. For details, see nsILoadInfo in nsILoadInfo.idl
 270      * @return reference to the new nsIChannel object
 271      *
 272      * Please note, if you provide both a loadingNode and a loadingPrincipal,
 273      * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
 274      * But less error prone is to just supply a loadingNode.
 275      */
 276     nsIChannel newChannelFromURIWithProxyFlags(in nsIURI aURI,
 277                                                in nsIURI aProxyURI,
 278                                                in unsigned long aProxyFlags,
 279                                                in Node aLoadingNode,
 280                                                in nsIPrincipal aLoadingPrincipal,
 281                                                in nsIPrincipal aTriggeringPrincipal,
 282                                                in unsigned long aSecurityFlags,
 283                                                in nsContentPolicyType aContentPolicyType);
 284
 285     /**
 286      * Return true if socket process is launched.
 287      */
 288     readonly attribute boolean socketProcessLaunched;
 289
 290     /**
 291      * The pid for socket process.
 292      */
 293     readonly attribute unsigned long long socketProcessId;
 294
 295     /**
 296      * Register a protocol handler at runtime, given protocol flags and a
 297      * default port.
 298      *
 299      * Statically registered protocol handlers cannot be overridden, and an
 300      * error will be returned if that is attempted.
 301      *
 302      * Runtime registered protocol handlers are never QueryInterface-ed into
 303      * `nsIProtocolHandlerWithDynamicFlags`, so that interface will be ignored.
 304      *
 305      * @param aScheme the scheme handled by the protocol handler.
 306      * @param aHandler the protocol handler instance.
 307      * @param aProtocolFlags protocol flags for this protocol, see
 308      *                       nsIProtocolHandler for values.
 309      * @param aDefaultPort default port for this scheme, or -1.
 310      */
 311     void registerProtocolHandler(in ACString aScheme,
 312                                  in nsIProtocolHandler aHandler,
 313                                  in unsigned long aProtocolFlags,
 314                                  in long aDefaultPort);
 315
 316     /**
 317      * Unregister a protocol handler which was previously registered using
 318      * registerProtocolHandler.
 319      *
 320      * @param aScheme the scheme to unregister a handler for.
 321      */
 322     void unregisterProtocolHandler(in ACString aScheme);
 323 };
 324
 325 %{C++
 326 /**
 327  * We send notifications through nsIObserverService with topic
 328  * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
 329  * when 'offline' has changed from false to true, and we are about
 330  * to shut down network services such as DNS. When those
 331  * services have been shut down, we send a notification with
 332  * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
 333  * NS_IOSERVICE_OFFLINE.
 334  *
 335  * When 'offline' changes from true to false, then after
 336  * network services have been restarted, we send a notification
 337  * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
 338  * NS_IOSERVICE_ONLINE.
 339  */
 340 #define NS_IOSERVICE_GOING_OFFLINE_TOPIC  "network:offline-about-to-go-offline"
 341 #define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
 342 #define NS_IOSERVICE_OFFLINE              "offline"
 343 #define NS_IOSERVICE_ONLINE               "online"
 344
 345 %}
 346
 347 [uuid(6633c0bf-d97a-428f-8ece-cb6a655fb95a)]
 348 interface nsIIOServiceInternal : nsISupports
 349 {
 350     /**
 351      * This is an internal method that should only be called from ContentChild
 352      * in order to pass the connectivity state from the chrome process to the
 353      * content process. It throws if called outside the content process.
 354      */
 355     void SetConnectivity(in boolean connectivity);
 356
 357     /**
 358      * An internal method to asynchronously run our notifications that happen
 359      * when we wake from sleep
 360      */
 361     void NotifyWakeup();
 362 };