Source code

Revision control

Other Tools

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