CFProxySupport Reference

Framework
CoreServices
Companion 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 to determine the best proxy to use to retrieve a specified URL.

extern CFArrayRef
CFNetworkCopyProxiesForAutoConfigurationScript(
   CFStringRef   proxyAutoConfigurationScript,
   CFURLRef      targetURL
   CFErrorRef *  error
);
Parameters
proxyAutoConfigurationScript

A CFString containing the code of the autoconfiguration script to execute.

targetURL

The URL your application intends to access.

error

The address of an error object reference that is overwritten on return if an error occurs.

Availability
  • Available in 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

CFNetworkCopySystemProxySettings

Returns a CFDictionary containing the current systemwide internet proxy settings.

CFDictionaryRef CFNetworkCopySystemProxySettings( void );
Discussion

The dictionary returned contains key-value pairs that represent the current internet proxy settings. The keys in this dictionary are defined in “Global Proxy Settings Constants.”

The caller is responsible for releasing the returned dictionary.

Availability
  • Available in OS X v10.6 and later.
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.

Availability
  • Available in 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.

Availability
  • Available in 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 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.

const CFStringRef kCFProxyAutoConfigurationHTTPResponseKey;
const CFStringRef kCFProxyAutoConfigurationJavaScriptKey;
const CFStringRef kCFProxyAutoConfigurationURLKey;
const CFStringRef kCFProxyHostNameKey;
const CFStringRef kCFProxyPasswordKey;
const CFStringRef kCFProxyPortNumberKey;
const CFStringRef kCFProxyTypeKey;
const CFStringRef kCFProxyUsernameKey;
Constants
kCFProxyAutoConfigurationHTTPResponseKey

A CFHTTPMessageRef value found in the user info dictionary of an authentication error returned to the CFNetworkCopyProxiesForAutoConfigurationScript function or to a CFProxyAutoConfigurationResultCallback callback.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyAutoConfigurationJavaScriptKey

A CFString value containing the full JavaScript source for the proxy autoconfiguration (PAC) file. This key is only present for proxies of type kCFProxyAutoConfigurationJavaScript.

Available in OS X v10.7 and later.

Declared in CFProxySupport.h.

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 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 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 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 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 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 OS X v10.5 and later.

Declared in CFProxySupport.h.

Proxy Types

Constants that specify the type of proxy.

const CFStringRef kCFProxyTypeNone;
const CFStringRef kCFProxyTypeAutoConfigurationURL;
const CFStringRef kCFProxyTypeAutoConfigurationJavaScript;
const CFStringRef kCFProxyTypeFTP;
const CFStringRef kCFProxyTypeHTTP;
const CFStringRef kCFProxyTypeHTTPS;
const CFStringRef kCFProxyTypeSOCKS;
Constants
kCFProxyTypeNone

Specifies that no proxy should be used.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeAutoConfigurationURL

Specifies that the proxy is determined by an autoconfiguration file at a given URL.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeAutoConfigurationJavaScript

Specifies that the proxy is determined by a provided autoconfiguration script.

Available in OS X v10.7 and later.

Declared in CFProxySupport.h.

kCFProxyTypeFTP

Specifies an FTP proxy.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeHTTP

Specifies an HTTP proxy.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeHTTPS

Specifies an HTTPS proxy.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

kCFProxyTypeSOCKS

Specifies a SOCKS proxy.

Available in OS X v10.5 and later.

Declared in CFProxySupport.h.

Global Proxy Settings Constants

Constants for keys in the global proxy settings dictionary returned by CFNetworkCopySystemProxySettings.

const CFStringRef kCFNetworkProxiesExceptionsList;
const CFStringRef kCFNetworkProxiesExcludeSimpleHostnames;
const CFStringRef kCFNetworkProxiesFTPEnable;
const CFStringRef kCFNetworkProxiesFTPPassive;
const CFStringRef kCFNetworkProxiesFTPPort;
const CFStringRef kCFNetworkProxiesFTPProxy;
const CFStringRef kCFNetworkProxiesGopherEnable;
const CFStringRef kCFNetworkProxiesGopherPort;
const CFStringRef kCFNetworkProxiesGopherProxy;
const CFStringRef kCFNetworkProxiesHTTPEnable;
const CFStringRef kCFNetworkProxiesHTTPPort;
const CFStringRef kCFNetworkProxiesHTTPProxy;
const CFStringRef kCFNetworkProxiesHTTPSEnable;
const CFStringRef kCFNetworkProxiesHTTPSPort;
const CFStringRef kCFNetworkProxiesHTTPSProxy;
const CFStringRef kCFNetworkProxiesRTSPEnable;
const CFStringRef kCFNetworkProxiesRTSPPort;
const CFStringRef kCFNetworkProxiesRTSPProxy;
const CFStringRef kCFNetworkProxiesSOCKSEnable;
const CFStringRef kCFNetworkProxiesSOCKSPort;
const CFStringRef kCFNetworkProxiesSOCKSProxy;
const CFStringRef kCFNetworkProxiesProxyAutoConfigEnable;
const CFStringRef kCFNetworkProxiesProxyAutoConfigJavaScript;
const CFStringRef kCFNetworkProxiesProxyAutoConfigURLString;
const CFStringRef kCFNetworkProxiesProxyAutoDiscoveryEnable;
Constants
kCFNetworkProxiesExceptionsList

Value is a CFArray of CFString objects indicating host name patterns that should bypass the proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesExcludeSimpleHostnames

Value is a CFNumber object indicating whether simple host names are excluded. Simple host names are excluded if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesFTPEnable

Value is a CFNumber object indicating whether an FTP proxy is enabled. The proxy is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesFTPPassive

Value is a CFNumber object indicating whether an FTP proxy’s passive mode is enabled. The passive mode is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesFTPPort

Value is a CFNumber object indicating the port number of an FTP proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesFTPProxy

Value is a CFString object indicating the host name or IP number of an FTP proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesGopherEnable

Value is a CFNumber object indicating whether a gopher proxy is enabled. The proxy is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesGopherPort

Value is a CFNumber indicating the port number of a gopher proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesGopherProxy

Value is a CFString object indicating the host name or IP number of a gopher proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesHTTPEnable

Value is a CFNumber object indicating whether an HTTP proxy is enabled. The proxy is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesHTTPPort

Value is a CFNumber object containing the port number associated with the HTTP proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesHTTPProxy

Value is a CFString object containing the HTTP proxy host name or IP number.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesHTTPSEnable

Value is a CFNumber object indicating whether an HTTPS proxy is enabled. The proxy is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesHTTPSPort

Value is a CFNumber object containing the port number associated with the HTTPS proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesHTTPSProxy

Value is a CFString object containing the HTTPS proxy host name or IP number.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesRTSPEnable

Value is a CFNumber object indicating whether an RTSP proxy is enabled. The proxy is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesRTSPPort

Value is a CFNumber object containing the port number associated with the RTSP proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesRTSPProxy

Value is a CFString object containing the RTSP proxy host name or IP number.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesSOCKSEnable

Value is a CFNumber object indicating whether a SOCKS proxy is enabled. The proxy is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesSOCKSPort

Value is a CFNumber object containing the port number associated with the SOCKS proxy.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesSOCKSProxy

Value is a CFString object containing the SOCKS proxy host name or IP number.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesProxyAutoConfigEnable

Value is a CFNumber object indicating whether proxy autoconfiguration is enabled. Proxy autoconfiguration is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesProxyAutoConfigJavaScript

Value is a CFString object that contains the full JavaScript source of the ProxyAutoConfig (PAC) file.

Available in OS X v10.7 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesProxyAutoConfigURLString

Value is a CFString object that contains the URL of the proxy autoconfiguration (PAC) file.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.

kCFNetworkProxiesProxyAutoDiscoveryEnable

Value is a CFNumber object indicating whether proxy autodiscovery is enabled. Proxy autodiscovery is enabled if the key is present and the associated value is nonzero.

Available in OS X v10.6 and later.

Declared in CFProxySupport.h.