Next Page >

Hide TOC

CFProxySupport Reference

Framework	CoreServices
Companion guide	CFNetwork Programming Guide
Declared in	CFProxySupport.h

Overview

The CFProxySupport API enables you to take advantage of global proxy configuration settings in your application.

The CFProxySupport functions return arrays of dictionaries, where each dictionary describes a single proxy. The arrays represent the order in which the proxies should be tried. In general, you should try to download a URL using the first proxy in the array, try the second proxy if the first one fails, and so on.

Every proxy dictionary has an entry for kCFProxyTypeKey. If the type is anything except kCFProxyTypeAutoConfigurationURL, the dictionary also has entries for the proxy's host and port (under kCFProxyHostNameKey and kCFProxyPortNumberKey respectively). If the type is kCFProxyTypeAutoConfigurationURL, it has an entry for kCFProxyAutoConfigurationURLKey.

The keys for username and password are optional and are present only if the username or password could be extracted from the information passed in (either from the URL itself or from the proxy dictionary supplied). These APIs do not consult any external credential stores such as the Keychain.

Functions

CFNetworkCopyProxiesForAutoConfigurationScript

Executes a proxy autoconfiguration script determine the best proxy to use to retrieve the specified URL

extern CFArrayRef
CFNetworkCopyProxiesForAutoConfigurationScript(
   CFStringRef   proxyAutoConfigurationScript,
   CFURLRef      targetURL);

Parameters

proxyAutoConfigurationScript: A CFString containing the code of the autoconfiguration script to execute.
targetURL: The URL your application intends to access.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CFProxySupport.h

CFNetworkCopyProxiesForURL

Returns the list of proxies that should be used to download a given URL.

extern CFArrayRef
CFNetworkCopyProxiesForURL(
   CFURLRef          url,
   CFDictionaryRef   proxySettings
);

Parameters

url: The URL your application intends to access.
proxySettings: A dictionary describing the available proxy settings. The dictionary should be in the format returned by SystemConfiguration.framework. (See System Configuration Framework Reference for more information.)

Return Value

Returns an array of dictionaries. Each dictionary describes a single proxy. The array is ordered optimally for requesting the URL specified.

Availability

AvailabilityItem

Declared In

CFProxySupport.h

CFNetworkExecuteProxyAutoConfigurationScript

Downloads a proxy autoconfiguration script and executes it.

CFRunLoopSourceRef
CFNetworkExecuteProxyAutoConfigurationScript(
   CFStringRef proxyAutoConfigurationScript,
   CFURLRef targetURL,
   CFProxyAutoConfigurationResultCallback cb,
   CFStreamClientContext *clientContext);

Parameters

proxyAutoConfigurationScript: A CFString containing the code of the autoconfiguration script to be executed.
targetURL: The URL that your application intends to eventually download using the proxies.
cb: A callback to be called when execution of the script is finished.
clientContext: A stream context containing a client info object and optionally retain and release callbacks for that object.

Discussion

This function returns a run loop source that the caller should schedule. Once execution of the script has completed, the specified callback function is called.

Note: If you want to terminate the request before completion, you should invalidate the run loop source.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CFProxySupport.h

CFNetworkExecuteProxyAutoConfigurationURL

Downloads a proxy autoconfiguration script and executes it.

extern CFRunLoopSourceRef
CFNetworkExecuteProxyAutoConfigurationURL(
   CFURLRef proxyAutoConfigURL,
   CFURLRef targetURL,
   CFProxyAutoConfigurationResultCallback cb,
   CFStreamClientContext *clientContext);

Parameters

proxyAutoConfigURL: The URL of the autoconfiguration script.
targetURL: The URL that your application intends to eventually download using the proxies.
cb: A callback to be called when execution of the script is finished.
clientContext: A stream context containing a client info object and optionally retain and release callbacks for that object.

Discussion

This function returns a run loop source that the caller should schedule. Once downloading and execution of the script has completed, the specified callback function is called.

Note: If you want to terminate the request before completion, you should invalidate the run loop source.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CFProxySupport.h

Callbacks

CFProxyAutoConfigurationResultCallback

Callback function called when a proxy autoconfiguration computation has completed.

typedef CALLBACK_API_C(
   void,
   CFProxyAutoConfigurationResultCallback
)(
   void *client,
   CFArrayRef proxyList,
   CFErrorRef error
);

void myFunction(
   void *client,
   CFArrayRef proxyList,
   CFErrorRef error
);

Parameters

client: The client reference originally passed in the clientContext parameter of the CFNetworkExecuteProxyAutoConfigurationScript or CFNetworkExecuteProxyAutoConfigurationURL call that triggered this callback.
proxyList: The list of proxies returned by the autoconfiguration script. This list is in a format suitable for passing to CFProxyCopyProxiesForURL (with the added guarantee that no entries will ever be autoconfiguration URL entries). If an error occurs, this value will be NULL.
Note: If you want to keep this list, you must retain it when your callback receives it.
error: An error object that indicates any error that may have occurred. If no error occurred, this value will be NULL.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CFProxySupport.h

Constants

Property Keys

Keys for calls to property get/set functions such as CFReadStreamSetProperty and CFReadStreamCopyProperty.

extern const CFStringRef kCFProxyAutoConfigurationURLKey;
extern const CFStringRef kCFProxyHostNameKey;
extern const CFStringRef kCFProxyPortNumberKey;
extern const CFStringRef kCFProxyTypeKey;
extern const CFStringRef kCFProxyUsernameKey;
extern const CFStringRef kCFProxyPasswordKey;

Constants

kCFProxyAutoConfigurationURLKey

A CFURL value specifying the location of the proxy autoconfiguration (PAC) file. This key is only present for proxies of type kCFProxyTypeAutoConfigurationURL.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyHostNameKey

A CFString value containing either the hostname or IP number of the proxy host.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyPortNumberKey

A CFNumber value specifying the port that should be used to contact the proxy.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeKey

Specifies the type of proxy. The value can be any of the values listed in “Proxy Types.”

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyUsernameKey

The username to be used when contacting the proxy. This key is only present if the username can be determined from the information passed in. (External credential stores such as the keychain are not consulted.)

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyPasswordKey

The password to be used when contacting the proxy. This key is only present if the password can be determined from the information passed in. (External credential stores such as the keychain are not consulted.)

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

Proxy Types

Para

extern const CFStringRef kCFProxyTypeNone;
extern const CFStringRef kCFProxyTypeAutoConfigurationURL;
extern const CFStringRef kCFProxyTypeFTP;
extern const CFStringRef kCFProxyTypeHTTP;
extern const CFStringRef kCFProxyTypeHTTPS;
extern const CFStringRef kCFProxyTypeSOCKS;

Constants

kCFProxyTypeNone

Specifies that no proxy should be used.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeAutoConfigurationURL

Specifies the URL of an autoconfiguration file from which the proxy information should be obtained.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeFTP

Specifies an FTP proxy.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeHTTP

Specifies an HTTP proxy.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeHTTPS

Specifies an HTTPS proxy.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeSOCKS

Specifies a SOCKS proxy.

Available in Mac OS X v10.5 and later.

Declared in CFProxySupport.h.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.