netwerk/base/public/nsIIOService.idl@b8a032363ba2 (annotated)
netwerk/base/public/nsIIOService.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | |
| michael@0 | 8 | interface nsIProtocolHandler; |
| michael@0 | 9 | interface nsIChannel; |
| michael@0 | 10 | interface nsIURI; |
| michael@0 | 11 | interface nsIFile; |
| michael@0 | 12 | |
| michael@0 | 13 | /** |
| michael@0 | 14 | * nsIIOService provides a set of network utility functions. This interface |
| michael@0 | 15 | * duplicates many of the nsIProtocolHandler methods in a protocol handler |
| michael@0 | 16 | * independent way (e.g., NewURI inspects the scheme in order to delegate |
| michael@0 | 17 | * creation of the new URI to the appropriate protocol handler). nsIIOService |
| michael@0 | 18 | * also provides a set of URL parsing utility functions. These are provided |
| michael@0 | 19 | * as a convenience to the programmer and in some cases to improve performance |
| michael@0 | 20 | * by eliminating intermediate data structures and interfaces. |
| michael@0 | 21 | */ |
| michael@0 | 22 | [scriptable, uuid(bddeda3f-9020-4d12-8c70-984ee9f7935e)] |
| michael@0 | 23 | interface nsIIOService : nsISupports |
| michael@0 | 24 | { |
| michael@0 | 25 | /** |
| michael@0 | 26 | * Returns a protocol handler for a given URI scheme. |
| michael@0 | 27 | * |
| michael@0 | 28 | * @param aScheme the URI scheme |
| michael@0 | 29 | * @return reference to corresponding nsIProtocolHandler |
| michael@0 | 30 | */ |
| michael@0 | 31 | nsIProtocolHandler getProtocolHandler(in string aScheme); |
| michael@0 | 32 | |
| michael@0 | 33 | /** |
| michael@0 | 34 | * Returns the protocol flags for a given scheme. |
| michael@0 | 35 | * |
| michael@0 | 36 | * @param aScheme the URI scheme |
| michael@0 | 37 | * @return value of corresponding nsIProtocolHandler::protocolFlags |
| michael@0 | 38 | */ |
| michael@0 | 39 | unsigned long getProtocolFlags(in string aScheme); |
| michael@0 | 40 | |
| michael@0 | 41 | /** |
| michael@0 | 42 | * This method constructs a new URI by determining the scheme of the |
| michael@0 | 43 | * URI spec, and then delegating the construction of the URI to the |
| michael@0 | 44 | * protocol handler for that scheme. QueryInterface can be used on |
| michael@0 | 45 | * the resulting URI object to obtain a more specific type of URI. |
| michael@0 | 46 | * |
| michael@0 | 47 | * @see nsIProtocolHandler::newURI |
| michael@0 | 48 | */ |
| michael@0 | 49 | nsIURI newURI(in AUTF8String aSpec, |
| michael@0 | 50 | in string aOriginCharset, |
| michael@0 | 51 | in nsIURI aBaseURI); |
| michael@0 | 52 | |
| michael@0 | 53 | /** |
| michael@0 | 54 | * This method constructs a new URI from a nsIFile. |
| michael@0 | 55 | * |
| michael@0 | 56 | * @param aFile specifies the file path |
| michael@0 | 57 | * @return reference to a new nsIURI object |
| michael@0 | 58 | * |
| michael@0 | 59 | * Note: in the future, for perf reasons we should allow |
| michael@0 | 60 | * callers to specify whether this is a file or directory by |
| michael@0 | 61 | * splitting this into newDirURI() and newActualFileURI(). |
| michael@0 | 62 | */ |
| michael@0 | 63 | nsIURI newFileURI(in nsIFile aFile); |
| michael@0 | 64 | |
| michael@0 | 65 | /** |
| michael@0 | 66 | * Creates a channel for a given URI. |
| michael@0 | 67 | * |
| michael@0 | 68 | * @param aURI nsIURI from which to make a channel |
| michael@0 | 69 | * @return reference to the new nsIChannel object |
| michael@0 | 70 | */ |
| michael@0 | 71 | nsIChannel newChannelFromURI(in nsIURI aURI); |
| michael@0 | 72 | |
| michael@0 | 73 | /** |
| michael@0 | 74 | * Equivalent to newChannelFromURI(newURI(...)) |
| michael@0 | 75 | */ |
| michael@0 | 76 | nsIChannel newChannel(in AUTF8String aSpec, |
| michael@0 | 77 | in string aOriginCharset, |
| michael@0 | 78 | in nsIURI aBaseURI); |
| michael@0 | 79 | |
| michael@0 | 80 | /** |
| michael@0 | 81 | * Returns true if networking is in "offline" mode. When in offline mode, |
| michael@0 | 82 | * attempts to access the network will fail (although this does not |
| michael@0 | 83 | * necessarily correlate with whether there is actually a network |
| michael@0 | 84 | * available -- that's hard to detect without causing the dialer to |
| michael@0 | 85 | * come up). |
| michael@0 | 86 | * |
| michael@0 | 87 | * Changing this fires observer notifications ... see below. |
| michael@0 | 88 | */ |
| michael@0 | 89 | attribute boolean offline; |
| michael@0 | 90 | |
| michael@0 | 91 | /** |
| michael@0 | 92 | * Checks if a port number is banned. This involves consulting a list of |
| michael@0 | 93 | * unsafe ports, corresponding to network services that may be easily |
| michael@0 | 94 | * exploitable. If the given port is considered unsafe, then the protocol |
| michael@0 | 95 | * handler (corresponding to aScheme) will be asked whether it wishes to |
| michael@0 | 96 | * override the IO service's decision to block the port. This gives the |
| michael@0 | 97 | * protocol handler ultimate control over its own security policy while |
| michael@0 | 98 | * ensuring reasonable, default protection. |
| michael@0 | 99 | * |
| michael@0 | 100 | * @see nsIProtocolHandler::allowPort |
| michael@0 | 101 | */ |
| michael@0 | 102 | boolean allowPort(in long aPort, in string aScheme); |
| michael@0 | 103 | |
| michael@0 | 104 | /** |
| michael@0 | 105 | * Utility to extract the scheme from a URL string, consistently and |
| michael@0 | 106 | * according to spec (see RFC 2396). |
| michael@0 | 107 | * |
| michael@0 | 108 | * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme |
| michael@0 | 109 | * can also be extracted from a URL string via nsIURI. This method |
| michael@0 | 110 | * is provided purely as an optimization. |
| michael@0 | 111 | * |
| michael@0 | 112 | * @param aSpec the URL string to parse |
| michael@0 | 113 | * @return URL scheme |
| michael@0 | 114 | * |
| michael@0 | 115 | * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form. |
| michael@0 | 116 | */ |
| michael@0 | 117 | ACString extractScheme(in AUTF8String urlString); |
| michael@0 | 118 | }; |
| michael@0 | 119 | |
| michael@0 | 120 | %{C++ |
| michael@0 | 121 | /** |
| michael@0 | 122 | * We send notifications through nsIObserverService with topic |
| michael@0 | 123 | * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE |
| michael@0 | 124 | * when 'offline' has changed from false to true, and we are about |
| michael@0 | 125 | * to shut down network services such as DNS. When those |
| michael@0 | 126 | * services have been shut down, we send a notification with |
| michael@0 | 127 | * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data |
| michael@0 | 128 | * NS_IOSERVICE_OFFLINE. |
| michael@0 | 129 | * |
| michael@0 | 130 | * When 'offline' changes from true to false, then after |
| michael@0 | 131 | * network services have been restarted, we send a notification |
| michael@0 | 132 | * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data |
| michael@0 | 133 | * NS_IOSERVICE_ONLINE. |
| michael@0 | 134 | */ |
| michael@0 | 135 | #define NS_IOSERVICE_GOING_OFFLINE_TOPIC "network:offline-about-to-go-offline" |
| michael@0 | 136 | #define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed" |
| michael@0 | 137 | #define NS_IOSERVICE_OFFLINE "offline" |
| michael@0 | 138 | #define NS_IOSERVICE_ONLINE "online" |
| michael@0 | 139 | %} |
