nsIProtocolProxyService

Implemented by: @mozilla.org/network/protocol-proxy-service;1. To access the service use:

var pps = Components.classes["@mozilla.org/network/protocol-proxy-service;1"]
              .getService(Components.interfaces.nsIProtocolProxyService);

Method overview

Constants

Methods

resolve() Deprecated since Gecko 18

This method has been removed in Firefox 18. Use resolveAsync instead

Previous doc

This method returns a nsIProxyInfo instance that identifies a proxy to be used for loading the given URI. Otherwise, this method returns null indicating that a direct connection should be used.

If this proxy is unavailable, getFailoverForProxy() may be called to determine the correct secondary proxy to be used.

If the protocol handler for the given URI supports nsIProxiedProtocolHandler, then the nsIProxyInfo instance returned from resolve may be passed to the nsIProxiedProtocolHandler.newProxiedChannel() method to create a nsIChannel to the given URI that uses the specified proxy.

However, if the nsIProxyInfo type is "http", then it means that the given URI should be loaded using the HTTP protocol handler, which also supports nsIProxiedProtocolHandler.

 nsIProxyInfo resolve(
   in nsIURI aURI, 
   in unsigned long aFlags
 );

Parameters

aURI

The URI to test.

aFlags

A bit-wise combination of the RESOLVE_ flags defined above. Pass 0 to specify the default behavior. Any additional bits that do not correspond to a RESOLVE_ flag are reserved for future use.

Return value

An nsIProxyInfo object or null for a direct connection.

asyncResolve()

This method is an asychronous version of the resolve method. Unlike resolve, this method is guaranteed not to block the calling thread waiting for DNS queries to complete. This method is intended as a substitute for resolve when the result is not needed immediately.

 nsICancelable asyncResolve(
   in nsIURI aURI, 
   in unsigned long aFlags,
   in nsIProtocolProxyCallback aCallback
 );

Parameters

aURI

The URI to test.

aFlags

A bit-wise combination of the RESOLVE_ flags defined above. Pass 0 to specify the default behavior. Any additional bits that do not correspond to a RESOLVE_ flag are reserved for future use.

aCallback

The object to be notified when the result is available.

Return value

An nsICancelableobject that can be used to cancel the asynchronous operation. If canceled, the cancellation status (aReason) will be forwarded to the callback's nsIProtocolProxyCallback.onProxyAvailable() method via the aStatus parameter.

newProxyInfo()

This method may be called to construct a nsIProxyInfo instance from the given parameters. This method may be useful in conjunction with nsISocketTransportService.createTransport() for creating, for example, a SOCKS connection.

nsIProxyInfo newProxyInfo(
  in ACString aType,
  in AUTF8String aHost,
  in long aPort,
  in unsigned long aFlags,
  in unsigned long aFailoverTimeout,
  in nsIProxyInfo aFailoverProxy
);

Parameters

aType

The proxy type is a string value that identifies the proxy type. Standard values are:

• "http" - specifies a HTTP proxy
• "https" - specifies a HTTPS proxy
• "socks" - specifies a SOCKS version 5 proxy
• "socks4" - specifies a SOCKS version 4 proxy
• "direct" - specifies a direct connection (useful for failover)

The type name is case-insensitive. Other string values may be possible, and new types may be defined by a future version of this interface.

aHost

The proxy hostname or IP address.

aPort

The proxy port.

aFlags

Flags associated with this connection. See nsIProxyInfo for currently defined flags.

aFailoverTimeout

Specifies the length of time (in seconds) to ignore this proxy if this proxy fails. Pass PR_UINT32_MAX to specify the default timeout value, causing nsIProxyInfo::failoverTimeout to be assigned the default value.

aFailoverProxy

Specifies the next proxy to try if this proxy fails. This parameter may be null.

Return value

An nsIProxyInfo object.

getFailoverForProxy()

If the proxy identified by aProxyInfo is unavailable for some reason, this method may be called to access an alternate proxy that may be used instead. As a side-effect, this method may affect future result values from resolve/asyncResolve as well as from getFailoverForProxy.

nsIProxyInfo getFailoverForProxy(
  in nsIProxyInfo aProxyInfo,
  in nsIURI aURI,
  in nsresult aReason
);

Parameters

aProxyInfo

The proxy that was unavailable.

aURI

The URI that was originally passed to resolve/asyncResolve.

aReason

The error code corresponding to the proxy failure. This value may be used to tune the delay before this proxy is used again. The proxy that was unavailable.

Return value

An nsIProxyInfo object or null for a direct connection.

Exceptions thrown

NS_ERROR_NOT_AVAILABLE

If there is no alternate proxy available.

registerFilter()

This method may be used to register a proxy filter instance. Each proxy filter is registered with an associated position that determines the order in which the filters are applied (starting from position 0). When resolve/asyncResolve is called, it generates a list of proxies for the given URI, and then it applies the proxy filters. The filters have the opportunity to modify the list of proxies.

If two filters register for the same position, then the filters will be visited in the order in which they were registered. If the filter is already registered, then its position will be updated.

After filters have been run, any disabled or disallowed proxies will be removed from the list. A proxy is disabled if it had previously failed-over to another proxy (see getFailoverForProxy()). A proxy is disallowed, for example, if it is a HTTP proxy and the nsIProtocolHandler for the queried URI does not permit proxying via HTTP.

If a nsIProtocolHandler disallows all proxying, then filters will never have a chance to intercept proxy requests for such URLs.

void registerFilter(
  in nsIProtocolProxyFilter aFilter,
  in unsigned long aPosition
);

Parameters

aFilter

The nsIProtocolProxyFilter instance to be registered.

aPosition

The position of the filter.

unregisterFilter()

This method may be used to unregister a proxy filter instance. All filters will be automatically unregistered at XPCOM shutdown.

void unregisterFilter(
  in nsIProtocolProxyFilter aFilter
);

Parameters

aFilter

The nsIProtocolProxyFilter instance to be unregistered.

See also

• nsIProxyInfo
• nsIProtocolProxyFilter
• nsIProxiedProtocolHandler
• nsICancelable