michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIProtocolHandler;
michael@0: interface nsIChannel;
michael@0: interface nsIURI;
michael@0: interface nsIFile;
michael@0: 
michael@0: /**
michael@0:  * nsIIOService provides a set of network utility functions.  This interface
michael@0:  * duplicates many of the nsIProtocolHandler methods in a protocol handler
michael@0:  * independent way (e.g., NewURI inspects the scheme in order to delegate
michael@0:  * creation of the new URI to the appropriate protocol handler).  nsIIOService
michael@0:  * also provides a set of URL parsing utility functions.  These are provided
michael@0:  * as a convenience to the programmer and in some cases to improve performance
michael@0:  * by eliminating intermediate data structures and interfaces.
michael@0:  */
michael@0: [scriptable, uuid(bddeda3f-9020-4d12-8c70-984ee9f7935e)]
michael@0: interface nsIIOService : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * Returns a protocol handler for a given URI scheme.
michael@0:      *
michael@0:      * @param aScheme the URI scheme
michael@0:      * @return reference to corresponding nsIProtocolHandler
michael@0:      */
michael@0:     nsIProtocolHandler getProtocolHandler(in string aScheme);
michael@0: 
michael@0:     /**
michael@0:      * Returns the protocol flags for a given scheme.
michael@0:      *
michael@0:      * @param aScheme the URI scheme
michael@0:      * @return value of corresponding nsIProtocolHandler::protocolFlags
michael@0:      */
michael@0:     unsigned long getProtocolFlags(in string aScheme);
michael@0: 
michael@0:     /**
michael@0:      * This method constructs a new URI by determining the scheme of the
michael@0:      * URI spec, and then delegating the construction of the URI to the
michael@0:      * protocol handler for that scheme. QueryInterface can be used on
michael@0:      * the resulting URI object to obtain a more specific type of URI.
michael@0:      *
michael@0:      * @see nsIProtocolHandler::newURI
michael@0:      */
michael@0:     nsIURI newURI(in AUTF8String aSpec,
michael@0:                   in string aOriginCharset,
michael@0:                   in nsIURI aBaseURI);
michael@0: 
michael@0:     /**
michael@0:      * This method constructs a new URI from a nsIFile.
michael@0:      *
michael@0:      * @param aFile specifies the file path
michael@0:      * @return reference to a new nsIURI object
michael@0:      *
michael@0:      * Note: in the future, for perf reasons we should allow 
michael@0:      * callers to specify whether this is a file or directory by
michael@0:      * splitting this  into newDirURI() and newActualFileURI().
michael@0:      */
michael@0:     nsIURI newFileURI(in nsIFile aFile);
michael@0: 
michael@0:     /**
michael@0:      * Creates a channel for a given URI.
michael@0:      *
michael@0:      * @param aURI nsIURI from which to make a channel
michael@0:      * @return reference to the new nsIChannel object
michael@0:      */
michael@0:     nsIChannel newChannelFromURI(in nsIURI aURI);
michael@0: 
michael@0:     /**
michael@0:      * Equivalent to newChannelFromURI(newURI(...))
michael@0:      */
michael@0:     nsIChannel newChannel(in AUTF8String aSpec,
michael@0:                           in string aOriginCharset,
michael@0:                           in nsIURI aBaseURI);
michael@0: 
michael@0:     /**
michael@0:      * Returns true if networking is in "offline" mode. When in offline mode, 
michael@0:      * attempts to access the network will fail (although this does not 
michael@0:      * necessarily correlate with whether there is actually a network 
michael@0:      * available -- that's hard to detect without causing the dialer to 
michael@0:      * come up).
michael@0:      *
michael@0:      * Changing this fires observer notifications ... see below.
michael@0:      */
michael@0:     attribute boolean offline;
michael@0: 
michael@0:     /**
michael@0:      * Checks if a port number is banned. This involves consulting a list of
michael@0:      * unsafe ports, corresponding to network services that may be easily
michael@0:      * exploitable. If the given port is considered unsafe, then the protocol
michael@0:      * handler (corresponding to aScheme) will be asked whether it wishes to
michael@0:      * override the IO service's decision to block the port. This gives the
michael@0:      * protocol handler ultimate control over its own security policy while
michael@0:      * ensuring reasonable, default protection.
michael@0:      *
michael@0:      * @see nsIProtocolHandler::allowPort
michael@0:      */
michael@0:     boolean allowPort(in long aPort, in string aScheme);
michael@0: 
michael@0:     /**
michael@0:      * Utility to extract the scheme from a URL string, consistently and
michael@0:      * according to spec (see RFC 2396).
michael@0:      *
michael@0:      * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme
michael@0:      * can also be extracted from a URL string via nsIURI.  This method
michael@0:      * is provided purely as an optimization.
michael@0:      *
michael@0:      * @param aSpec the URL string to parse
michael@0:      * @return URL scheme
michael@0:      *
michael@0:      * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
michael@0:      */
michael@0:     ACString extractScheme(in AUTF8String urlString);
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: /**
michael@0:  * We send notifications through nsIObserverService with topic
michael@0:  * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
michael@0:  * when 'offline' has changed from false to true, and we are about
michael@0:  * to shut down network services such as DNS. When those
michael@0:  * services have been shut down, we send a notification with
michael@0:  * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
michael@0:  * NS_IOSERVICE_OFFLINE.
michael@0:  *
michael@0:  * When 'offline' changes from true to false, then after
michael@0:  * network services have been restarted, we send a notification
michael@0:  * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
michael@0:  * NS_IOSERVICE_ONLINE.
michael@0:  */
michael@0: #define NS_IOSERVICE_GOING_OFFLINE_TOPIC  "network:offline-about-to-go-offline"
michael@0: #define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
michael@0: #define NS_IOSERVICE_OFFLINE              "offline"
michael@0: #define NS_IOSERVICE_ONLINE               "online"
michael@0: %}