DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (4a108e94d3e2)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIProtocolHandler;
interface nsIChannel;
interface nsIURI;
interface nsIFile;
interface nsIDOMNode;
interface nsIPrincipal;
interface nsILoadInfo;

/**
 * nsIIOService provides a set of network utility functions.  This interface
 * duplicates many of the nsIProtocolHandler methods in a protocol handler
 * independent way (e.g., NewURI inspects the scheme in order to delegate
 * creation of the new URI to the appropriate protocol handler).  nsIIOService
 * also provides a set of URL parsing utility functions.  These are provided
 * as a convenience to the programmer and in some cases to improve performance
 * by eliminating intermediate data structures and interfaces.
 */
[scriptable, uuid(b1c3c61d-2df9-4240-ae16-0355b51a2770)]
interface nsIIOService : nsISupports
{
    /**
     * Returns a protocol handler for a given URI scheme.
     *
     * @param aScheme the URI scheme
     * @return reference to corresponding nsIProtocolHandler
     */
    nsIProtocolHandler getProtocolHandler(in string aScheme);

    /**
     * Returns the protocol flags for a given scheme.
     *
     * @param aScheme the URI scheme
     * @return value of corresponding nsIProtocolHandler::protocolFlags
     */
    unsigned long getProtocolFlags(in string aScheme);

    /**
     * This method constructs a new URI by determining the scheme of the
     * URI spec, and then delegating the construction of the URI to the
     * protocol handler for that scheme. QueryInterface can be used on
     * the resulting URI object to obtain a more specific type of URI.
     *
     * @see nsIProtocolHandler::newURI
     */
    nsIURI newURI(in AUTF8String aSpec,
                  in string aOriginCharset,
                  in nsIURI aBaseURI);

    /**
     * This method constructs a new URI from a nsIFile.
     *
     * @param aFile specifies the file path
     * @return reference to a new nsIURI object
     *
     * Note: in the future, for perf reasons we should allow 
     * callers to specify whether this is a file or directory by
     * splitting this  into newDirURI() and newActualFileURI().
     */
    nsIURI newFileURI(in nsIFile aFile);

    /**
     * Creates a channel for a given URI.
     *
     * @param aURI
     *        nsIURI from which to make a channel
     * @param aLoadingNode
     *        The loadingDocument of the channel.
     *        The element or document where the result of this request will be
     *        used. This is the document/element that will get access to the
     *        result of this request. For example for an image load, it's the
     *        document in which the image will be loaded. And for a CSS
     *        stylesheet it's the document whose rendering will be affected by
     *        the stylesheet.
     *        If possible, pass in the element which is performing the load. But
     *        if the load is coming from a JS API (such as XMLHttpRequest) or if
     *        the load might be coalesced across multiple elements (such as
     *        for <img>) then pass in the Document node instead.
     *        For loads that are not related to any document, such as loads coming
     *        from addons or internal browser features, use null here.
     * @param aLoadingPrincipal
     *        The loadingPrincipal of the channel.
     *        The principal of the document where the result of this request will
     *        be used.
     *        This is generally the principal of the aLoadingNode. However for
     *        loads where aLoadingNode is null this argument still needs to be
     *        passed. For example for loads from a WebWorker, pass the principal
     *        of that worker. For loads from an addon or from internal browser
     *        features, pass the system principal.
     *        This principal should almost always be the system principal if
     *        aLoadingNode is null. The only exception to this is for loads
     *        from WebWorkers since they don't have any nodes to be passed as
     *        aLoadingNode.
     *        Please note, aLoadingPrincipal is *not* the principal of the
     *        resource being loaded. But rather the principal of the context
     *        where the resource will be used.
     * @param aTriggeringPrincipal
     *        The triggeringPrincipal of the load.
     *        The triggeringPrincipal is the principal of the resource that caused
     *        this particular URL to be loaded.
     *        Most likely the triggeringPrincipal and the loadingPrincipal are
     *        identical, in which case the triggeringPrincipal can be left out.
     *        In some cases the loadingPrincipal and the triggeringPrincipal are
     *        different however, e.g. a stylesheet may import a subresource. In
     *        that case the principal of the stylesheet which contains the
     *        import command is the triggeringPrincipal, and the principal of
     *        the document whose rendering is affected is the loadingPrincipal.
     * @param aSecurityFlags
     *        The securityFlags of the channel.
     *        Any of the securityflags defined in nsILoadInfo.idl
     * @param aContentPolicyType
     *        The contentPolicyType of the channel.
     *        Any of the content types defined in nsIContentPolicy.idl
     * @return reference to the new nsIChannel object
     *
     * Please note, if you provide both a loadingNode and a loadingPrincipal,
     * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
     * But less error prone is to just supply a loadingNode.
     *
     * Keep in mind that URIs coming from a webpage should *never* use the
     * systemPrincipal as the loadingPrincipal.
     */
    nsIChannel newChannelFromURI2(in nsIURI aURI,
                                  in nsIDOMNode aLoadingNode,
                                  in nsIPrincipal aLoadingPrincipal,
                                  in nsIPrincipal aTriggeringPrincipal,
                                  in unsigned long aSecurityFlags,
                                  in unsigned long aContentPolicyType);

    /**
     * Equivalent to newChannelFromURI2(aURI, aLoadingNode, ...)
     */
    nsIChannel newChannelFromURIWithLoadInfo(in nsIURI aURI,
                                             in nsILoadInfo aLoadInfo);

    /**
     * Creates a channel for a given URI.
     *
     * @param aURI nsIURI from which to make a channel
     * @return reference to the new nsIChannel object
     */
    nsIChannel newChannelFromURI(in nsIURI aURI);

    /**
     * Equivalent to newChannelFromURI2(newURI(...))
     */
    nsIChannel newChannel2(in AUTF8String aSpec,
                           in string aOriginCharset,
                           in nsIURI aBaseURI,
                           in nsIDOMNode aLoadingNode,
                           in nsIPrincipal aLoadingPrincipal,
                           in nsIPrincipal aTriggeringPrincipal,
                           in unsigned long aSecurityFlags,
                           in unsigned long aContentPolicyType);

    /**
     * Equivalent to newChannelFromURI(newURI(...))
     */
    nsIChannel newChannel(in AUTF8String aSpec,
                          in string aOriginCharset,
                          in nsIURI aBaseURI);

    /**
     * Returns true if networking is in "offline" mode. When in offline mode, 
     * attempts to access the network will fail (although this does not 
     * necessarily correlate with whether there is actually a network 
     * available -- that's hard to detect without causing the dialer to 
     * come up).
     *
     * Changing this fires observer notifications ... see below.
     */
    attribute boolean offline;

    /**
     * Set whether network appears to be offline for network connections from
     * a given appID.
     *
     * Calling this function may fire the "network:app-offline-status-changed"
     * notification, which is also sent to child processes containing this appId.
     * 'state' must one of nsIAppOfflineInfo::{ONLINE|OFFLINE|WIFI_ONLY}.
     */
    void setAppOffline(in uint32_t appId, in long state);

    /**
     * Returns true if given appId is currently not allowed to make network
     * connections. It will return true if the app is in the wifi-only state
     * and we are currently on a 3G connection.
     * The returned value does not depend on the offline state of the browser.
     */
    boolean isAppOffline(in uint32_t appId);

    /**
     * Returns the state of the app with the given appId.
     * returns nsIAppOfflineInfo::{ONLINE,OFFLINE,WIFI_ONLY}
     */
    long getAppOfflineState(in uint32_t appId);

    /**
     * Checks if a port number is banned. This involves consulting a list of
     * unsafe ports, corresponding to network services that may be easily
     * exploitable. If the given port is considered unsafe, then the protocol
     * handler (corresponding to aScheme) will be asked whether it wishes to
     * override the IO service's decision to block the port. This gives the
     * protocol handler ultimate control over its own security policy while
     * ensuring reasonable, default protection.
     *
     * @see nsIProtocolHandler::allowPort
     */
    boolean allowPort(in long aPort, in string aScheme);

    /**
     * Utility to extract the scheme from a URL string, consistently and
     * according to spec (see RFC 2396).
     *
     * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme
     * can also be extracted from a URL string via nsIURI.  This method
     * is provided purely as an optimization.
     *
     * @param aSpec the URL string to parse
     * @return URL scheme
     *
     * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
     */
    ACString extractScheme(in AUTF8String urlString);
};

[scriptable, uuid(4ac296a0-ca1b-44f4-8787-117a88cb70fb)]
interface nsIAppOfflineInfo : nsISupports
{
    readonly attribute unsigned long appId;

    const long ONLINE = 1;
    const long OFFLINE = 2;
    const long WIFI_ONLY = 3;

    readonly attribute long mode;
};

%{C++
/**
 * We send notifications through nsIObserverService with topic
 * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
 * when 'offline' has changed from false to true, and we are about
 * to shut down network services such as DNS. When those
 * services have been shut down, we send a notification with
 * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
 * NS_IOSERVICE_OFFLINE.
 *
 * When 'offline' changes from true to false, then after
 * network services have been restarted, we send a notification
 * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
 * NS_IOSERVICE_ONLINE.
 */
#define NS_IOSERVICE_GOING_OFFLINE_TOPIC  "network:offline-about-to-go-offline"
#define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
#define NS_IOSERVICE_OFFLINE              "offline"
#define NS_IOSERVICE_ONLINE               "online"

/**
 * When network:app-offline-status-changed is fired,
 * the 'Subject' argument is a nsIOfflineAppInfo.
 */
#define NS_IOSERVICE_APP_OFFLINE_STATUS_TOPIC "network:app-offline-status-changed"
%}