Back to index

lightning-sunbird  0.9+nobinonly
Classes | Public Member Functions | Public Attributes | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends
nsProtocolProxyService Class Reference

#include <nsProtocolProxyService.h>

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

List of all members.

Classes

struct  FilterLink
struct  HostInfo
union  HostInfo.__unnamed__
struct  HostInfoIP
struct  HostInfoName

Public Member Functions

NS_DECL_ISUPPORTS
NS_DECL_NSPIPROTOCOLPROXYSERVICE
NS_DECL_NSIPROTOCOLPROXYSERVICE
NS_DECL_NSIOBSERVER 
nsProtocolProxyService () NS_HIDDEN
 NS_HIDDEN_ (nsresult) Init()
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.
void observe (in nsISupports aSubject, in string aTopic, in wstring aData)
 Observe will be called when there is a notification for the topic |aTopic|.

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.

Protected Types

enum  ProxyConfig {
  eProxyConfig_Direct, eProxyConfig_Manual, eProxyConfig_PAC, eProxyConfig_Direct4x,
  eProxyConfig_WPAD, eProxyConfig_Last
}

Protected Member Functions

 ~nsProtocolProxyService () NS_HIDDEN
 NS_HIDDEN_ (void) PrefsChanged(nsIPrefBranch *prefs
 This method is called whenever a preference may have changed or to initialize all preferences.
 NS_HIDDEN_ (const char *) ExtractProxyInfo(const char *proxy
 This method is called to create a nsProxyInfo instance from the given PAC-style proxy string.
 NS_HIDDEN_ (void) ProcessPACString(const nsCString &pacString
 This method builds a list of nsProxyInfo objects from the given PAC- style string.
 NS_HIDDEN_ (void) GetProxyKey(nsProxyInfo *pi
 This method generates a string valued identifier for the given nsProxyInfo object.
 NS_HIDDEN_ (PRUint32) SecondsSinceSessionStart()
 NS_HIDDEN_ (void) EnableProxy(nsProxyInfo *pi)
 This method removes the specified proxy from the disabled list.
 NS_HIDDEN_ (void) DisableProxy(nsProxyInfo *pi)
 This method adds the specified proxy to the disabled list.
 NS_HIDDEN_ (PRBool) IsProxyDisabled(nsProxyInfo *pi)
 This method tests to see if the given proxy is disabled.
 NS_HIDDEN_ (nsresult) GetProtocolInfo(nsIURI *uri
 This method queries the protocol handler for the given scheme to check for the protocol flags and default port.
 NS_HIDDEN_ (nsresult) NewProxyInfo_Internal(const char *type
 This method is an internal version nsIProtocolProxyService::newProxyInfo that expects a string literal for the type.
 NS_HIDDEN_ (nsresult) Resolve_Internal(nsIURI *uri
 This method is an internal version of Resolve that does not query PAC.
 NS_HIDDEN_ (void) ApplyFilters(nsIURI *uri
 This method applies the registered filters to the given proxy info list, and returns a possibly modified list.
void ApplyFilters (nsIURI *uri, const nsProtocolInfo &info, nsCOMPtr< nsIProxyInfo > &proxyInfo)
 This method is a simple wrapper around ApplyFilters that takes the proxy info list inout param as a nsCOMPtr.
 NS_HIDDEN_ (void) PruneProxyInfo(const nsProtocolInfo &info
 This method prunes out disabled and disallowed proxies from a given proxy info list.
 NS_HIDDEN_ (void) LoadHostFilters(const char *hostFilters)
 This method populates mHostFiltersArray from the given string.
 NS_HIDDEN_ (PRBool) CanUseProxy(nsIURI *uri
 This method checks the given URI against mHostFiltersArray.

Static Protected Member Functions

static PRBool PR_CALLBACK CleanupFilterArray (void *aElement, void *aData)
static void *PR_CALLBACK HandlePACLoadEvent (PLEvent *aEvent)
static void PR_CALLBACK DestroyPACLoadEvent (PLEvent *aEvent)

Protected Attributes

const char * name
nsProxyInfo ** result
nsIProxyInfo ** result
nsCStringresult
nsProtocolInforesult
const nsACString & host
const nsACString PRInt32 port
const nsACString PRInt32 PRUint32 flags
const nsACString PRInt32
PRUint32 PRUint32 
timeout
const nsACString PRInt32
PRUint32 PRUint32 nsIProxyInfo
next
const nsACString PRInt32
PRUint32 PRUint32 nsIProxyInfo
nsIProxyInfo ** 
result
const nsProtocolInfoinfo
const nsProtocolInfo PRBoolusePAC
const nsProtocolInfo PRBool
nsIProxyInfo ** 
result
const nsProtocolInfo
nsIProxyInfo ** 
proxyInfo
nsIProxyInfo ** proxyInfo
PRInt32 defaultPort
nsVoidArray mHostFiltersArray
FilterLinkmFilters
ProxyConfig mProxyConfig
nsCString mHTTPProxyHost
PRInt32 mHTTPProxyPort
nsCString mFTPProxyHost
PRInt32 mFTPProxyPort
nsCString mGopherProxyHost
PRInt32 mGopherProxyPort
nsCString mHTTPSProxyHost
PRInt32 mHTTPSProxyPort
nsCString mSOCKSProxyHost
PRInt32 mSOCKSProxyPort
PRInt32 mSOCKSProxyVersion
PRBool mSOCKSProxyRemoteDNS
nsRefPtr< nsPACManmPACMan
PRTime mSessionStart
nsFailedProxyTable mFailedProxies
PRInt32 mFailedProxyTimeout

Friends

class nsAsyncResolveRequest

Detailed Description

Definition at line 65 of file nsProtocolProxyService.h.


Class Documentation

union nsProtocolProxyService::HostInfo.__unnamed__

Definition at line 320 of file nsProtocolProxyService.h.

Class Members
HostInfoIP ip
HostInfoName name
struct nsProtocolProxyService::HostInfoIP

Definition at line 294 of file nsProtocolProxyService.h.

Class Members
PRIPv6Addr addr
PRUint16 family
PRUint16 mask_len
struct nsProtocolProxyService::HostInfoName

Definition at line 300 of file nsProtocolProxyService.h.

Class Members
char * host
PRUint32 host_len

Member Enumeration Documentation

Enumerator:
eProxyConfig_Direct 
eProxyConfig_Manual 
eProxyConfig_PAC 
eProxyConfig_Direct4x 
eProxyConfig_WPAD 
eProxyConfig_Last 

Definition at line 307 of file nsProtocolProxyService.h.


Constructor & Destructor Documentation

NS_DECL_ISUPPORTS NS_DECL_NSPIPROTOCOLPROXYSERVICE NS_DECL_NSIPROTOCOLPROXYSERVICE NS_DECL_NSIOBSERVER nsProtocolProxyService::nsProtocolProxyService ( )

Definition at line 322 of file nsProtocolProxyService.cpp.

{
    // These should have been cleaned up in our Observe method.
    NS_ASSERTION(mHostFiltersArray.Count() == 0 && mFilters == nsnull &&
                 mPACMan == nsnull, "what happened to xpcom-shutdown?");
}

Member Function Documentation

void nsProtocolProxyService::ApplyFilters ( nsIURI uri,
const nsProtocolInfo info,
nsCOMPtr< nsIProxyInfo > &  proxyInfo 
) [inline, protected]

This method is a simple wrapper around ApplyFilters that takes the proxy info list inout param as a nsCOMPtr.

Definition at line 244 of file nsProtocolProxyService.h.

    {
      nsIProxyInfo *pi = nsnull;
      proxyInfo.swap(pi);
      ApplyFilters(uri, info, &pi);
      proxyInfo.swap(pi);
    }
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.
PRBool PR_CALLBACK nsProtocolProxyService::CleanupFilterArray ( void aElement,
void aData 
) [static, protected]

Definition at line 1008 of file nsProtocolProxyService.cpp.

{
    if (aElement)
        delete (HostInfo *) aElement;

    return PR_TRUE;
}
void nsPIProtocolProxyService::configureFromPAC ( in AUTF8String  aURI) [inherited]

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.
static void PR_CALLBACK nsProtocolProxyService::DestroyPACLoadEvent ( PLEvent aEvent) [static, protected]
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.
static void* PR_CALLBACK nsProtocolProxyService::HandlePACLoadEvent ( PLEvent aEvent) [static, protected]
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.

This method is called whenever a preference may have changed or to initialize all preferences.

Parameters:
prefsThis must be a pointer to the root pref branch.
nameThis can be the name of a fully-qualified preference, or it can be null, in which case all preferences will be initialized.
nsProtocolProxyService::NS_HIDDEN_ ( const char *  ) const [protected]

This method is called to create a nsProxyInfo instance from the given PAC-style proxy string.

It parses up to the end of the string, or to the next ';' character.

Parameters:
proxyThe PAC-style proxy string to parse. This must not be null.
resultUpon return this points to a newly allocated nsProxyInfo or null if the proxy string was invalid.
Returns:
A pointer beyond the parsed proxy string (never null).
nsProtocolProxyService::NS_HIDDEN_ ( void  ) const [protected]

This method builds a list of nsProxyInfo objects from the given PAC- style string.

Parameters:
pacStringThe PAC-style proxy string to parse. This may be empty.
resultThe resulting list of proxy info objects.

This method generates a string valued identifier for the given nsProxyInfo object.

Parameters:
piThe nsProxyInfo object from which to generate the key.
resultUpon return, this parameter holds the generated key.
Returns:
Seconds since start of session.

This method removes the specified proxy from the disabled list.

Parameters:
piThe nsProxyInfo object identifying the proxy to enable.

This method adds the specified proxy to the disabled list.

Parameters:
piThe nsProxyInfo object identifying the proxy to disable.

This method tests to see if the given proxy is disabled.

Parameters:
piThe nsProxyInfo object identifying the proxy to test.
Returns:
True if the specified proxy is disabled.

This method queries the protocol handler for the given scheme to check for the protocol flags and default port.

Parameters:
uriThe URI to query.
infoHolds information about the protocol upon return. Pass address of structure when you call this method. This parameter must not be null.

This method is an internal version nsIProtocolProxyService::newProxyInfo that expects a string literal for the type.

Parameters:
typeThe proxy type.
hostThe proxy host name (UTF-8 ok).
portThe proxy port number.
flagsThe proxy flags (nsIProxyInfo::flags).
timeoutThe failover timeout for this proxy.
nextThe next proxy to try if this one fails.
resultThe resulting nsIProxyInfo object.

This method is an internal version of Resolve that does not query PAC.

It performs all of the built-in processing, and reports back to the caller with either the proxy info result or a flag to instruct the caller to use PAC instead.

Parameters:
uriThe URI to test.
infoInformation about the URI's protocol.
usePACIf this flag is set upon return, then PAC should be queried to resolve the proxy info.
resultThe resulting proxy info or null.

This method applies the registered filters to the given proxy info list, and returns a possibly modified list.

Parameters:
uriThe URI corresponding to this proxy info list.
infoInformation about the URI's protocol.
proxyInfoThe proxy info list to be modified. This is an inout param.
nsProtocolProxyService::NS_HIDDEN_ ( void  ) const [protected]

This method prunes out disabled and disallowed proxies from a given proxy info list.

Parameters:
infoInformation about the URI's protocol.
proxyInfoThe proxy info list to be modified. This is an inout param.
nsProtocolProxyService::NS_HIDDEN_ ( void  ) const [protected]

This method populates mHostFiltersArray from the given string.

Parameters:
hostFiltersA "no-proxy-for" exclusion list.

This method checks the given URI against mHostFiltersArray.

Parameters:
uriThe URI to test.
defaultPortThe default port for the given URI.
Returns:
True if the URI can use the specified proxy.
void nsIObserver::observe ( in nsISupports  aSubject,
in string  aTopic,
in wstring  aData 
) [inherited]

Observe will be called when there is a notification for the topic |aTopic|.

This assumes that the object implementing this interface has been registered with an observer service such as the nsIObserverService.

If you expect multiple topics/subjects, the impl is responsible for filtering.

You should not modify, add, remove, or enumerate notifications in the implemention of observe.

Parameters:
aSubject: Notification specific interface pointer.
aTopic: The notification topic or subject.
aData: Notification specific wide string. subject event.
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.

Friends And Related Function Documentation

friend class nsAsyncResolveRequest [friend]

Definition at line 79 of file nsProtocolProxyService.h.


Member Data Documentation

Definition at line 283 of file nsProtocolProxyService.h.

Definition at line 198 of file nsProtocolProxyService.h.

const nsACString& nsProtocolProxyService::host [protected]

Definition at line 198 of file nsProtocolProxyService.h.

Definition at line 222 of file nsProtocolProxyService.h.

Definition at line 376 of file nsProtocolProxyService.h.

Definition at line 377 of file nsProtocolProxyService.h.

Definition at line 352 of file nsProtocolProxyService.h.

Definition at line 359 of file nsProtocolProxyService.h.

Definition at line 360 of file nsProtocolProxyService.h.

Definition at line 362 of file nsProtocolProxyService.h.

Definition at line 363 of file nsProtocolProxyService.h.

Definition at line 348 of file nsProtocolProxyService.h.

Definition at line 356 of file nsProtocolProxyService.h.

Definition at line 357 of file nsProtocolProxyService.h.

Definition at line 365 of file nsProtocolProxyService.h.

Definition at line 366 of file nsProtocolProxyService.h.

Definition at line 373 of file nsProtocolProxyService.h.

Definition at line 354 of file nsProtocolProxyService.h.

Definition at line 375 of file nsProtocolProxyService.h.

Definition at line 368 of file nsProtocolProxyService.h.

Definition at line 369 of file nsProtocolProxyService.h.

Definition at line 371 of file nsProtocolProxyService.h.

Definition at line 370 of file nsProtocolProxyService.h.

Definition at line 93 of file nsProtocolProxyService.h.

Definition at line 198 of file nsProtocolProxyService.h.

const nsACString PRInt32 nsProtocolProxyService::port [protected]

Definition at line 198 of file nsProtocolProxyService.h.

Definition at line 237 of file nsProtocolProxyService.h.

Definition at line 263 of file nsProtocolProxyService.h.

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.

Definition at line 109 of file nsProtocolProxyService.h.

Definition at line 121 of file nsProtocolProxyService.h.

Definition at line 132 of file nsProtocolProxyService.h.

Definition at line 176 of file nsProtocolProxyService.h.

Definition at line 198 of file nsProtocolProxyService.h.

Definition at line 222 of file nsProtocolProxyService.h.

Definition at line 198 of file nsProtocolProxyService.h.

Definition at line 222 of file nsProtocolProxyService.h.


The documentation for this class was generated from the following files: