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