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