Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
nsPIProtocolProxyService Interface Reference

THIS IS A PRIVATE INTERFACE. More...

import "nsPIProtocolProxyService.idl";

Inheritance diagram for nsPIProtocolProxyService:
Inheritance graph
[legend]
Collaboration diagram for nsPIProtocolProxyService:
Collaboration graph
[legend]

List of all members.

Public Member Functions

void configureFromPAC (in AUTF8String aURI)
 This method may be called to re-configure proxy settings given a URI to a new proxy auto config file.
nsIProxyInfo resolve (in nsIURI aURI, in unsigned long aFlags)
 This method returns a nsIProxyInfo instance that identifies a proxy to be used for loading the given URI.
nsICancelable asyncResolve (in nsIURI aURI, in unsigned long aFlags, in nsIProtocolProxyCallback aCallback)
 This method is an asychronous version of the resolve method.
nsIProxyInfo newProxyInfo (in ACString aType, in AUTF8String aHost, in long aPort, in unsigned long aFlags, in unsigned long aFailoverTimeout, in nsIProxyInfo aFailoverProxy)
 This method may be called to construct a nsIProxyInfo instance from the given parameters.
nsIProxyInfo getFailoverForProxy (in nsIProxyInfo aProxyInfo, in nsIURI aURI, in nsresult aReason)
 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.
void registerFilter (in nsIProtocolProxyFilter aFilter, in unsigned long aPosition)
 This method may be used to register a proxy filter instance.
void unregisterFilter (in nsIProtocolProxyFilter aFilter)
 This method may be used to unregister a proxy filter instance.

Public Attributes

const unsigned long RESOLVE_NON_BLOCKING = 1
 This flag may be passed to the resolve method to request that it fail instead of block the calling thread.

Detailed Description

THIS IS A PRIVATE INTERFACE.

It exists purely as a hack to support the configureFromPAC method used by the preference panels in the various apps. Those apps need to be taught to just use the preferences API to "reload" the PAC file. Then, at that point, we can eliminate this interface completely.

Definition at line 51 of file nsPIProtocolProxyService.idl.


Member Function Documentation

nsICancelable nsIProtocolProxyService::asyncResolve ( in nsIURI  aURI,
in unsigned long  aFlags,
in nsIProtocolProxyCallback  aCallback 
) [inherited]

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.

Parameters:
aURIThe URI to test.
aFlagsA bit-wise OR of the RESOLVE_ flags defined above. Pass 0 to specify the default behavior.
aCallbackThe object to be notified when the result is available.
Returns:
An object that can be used to cancel the asychronous operation.

This method may be called to re-configure proxy settings given a URI to a new proxy auto config file.

This method may return before the configuration actually takes affect (i.e., the URI may be loaded asynchronously).

WARNING: This method is considered harmful since it may cause the PAC preferences to be out of sync with the state of the Protocol Proxy Service. This method is going to be eliminated in the near future.

Parameters:
aURIThe location of the PAC file to load. If this value is empty, then the PAC configuration will be removed.
nsIProxyInfo nsIProtocolProxyService::getFailoverForProxy ( in nsIProxyInfo  aProxyInfo,
in nsIURI  aURI,
in nsresult  aReason 
) [inherited]

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.

Parameters:
aProxyInfoThe proxy that was unavailable.
aURIThe URI that was originally passed to resolve/asyncResolve.
aReasonThe error code corresponding to the proxy failure. This value may be used to tune the delay before this proxy is used again.
Exceptions:
NS_ERROR_NOT_AVAILABLEif there is no alternate proxy available.
nsIProxyInfo nsIProtocolProxyService::newProxyInfo ( in ACString  aType,
in AUTF8String  aHost,
in long  aPort,
in unsigned long  aFlags,
in unsigned long  aFailoverTimeout,
in nsIProxyInfo  aFailoverProxy 
) [inherited]

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.

Parameters:
aTypeThe proxy type. This is a string value that identifies the proxy type. Standard values include: "http" - specifies a HTTP 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.
aHostThe proxy hostname or IP address.
aPortThe proxy port.
aFlagsFlags associated with this connection. See nsIProxyInfo.idl for currently defined flags.
aFailoverTimeoutSpecifies 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.
aFailoverProxySpecifies the next proxy to try if this proxy fails. This parameter may be null.
void nsIProtocolProxyService::registerFilter ( in nsIProtocolProxyFilter  aFilter,
in unsigned long  aPosition 
) [inherited]

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.

Parameters:
aFilterThe nsIProtocolProxyFilter instance to be registered.
aPositionThe position of the filter.

NOTE: It is possible to construct filters that compete with one another in undesirable ways. This API does not attempt to protect against such problems. It is recommended that any extensions that choose to call this method make their position value configurable at runtime (perhaps via the preferences service).

nsIProxyInfo nsIProtocolProxyService::resolve ( in nsIURI  aURI,
in unsigned long  aFlags 
) [inherited]

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.

Parameters:
aURIThe URI to test.
aFlagsA bit-wise OR of the RESOLVE_ flags defined above. Pass 0 to specify the default behavior.

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

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

NOTE: 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.

NOTE: If PAC is configured, and the PAC file has not yet been loaded, then this method will return a nsIProxyInfo instance with a type of "unknown" to indicate to the consumer that asyncResolve should be used to wait for the PAC file to finish loading. Otherwise, the consumer may choose to treat the result as type "direct" if desired.

See also:
nsIProxiedProtocolHandler::newProxiedChannel

This method may be used to unregister a proxy filter instance.

All filters will be automatically unregistered at XPCOM shutdown.

Parameters:
aFilterThe nsIProtocolProxyFilter instance to be unregistered.

Member Data Documentation

This flag may be passed to the resolve method to request that it fail instead of block the calling thread.

Proxy Auto Config (PAC) may perform a synchronous DNS query, which may not return immediately. So, calling resolve without this flag may result in locking up the calling thread for a lengthy period of time.

By passing this flag to resolve, one can failover to asyncResolve to avoid locking up the calling thread if a PAC query is required.

When this flag is passed to resolve, resolve may throw the exception NS_BASE_STREAM_WOULD_BLOCK to indicate that it failed due to this flag being present.

Definition at line 72 of file nsIProtocolProxyService.idl.


The documentation for this interface was generated from the following file: