diff options
Diffstat (limited to 'netwerk/base/nsIIOService.idl')
| -rw-r--r-- | netwerk/base/nsIIOService.idl | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/netwerk/base/nsIIOService.idl b/netwerk/base/nsIIOService.idl new file mode 100644 index 000000000..9bb777405 --- /dev/null +++ b/netwerk/base/nsIIOService.idl @@ -0,0 +1,218 @@ +/* -*- 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(4286de5a-b2ea-446f-8f70-e2a461f42694)] +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, + [optional] in string aOriginCharset, + [optional] 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 + * @param aLoadingPrincipal + * @param aTriggeringPrincipal + * @param aSecurityFlags + * @param aContentPolicyType + * These will be used as values for the nsILoadInfo object on the + * created channel. For details, see nsILoadInfo in nsILoadInfo.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); + + /** + * 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); + + /** + * ***** DEPRECATED ***** + * Please use NewChannelFromURI2() + * + * 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); + + /** + * ***** DEPRECATED ***** + * Please use newChannel2(). + * + * 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; + + /** + * Returns false if there are no interfaces for a network request + */ + readonly attribute boolean connectivity; + + /** + * 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); +}; + +%{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" + +%} + +[builtinclass, uuid(6633c0bf-d97a-428f-8ece-cb6a655fb95a)] +interface nsIIOServiceInternal : nsISupports +{ + /** + * This is an internal method that should only be called from ContentChild + * in order to pass the connectivity state from the chrome process to the + * content process. It throws if called outside the content process. + */ + void SetConnectivity(in boolean connectivity); + + /** + * An internal method to asynchronously run our notifications that happen + * when we wake from sleep + */ + void NotifyWakeup(); +}; |