The Tor Browser / file comparison

comparison: netwerk/base/public/nsIProtocolProxyService.idl

netwerk/base/public/nsIProtocolProxyService.idl

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:268b00486fd2
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* vim:set ts=4 sw=4 sts=4 et: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7 #include "nsISupports.idl"
8
9 interface nsICancelable;
10 interface nsIProtocolProxyCallback;
11 interface nsIProtocolProxyFilter;
12 interface nsIProtocolProxyChannelFilter;
13 interface nsIProxyInfo;
14 interface nsIChannel;
15 interface nsIURI;
16
17 /**
18 * nsIProtocolProxyService provides methods to access information about
19 * various network proxies.
20 */
21 [scriptable, uuid(ab363090-c331-489f-aabb-7fe4481795b8)]
22 interface nsIProtocolProxyService : nsISupports
23 {
24 /** Flag 1 << 0 is unused **/
25
26 /**
27 * When the proxy configuration is manual this flag may be passed to the
28 * resolve and asyncResolve methods to request to prefer the SOCKS proxy
29 * to HTTP ones.
30 */
31 const unsigned long RESOLVE_PREFER_SOCKS_PROXY = 1 << 1;
32
33 /**
34 * When the proxy configuration is manual this flag may be passed to the
35 * resolve and asyncResolve methods to request to not analyze the uri's
36 * scheme specific proxy. When this flag is set the main HTTP proxy is the
37 * preferred one.
38 *
39 * NOTE: if RESOLVE_PREFER_SOCKS_PROXY is set then the SOCKS proxy is
40 * the preferred one.
41 *
42 * NOTE: if RESOLVE_PREFER_HTTPS_PROXY is set then the HTTPS proxy
43 * is the preferred one.
44 */
45 const unsigned long RESOLVE_IGNORE_URI_SCHEME = 1 << 2;
46
47 /**
48 * When the proxy configuration is manual this flag may be passed to the
49 * resolve and asyncResolve methods to request to prefer the HTTPS proxy
50 * to the others HTTP ones.
51 *
52 * NOTE: RESOLVE_PREFER_SOCKS_PROXY takes precedence over this flag.
53 *
54 * NOTE: This flag implies RESOLVE_IGNORE_URI_SCHEME.
55 */
56 const unsigned long RESOLVE_PREFER_HTTPS_PROXY =
57 (1 << 3) | RESOLVE_IGNORE_URI_SCHEME;
58
59 /**
60 * When the proxy configuration is manual this flag may be passed to the
61 * resolve and asyncResolve methods to that all methods will be tunneled via
62 * CONNECT through the http proxy.
63 */
64 const unsigned long RESOLVE_ALWAYS_TUNNEL = (1 << 4);
65
66 /**
67 * This method returns via callback a nsIProxyInfo instance that identifies
68 * a proxy to be used for the given channel. Otherwise, this method returns
69 * null indicating that a direct connection should be used.
70 *
71 * @param aChannel
72 * The channel for which a proxy is to be found.
73 * @param aFlags
74 * A bit-wise combination of the RESOLVE_ flags defined above. Pass
75 * 0 to specify the default behavior. Any additional bits that do
76 * not correspond to a RESOLVE_ flag are reserved for future use.
77 * @param aCallback
78 * The object to be notified when the result is available.
79 *
80 * @return An object that can be used to cancel the asychronous operation.
81 * If canceled, the cancelation status (aReason) will be forwarded
82 * to the callback's onProxyAvailable method via the aStatus param.
83 *
84 * NOTE: If this proxy is unavailable, getFailoverForProxy may be called
85 * to determine the correct secondary proxy to be used.
86 *
87 * NOTE: If the protocol handler for the given URI supports
88 * nsIProxiedProtocolHandler, then the nsIProxyInfo instance returned from
89 * resolve may be passed to the newProxiedChannel method to create a
90 * nsIChannel to the given URI that uses the specified proxy.
91 *
92 * NOTE: However, if the nsIProxyInfo type is "http", then it means that
93 * the given URI should be loaded using the HTTP protocol handler, which
94 * also supports nsIProxiedProtocolHandler.
95 *
96 * @see nsIProxiedProtocolHandler::newProxiedChannel
97 */
98 nsICancelable asyncResolve(in nsIChannel aChannel, in unsigned long aFlags,
99 in nsIProtocolProxyCallback aCallback);
100
101 /**
102 * This method may be called to construct a nsIProxyInfo instance from
103 * the given parameters. This method may be useful in conjunction with
104 * nsISocketTransportService::createTransport for creating, for example,
105 * a SOCKS connection.
106 *
107 * @param aType
108 * The proxy type. This is a string value that identifies the proxy
109 * type. Standard values include:
110 * "http" - specifies a HTTP proxy
111 * "socks" - specifies a SOCKS version 5 proxy
112 * "socks4" - specifies a SOCKS version 4 proxy
113 * "direct" - specifies a direct connection (useful for failover)
114 * The type name is case-insensitive. Other string values may be
115 * possible, and new types may be defined by a future version of
116 * this interface.
117 * @param aHost
118 * The proxy hostname or IP address.
119 * @param aPort
120 * The proxy port.
121 * @param aFlags
122 * Flags associated with this connection. See nsIProxyInfo.idl
123 * for currently defined flags.
124 * @param aFailoverTimeout
125 * Specifies the length of time (in seconds) to ignore this proxy if
126 * this proxy fails. Pass UINT32_MAX to specify the default
127 * timeout value, causing nsIProxyInfo::failoverTimeout to be
128 * assigned the default value.
129 * @param aFailoverProxy
130 * Specifies the next proxy to try if this proxy fails. This
131 * parameter may be null.
132 */
133 nsIProxyInfo newProxyInfo(in ACString aType, in AUTF8String aHost,
134 in long aPort, in unsigned long aFlags,
135 in unsigned long aFailoverTimeout,
136 in nsIProxyInfo aFailoverProxy);
137
138 /**
139 * This method may be called to construct a nsIProxyInfo instance for
140 * a SOCKS connection, with the specified username and password.
141 * @param aHost
142 * The proxy hostname or IP address.
143 * @param aPort
144 * The proxy port.
145 * @param aUsername
146 * The SOCKS5 username
147 * @param aPassword
148 * The SOCKS5 password
149 * @param aFlags
150 * Flags associated with this connection. See nsIProxyInfo.idl
151 * for currently defined flags.
152 * @param aFailoverTimeout
153 * Specifies the length of time (in seconds) to ignore this proxy if
154 * this proxy fails. Pass UINT32_MAX to specify the default
155 * timeout value, causing nsIProxyInfo::failoverTimeout to be
156 * assigned the default value.
157 * @param aFailoverProxy
158 * Specifies the next proxy to try if this proxy fails. This
159 * parameter may be null.
160 */
161 nsIProxyInfo newSOCKSProxyInfo(in AUTF8String aHost, in long aPort,
162 in ACString aUsername, in ACString aPassword,
163 in unsigned long aFlags,
164 in unsigned long aFailoverTimeout,
165 in nsIProxyInfo aFailoverProxy);
166
167 /**
168 * If the proxy identified by aProxyInfo is unavailable for some reason,
169 * this method may be called to access an alternate proxy that may be used
170 * instead. As a side-effect, this method may affect future result values
171 * from resolve/asyncResolve as well as from getFailoverForProxy.
172 *
173 * @param aProxyInfo
174 * The proxy that was unavailable.
175 * @param aURI
176 * The URI that was originally passed to resolve/asyncResolve.
177 * @param aReason
178 * The error code corresponding to the proxy failure. This value
179 * may be used to tune the delay before this proxy is used again.
180 *
181 * @throw NS_ERROR_NOT_AVAILABLE if there is no alternate proxy available.
182 */
183 nsIProxyInfo getFailoverForProxy(in nsIProxyInfo aProxyInfo,
184 in nsIURI aURI,
185 in nsresult aReason);
186
187 /**
188 * This method may be used to register a proxy filter instance. Each proxy
189 * filter is registered with an associated position that determines the
190 * order in which the filters are applied (starting from position 0). When
191 * resolve/asyncResolve is called, it generates a list of proxies for the
192 * given URI, and then it applies the proxy filters. The filters have the
193 * opportunity to modify the list of proxies.
194 *
195 * If two filters register for the same position, then the filters will be
196 * visited in the order in which they were registered.
197 *
198 * If the filter is already registered, then its position will be updated.
199 *
200 * After filters have been run, any disabled or disallowed proxies will be
201 * removed from the list. A proxy is disabled if it had previously failed-
202 * over to another proxy (see getFailoverForProxy). A proxy is disallowed,
203 * for example, if it is a HTTP proxy and the nsIProtocolHandler for the
204 * queried URI does not permit proxying via HTTP.
205 *
206 * If a nsIProtocolHandler disallows all proxying, then filters will never
207 * have a chance to intercept proxy requests for such URLs.
208 *
209 * @param aFilter
210 * The nsIProtocolProxyFilter instance to be registered.
211 * @param aPosition
212 * The position of the filter.
213 *
214 * NOTE: It is possible to construct filters that compete with one another
215 * in undesirable ways. This API does not attempt to protect against such
216 * problems. It is recommended that any extensions that choose to call
217 * this method make their position value configurable at runtime (perhaps
218 * via the preferences service).
219 */
220 void registerFilter(in nsIProtocolProxyFilter aFilter,
221 in unsigned long aPosition);
222
223 /**
224 * Similar to registerFilter, but accepts an nsIProtocolProxyChannelFilter,
225 * which selects proxies according to channel rather than URI.
226 *
227 * @param aFilter
228 * The nsIProtocolProxyChannelFilter instance to be registered.
229 * @param aPosition
230 * The position of the filter.
231 */
232 void registerChannelFilter(in nsIProtocolProxyChannelFilter aFilter,
233 in unsigned long aPosition);
234
235 /**
236 * This method may be used to unregister a proxy filter instance. All
237 * filters will be automatically unregistered at XPCOM shutdown.
238 *
239 * @param aFilter
240 * The nsIProtocolProxyFilter instance to be unregistered.
241 */
242 void unregisterFilter(in nsIProtocolProxyFilter aFilter);
243
244 /**
245 * This method may be used to unregister a proxy channel filter instance. All
246 * filters will be automatically unregistered at XPCOM shutdown.
247 *
248 * @param aFilter
249 * The nsIProtocolProxyChannelFilter instance to be unregistered.
250 */
251 void unregisterChannelFilter(in nsIProtocolProxyChannelFilter aFilter);
252
253 /**
254 * These values correspond to the possible integer values for the
255 * network.proxy.type preference.
256 */
257 const unsigned long PROXYCONFIG_DIRECT = 0;
258 const unsigned long PROXYCONFIG_MANUAL = 1;
259 const unsigned long PROXYCONFIG_PAC = 2;
260 const unsigned long PROXYCONFIG_WPAD = 4;
261 const unsigned long PROXYCONFIG_SYSTEM = 5;
262
263 /**
264 * This attribute specifies the current type of proxy configuration.
265 */
266 readonly attribute unsigned long proxyConfigType;
267 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial