1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIIOService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,139 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIProtocolHandler;
1.12 +interface nsIChannel;
1.13 +interface nsIURI;
1.14 +interface nsIFile;
1.15 +
1.16 +/**
1.17 + * nsIIOService provides a set of network utility functions. This interface
1.18 + * duplicates many of the nsIProtocolHandler methods in a protocol handler
1.19 + * independent way (e.g., NewURI inspects the scheme in order to delegate
1.20 + * creation of the new URI to the appropriate protocol handler). nsIIOService
1.21 + * also provides a set of URL parsing utility functions. These are provided
1.22 + * as a convenience to the programmer and in some cases to improve performance
1.23 + * by eliminating intermediate data structures and interfaces.
1.24 + */
1.25 +[scriptable, uuid(bddeda3f-9020-4d12-8c70-984ee9f7935e)]
1.26 +interface nsIIOService : nsISupports
1.27 +{
1.28 + /**
1.29 + * Returns a protocol handler for a given URI scheme.
1.30 + *
1.31 + * @param aScheme the URI scheme
1.32 + * @return reference to corresponding nsIProtocolHandler
1.33 + */
1.34 + nsIProtocolHandler getProtocolHandler(in string aScheme);
1.35 +
1.36 + /**
1.37 + * Returns the protocol flags for a given scheme.
1.38 + *
1.39 + * @param aScheme the URI scheme
1.40 + * @return value of corresponding nsIProtocolHandler::protocolFlags
1.41 + */
1.42 + unsigned long getProtocolFlags(in string aScheme);
1.43 +
1.44 + /**
1.45 + * This method constructs a new URI by determining the scheme of the
1.46 + * URI spec, and then delegating the construction of the URI to the
1.47 + * protocol handler for that scheme. QueryInterface can be used on
1.48 + * the resulting URI object to obtain a more specific type of URI.
1.49 + *
1.50 + * @see nsIProtocolHandler::newURI
1.51 + */
1.52 + nsIURI newURI(in AUTF8String aSpec,
1.53 + in string aOriginCharset,
1.54 + in nsIURI aBaseURI);
1.55 +
1.56 + /**
1.57 + * This method constructs a new URI from a nsIFile.
1.58 + *
1.59 + * @param aFile specifies the file path
1.60 + * @return reference to a new nsIURI object
1.61 + *
1.62 + * Note: in the future, for perf reasons we should allow
1.63 + * callers to specify whether this is a file or directory by
1.64 + * splitting this into newDirURI() and newActualFileURI().
1.65 + */
1.66 + nsIURI newFileURI(in nsIFile aFile);
1.67 +
1.68 + /**
1.69 + * Creates a channel for a given URI.
1.70 + *
1.71 + * @param aURI nsIURI from which to make a channel
1.72 + * @return reference to the new nsIChannel object
1.73 + */
1.74 + nsIChannel newChannelFromURI(in nsIURI aURI);
1.75 +
1.76 + /**
1.77 + * Equivalent to newChannelFromURI(newURI(...))
1.78 + */
1.79 + nsIChannel newChannel(in AUTF8String aSpec,
1.80 + in string aOriginCharset,
1.81 + in nsIURI aBaseURI);
1.82 +
1.83 + /**
1.84 + * Returns true if networking is in "offline" mode. When in offline mode,
1.85 + * attempts to access the network will fail (although this does not
1.86 + * necessarily correlate with whether there is actually a network
1.87 + * available -- that's hard to detect without causing the dialer to
1.88 + * come up).
1.89 + *
1.90 + * Changing this fires observer notifications ... see below.
1.91 + */
1.92 + attribute boolean offline;
1.93 +
1.94 + /**
1.95 + * Checks if a port number is banned. This involves consulting a list of
1.96 + * unsafe ports, corresponding to network services that may be easily
1.97 + * exploitable. If the given port is considered unsafe, then the protocol
1.98 + * handler (corresponding to aScheme) will be asked whether it wishes to
1.99 + * override the IO service's decision to block the port. This gives the
1.100 + * protocol handler ultimate control over its own security policy while
1.101 + * ensuring reasonable, default protection.
1.102 + *
1.103 + * @see nsIProtocolHandler::allowPort
1.104 + */
1.105 + boolean allowPort(in long aPort, in string aScheme);
1.106 +
1.107 + /**
1.108 + * Utility to extract the scheme from a URL string, consistently and
1.109 + * according to spec (see RFC 2396).
1.110 + *
1.111 + * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme
1.112 + * can also be extracted from a URL string via nsIURI. This method
1.113 + * is provided purely as an optimization.
1.114 + *
1.115 + * @param aSpec the URL string to parse
1.116 + * @return URL scheme
1.117 + *
1.118 + * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
1.119 + */
1.120 + ACString extractScheme(in AUTF8String urlString);
1.121 +};
1.122 +
1.123 +%{C++
1.124 +/**
1.125 + * We send notifications through nsIObserverService with topic
1.126 + * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
1.127 + * when 'offline' has changed from false to true, and we are about
1.128 + * to shut down network services such as DNS. When those
1.129 + * services have been shut down, we send a notification with
1.130 + * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
1.131 + * NS_IOSERVICE_OFFLINE.
1.132 + *
1.133 + * When 'offline' changes from true to false, then after
1.134 + * network services have been restarted, we send a notification
1.135 + * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
1.136 + * NS_IOSERVICE_ONLINE.
1.137 + */
1.138 +#define NS_IOSERVICE_GOING_OFFLINE_TOPIC "network:offline-about-to-go-offline"
1.139 +#define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
1.140 +#define NS_IOSERVICE_OFFLINE "offline"
1.141 +#define NS_IOSERVICE_ONLINE "online"
1.142 +%}
