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
   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, 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 newChannelFromURI2(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 newChannelFromURI2(aURI, aLoadingNode, ...)
 124      */
 125     nsIChannel newChannelFromURIWithLoadInfo(in nsIURI aURI,
 126                                              in nsILoadInfo aLoadInfo);
 127
 128     /**
 129      * Equivalent to newChannelFromURI2(newURI(...))
 130      */
 131     nsIChannel newChannel2(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      * While this is set, IOService will monitor an nsINetworkLinkService
 194      * (if available) and set its offline status to "true" whenever
 195      * isLinkUp is false.
 196      *
 197      * Applications that want to control changes to the IOService's offline
 198      * status should set this to false, watch for network:link-status-changed
 199      * broadcasts, and change nsIIOService::offline as they see fit. Note
 200      * that this means during application startup, IOService may be offline
 201      * if there is no link, until application code runs and can turn off
 202      * this management.
 203      */
 204     attribute boolean manageOfflineStatus;
 205
 206     /**
 207      * Creates a channel for a given URI.
 208      *
 209      * @param aURI
 210      *        nsIURI from which to make a channel
 211      * @param aProxyURI
 212      *        nsIURI to use for proxy resolution. Can be null in which
 213      *        case aURI is used
 214      * @param aProxyFlags flags from nsIProtocolProxyService to use
 215      *        when resolving proxies for this new channel
 216      * @param aLoadingNode
 217      * @param aLoadingPrincipal
 218      * @param aTriggeringPrincipal
 219      * @param aSecurityFlags
 220      * @param aContentPolicyType
 221      *        These will be used as values for the nsILoadInfo object on the
 222      *        created channel. For details, see nsILoadInfo in nsILoadInfo.idl
 223      * @return reference to the new nsIChannel object
 224      *
 225      * Please note, if you provide both a loadingNode and a loadingPrincipal,
 226      * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
 227      * But less error prone is to just supply a loadingNode.
 228      */
 229     nsIChannel newChannelFromURIWithProxyFlags2(in nsIURI aURI,
 230                                                 in nsIURI aProxyURI,
 231                                                 in unsigned long aProxyFlags,
 232                                                 in Node aLoadingNode,
 233                                                 in nsIPrincipal aLoadingPrincipal,
 234                                                 in nsIPrincipal aTriggeringPrincipal,
 235                                                 in unsigned long aSecurityFlags,
 236                                                 in unsigned long aContentPolicyType);
 237 };
 238
 239 %{C++
 240 /**
 241  * We send notifications through nsIObserverService with topic
 242  * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
 243  * when 'offline' has changed from false to true, and we are about
 244  * to shut down network services such as DNS. When those
 245  * services have been shut down, we send a notification with
 246  * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
 247  * NS_IOSERVICE_OFFLINE.
 248  *
 249  * When 'offline' changes from true to false, then after
 250  * network services have been restarted, we send a notification
 251  * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
 252  * NS_IOSERVICE_ONLINE.
 253  */
 254 #define NS_IOSERVICE_GOING_OFFLINE_TOPIC  "network:offline-about-to-go-offline"
 255 #define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
 256 #define NS_IOSERVICE_OFFLINE              "offline"
 257 #define NS_IOSERVICE_ONLINE               "online"
 258
 259 %}
 260
 261 [builtinclass, uuid(6633c0bf-d97a-428f-8ece-cb6a655fb95a)]
 262 interface nsIIOServiceInternal : nsISupports
 263 {
 264     /**
 265      * This is an internal method that should only be called from ContentChild
 266      * in order to pass the connectivity state from the chrome process to the
 267      * content process. It throws if called outside the content process.
 268      */
 269     void SetConnectivity(in boolean connectivity);
 270
 271     /**
 272      * An internal method to asynchronously run our notifications that happen
 273      * when we wake from sleep
 274      */
 275     void NotifyWakeup();
 276 };