diff options
Diffstat (limited to 'netwerk/base/nsIIOService.idl')
| -rw-r--r-- | netwerk/base/nsIIOService.idl | 362 |
1 files changed, 362 insertions, 0 deletions
diff --git a/netwerk/base/nsIIOService.idl b/netwerk/base/nsIIOService.idl new file mode 100644 index 0000000000..5bc3e41181 --- /dev/null +++ b/netwerk/base/nsIIOService.idl @@ -0,0 +1,362 @@ +/* -*- 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" +#include "nsIContentPolicy.idl" + +interface nsIProtocolHandler; +interface nsIChannel; +interface nsIURI; +interface nsIFile; +interface nsIPrincipal; +interface nsILoadInfo; +interface nsIWebTransport; + +webidl Node; + +%{C++ +#include "mozilla/Maybe.h" + +namespace mozilla { +namespace dom { +class ClientInfo; +class ServiceWorkerDescriptor; +} // namespace dom +} // namespace mozilla +%} + +[ref] native const_MaybeClientInfoRef(const mozilla::Maybe<mozilla::dom::ClientInfo>); +[ref] native const_MaybeServiceWorkerDescriptorRef(const mozilla::Maybe<mozilla::dom::ServiceWorkerDescriptor>); + +/** + * 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, builtinclass, 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 protocol flags for the corresponding protocol + */ + unsigned long getProtocolFlags(in string aScheme); + + /** + * Returns the dynamic protocol flags for a given URI. + * + * @param aURI the URI to get all dynamic flags for + * @return protocol flags for that URI + */ + unsigned long getDynamicProtocolFlags(in nsIURI aURI); + + /** + * Returns the default port for a given scheme. + * + * @param aScheme the URI scheme + * @return default port for the corresponding protocol + */ + long getDefaultPort(in string aScheme); + + /** + * This method constructs a new URI based on the scheme of the URI spec. + * QueryInterface can be used on the resulting URI object to obtain a more + * specific type of URI. + */ + 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); + + /** + * Converts an internal URI (e.g. one that has a username and password in + * it) into one which we can expose to the user, for example on the URL bar. + * + * @param aURI The URI to be converted. + * @return nsIURI The converted, exposable URI. + */ + nsIURI createExposableURI(in nsIURI aURI); + + /** + * 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 newChannelFromURI(in nsIURI aURI, + in Node aLoadingNode, + in nsIPrincipal aLoadingPrincipal, + in nsIPrincipal aTriggeringPrincipal, + in unsigned long aSecurityFlags, + in nsContentPolicyType aContentPolicyType); + + [noscript, nostdcall, notxpcom] + nsresult NewChannelFromURIWithClientAndController(in nsIURI aURI, + in Node aLoadingNode, + in nsIPrincipal aLoadingPrincipal, + in nsIPrincipal aTriggeringPrincipal, + in const_MaybeClientInfoRef aLoadingClientInfo, + in const_MaybeServiceWorkerDescriptorRef aController, + in unsigned long aSecurityFlags, + in nsContentPolicyType aContentPolicyType, + in unsigned long aSandboxFlags, + in boolean aSkipCheckForBrokenURLOrZeroSized, + out nsIChannel aResult); + + /** + * Equivalent to newChannelFromURI(aURI, aLoadingNode, ...) + */ + nsIChannel newChannelFromURIWithLoadInfo(in nsIURI aURI, + in nsILoadInfo aLoadInfo); + + /** + * Equivalent to newChannelFromURI(newURI(...)) + */ + nsIChannel newChannel(in AUTF8String aSpec, + in string aOriginCharset, + in nsIURI aBaseURI, + in Node aLoadingNode, + in nsIPrincipal aLoadingPrincipal, + in nsIPrincipal aTriggeringPrincipal, + in unsigned long aSecurityFlags, + in nsContentPolicyType aContentPolicyType); + + /** + * Creates a WebTransport. + */ + nsIWebTransport newWebTransport(); + + /** + * 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, lowercase + * + * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form. + */ + ACString extractScheme(in AUTF8String urlString); + + /** + * Checks if a URI host is a local IPv4 or IPv6 address literal. + * + * @param nsIURI the URI that contains the hostname to check + * @return true if the URI hostname is a local IP address + */ + boolean hostnameIsLocalIPAddress(in nsIURI aURI); + + /** + * Checks if a URI host is a shared IPv4 address literal. + * + * @param nsIURI the URI that contains the hostname to check + * @return true if the URI hostname is a shared IP address + */ + boolean hostnameIsSharedIPAddress(in nsIURI aURI); + + /** + * Checks if a hostname is valid. + * + * @param AUTF8String hostname is the hostname to validate + * @return true if the hostname is valid, else false + */ + boolean isValidHostname(in AUTF8String hostname); + + /** + * While this is set, IOService will monitor an nsINetworkLinkService + * (if available) and set its offline status to "true" whenever + * isLinkUp is false. + * + * Applications that want to control changes to the IOService's offline + * status should set this to false, watch for network:link-status-changed + * broadcasts, and change nsIIOService::offline as they see fit. Note + * that this means during application startup, IOService may be offline + * if there is no link, until application code runs and can turn off + * this management. + */ + attribute boolean manageOfflineStatus; + + /** + * Creates a channel for a given URI. + * + * @param aURI + * nsIURI from which to make a channel + * @param aProxyURI + * nsIURI to use for proxy resolution. Can be null in which + * case aURI is used + * @param aProxyFlags flags from nsIProtocolProxyService to use + * when resolving proxies for this new 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. + */ + nsIChannel newChannelFromURIWithProxyFlags(in nsIURI aURI, + in nsIURI aProxyURI, + in unsigned long aProxyFlags, + in Node aLoadingNode, + in nsIPrincipal aLoadingPrincipal, + in nsIPrincipal aTriggeringPrincipal, + in unsigned long aSecurityFlags, + in nsContentPolicyType aContentPolicyType); + + /** + * Return true if socket process is launched. + */ + readonly attribute boolean socketProcessLaunched; + + /** + * The pid for socket process. + */ + readonly attribute unsigned long long socketProcessId; + + /** + * Register a protocol handler at runtime, given protocol flags and a + * default port. + * + * Statically registered protocol handlers cannot be overridden, and an + * error will be returned if that is attempted. + * + * Runtime registered protocol handlers are never QueryInterface-ed into + * `nsIProtocolHandlerWithDynamicFlags`, so that interface will be ignored. + * + * @param aScheme the scheme handled by the protocol handler. + * @param aHandler the protocol handler instance. + * @param aProtocolFlags protocol flags for this protocol, see + * nsIProtocolHandler for values. + * @param aDefaultPort default port for this scheme, or -1. + */ + void registerProtocolHandler(in ACString aScheme, + in nsIProtocolHandler aHandler, + in unsigned long aProtocolFlags, + in long aDefaultPort); + + /** + * Unregister a protocol handler which was previously registered using + * registerProtocolHandler. + * + * @param aScheme the scheme to unregister a handler for. + */ + void unregisterProtocolHandler(in ACString aScheme); +}; + +%{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" + +%} + +[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(); +}; |