FoxyProxy

FoxyProxy Object

This singleton object is the top-most object in the FoxyProxy object model. It is used to get/set global settings and to obtain the ProxyConfigs object.

Properties

settings

NameTypeDescriptionSinceRequires
settingsDOMNode

Specification here
Gets/sets all FoxyProxy settings to/from an XML DOM Node, but only if the user permits the change and apiDisabled is
false
. The object model is described in detail here, but the easiest way to create a
<foxyproxy>
string is to copy it from a generated foxyproxy.xml file. Changing the settings this way won't tell your code if the user rejected the changes, or if there was an error while parsing the settings. To receive such notifications, use the setSettings() function.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 2+ (Firefox 4+, Thunderbird 3.3+, SeaMonkey 2.1+)

Examples

Get all FoxyProxy settings as a DOM node/element


              if (typeof(FoxyProxy) == "undefined")
              alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
              else if (FoxyProxy.apiDisabled)
              alert("I cannot access your FoxyProxy settings because the FoxyProxy API is disabled on your system.");
              else {
              var node = FoxyProxy.settings;
              // Note: XMLSerializer is Firefox-specific
              var stringified = new XMLSerializer().serializeToString(node);
              alert(stringified);
            }
          

Set all FoxyProxy settings as a DOM node/element

Let's assume we have the following HTML. Notice the FoxyProxy XML in the page. Browsers won't display the XML, but they do include it in the DOM. So, it is accessible with standard Javascript.

            <html>
            <body>
            <script type="text/javascript">
            function setFoxyProxySettings(id) {
            if (typeof(FoxyProxy) == "undefined")
            alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
            else if (FoxyProxy.apiDisabled)
            alert("I cannot change your FoxyProxy settings because the FoxyProxy API is disabled on your system.");
            else
            FoxyProxy.settings = document.getElementById(id);
          }
          </script>
          Click <a onclick="setFoxyProxySettings('settings-1')">here</a> to change FoxyProxy settings
    
          <foxyproxy id="settings-1" mode="disabled" selectedTabIndex="0" toolbaricon="true" toolsMenu="true" contextMenu="true" advancedMenus="false" previousMode="3004116187" resetIconColors="true" useStatusBarPrefix="true" excludePatternsFromCycling="false" excludeDisabledFromCycling="false" ignoreProxyScheme="false" apiDisabled="false"><random includeDirect="false" includeDisabled="false"/><statusbar icon="true" text="false" left="options" middle="cycle" right="contextmenu" width="0"/><toolbar left="options" middle="cycle" right="contextmenu"/><logg enabled="false" maxSize="500" noURLs="false"/><warnings confirmDeleteProxy="false" white-patterns="false"/><autoadd enabled="false" temp="false" reload="true" notify="true" notifyWhenCanceled="true" prompt="true"><match enabled="true" name="Dynamic AutoAdd Pattern" pattern="*://${3}${6}/*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="" pattern="*You are not authorized to view this page*" isRegEx="false" isBlackList="false" isMultiLine="true" caseSensitive="false" fromSubscription="false"/></autoadd><quickadd enabled="false" temp="false" reload="true" notify="true" notifyWhenCanceled="true" prompt="true"><match enabled="true" name="Dynamic QuickAdd Pattern" pattern="*://${3}${6}/*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/></quickadd><defaultPrefs origPrefetch="17" origDiskCache="false" origMemCache="false" origOfflineCache="false" origSSLCache="false" origCookieBehavior="2"/><proxies><proxy name="localhost:9090" id="1878135280" notes="" enabled="true" mode="manual" selectedTabIndex="0" lastresort="false" animatedIcons="true" includeInCycle="true" color="#1FE600" proxyDNS="true" noInternalIPs="true" autoconfMode="pac" clearCacheBeforeUse="true" disableCache="true" clearCookiesBeforeUse="true" rejectCookies="true"><matches><match enabled="true" name="localhost - Matches the local host optionally prefixed by a user:password authentication string and optionally suffixed by a port number. Note that the entire local subnet (127.0.0.0/8) matches. Pattern exists because "Do not use this proxy for internal IP addresses" is checked" pattern="^https?://(?:[^:@/]+(?::[^@/]+)?@)?(?:localhost|127\.\d+\.\d+\.\d+)(?::\d+)?/.*" isRegEx="true" isBlackList="true" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="local subnets (IANA reserved address space). Pattern exists because "Do not use this proxy for internal IP addresses" is checked" pattern="^https?://(?:[^:@/]+(?::[^@/]+)?@)?(?:192\.168\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(?:1[6789]|2[0-9]|3[01])\.\d+\.\d+)(?::\d+)?/.*" isRegEx="true" isBlackList="true" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="local hostnames (usually no dots in the name). Pattern exists because "Do not use this proxy for internal IP addresses" is checked" pattern="^https?://(?:[^:@/]+(?::[^@/]+)?@)?[\w-]+(?::\d+)?/.*" isRegEx="true" isBlackList="true" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="google" pattern="*google.com/*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/></matches><autoconf url="" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><autoconf url="http://wpad/wpad.dat" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><manualconf host="localhost" port="9090" socksversion="5" isSocks="false"/></proxy><proxy name="Ireland" id="3004116187" notes="This is my Irish proxy" enabled="false" mode="auto" selectedTabIndex="1" lastresort="false" animatedIcons="true" includeInCycle="true" color="#E60058" proxyDNS="false" noInternalIPs="false" autoconfMode="pac" clearCacheBeforeUse="false" disableCache="false" clearCookiesBeforeUse="false" rejectCookies="false"><matches/><autoconf url="http://foo.com/proxy.pac" loadNotification="true" errorNotification="true" autoReload="true" reloadFreqMins="60" disableOnBadPAC="true"/><autoconf url="http://wpad/wpad.dat" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><manualconf host="localhost" port="9090" socksversion="5" isSocks="false"/></proxy><proxy name="Default" id="4170519589" notes="These are the settings that are used when no patterns match a URL." enabled="true" mode="direct" selectedTabIndex="0" lastresort="true" animatedIcons="false" includeInCycle="true" color="#0055E5" proxyDNS="true" noInternalIPs="false" autoconfMode="pac" clearCacheBeforeUse="false" disableCache="false" clearCookiesBeforeUse="false" rejectCookies="false"><matches><match enabled="true" name="All" pattern="*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/></matches><autoconf url="" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><autoconf url="http://wpad/wpad.dat" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><manualconf host="" port="" socksversion="5" isSocks="false"/></proxy></proxies></foxyproxy>
    
          </body>
          </html>
        

mode

NameTypeDescriptionSinceRequires
modeStringGets/sets the FoxyProxy mode, but only if the user permits the change and apiDisabled is
false
. Changing the mode this way won't tell your code if the user rejected the changes, or if there was an error while parsing the settings. To receive such notifications, use the setMode() function.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 2+ (Firefox 4+, Thunderbird 3.3+, SeaMonkey 2.1+)

Acceptable values for

mode
are patterns, disabled, random, roundrobin, previous, and proxy-id. Mode value determines the core behavior of FoxyProxy. patterns is Use proxies based on their pre-defined patterns and priorities. proxy-id means that all URLs are loaded through the proxy with the specified internal id (all proxies have a unique id--see the settings DOM reference). Random and roundrobin are not fully implemented yet. Disabled means FoxyProxy is completed disabled. previous is an internal-only mode; read more about it in the previousMode attribute.

Examples

Get the Current Mode


          if (typeof(FoxyProxy) == "undefined")
          alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
          else if (FoxyProxy.apiDisabled)
          alert("I cannot inspect your FoxyProxy mode because the FoxyProxy API is disabled on your system.");
          else
          alert(FoxyProxy.mode);
        

Set the Current Mode


          if (typeof(FoxyProxy) == "undefined")
          alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
          else if (FoxyProxy.apiDisabled)
          alert("I cannot change your FoxyProxy mode because the FoxyProxy API is disabled on your system.");
          else
          FoxyProxy.mode = "disabled";
        

apiDisabled

NameTypeDescriptionSinceRequires
apiDisabledBoolean
true
if API calls are disabled. When disabled, all API calls return
null
except for the version property and this property. User approval is not required to get this property; the user is not prompted. This property is read-only for obvious reasons.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 2+ (Firefox 4+, Thunderbird 3.3+, SeaMonkey 2.1+)

Examples

Get the Value of apiDisabled


          if (typeof(FoxyProxy) == "undefined")
          alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
          else
          alert(FoxyProxy.apiDisabled);
        

version

NameTypeDescriptionSinceRequires
versionJSON StringGets the FoxyProxy version, but only if apiDisabled is
false
. User approval is not required to get this property; the user is not prompted. This property is read-only for obvious reasons.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 2+ (Firefox 4+, Thunderbird 3.3+, SeaMonkey 2.1+)

Examples

Get the Version


          alert(FoxyProxy.version);
        
Sample output

          {"version": "3.7", "name": "FoxyProxyStandard"}
        
Possible values for
name
are
FoxyProxyBasic, FoxyProxyStandard
, and
FoxyProxyPlus
.

Functions

setSettings()

Requires Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6 or greater

SignatureDescriptionSinceRequires
setSettings(domNode, notificationCallback)

Specification for domNode here
Sets all FoxyProxy settings from an XML DOM Node, but only if the user permits the change and apiDisabled is
false
. The object model is described in detail here, but the easiest way to create a
<foxyproxy>
string is to copy it from a generated FoxyProxy.xml file. A shortcut to get/set the settings is to use the settings property.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 9+ (Firefox 9+, Thunderbird 9+, SeaMonkey 2.6+)

Examples

Set all FoxyProxy settings from a DOM node/element

Let's assume we have the following HTML. Notice the FoxyProxy XML in the page. Browsers won't display the XML, but they do include it in the DOM. So, it is accessible with standard Javascript.

          <html>
          <body>
          <script type="text/javascript">
          function setFoxyProxySettings(id) {
          if (typeof(FoxyProxy) == "undefined")
          alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
          else if (FoxyProxy.apiDisabled)
          alert("Please enable the FoxyProxy API so we can adjust your proxy configuration.");
          else {
          FoxyProxy.setSettings(document.getElementById(id), {
          success: function() {
          alert("Cool. Your settings are now changed.");
        },
        error: function(msg) {
        alert("Error: " + msg);
      },
      rejected: function rejectedByUser() {
      // User didn't allow us to make changes to FoxyProxy
      alert("Please allow me to read/write FoxyProxy settings. Please try again and click the 'Allow' button.");
    }   
    });
    }
    </script>
    Click <a onclick="setFoxyProxySettings('settings-1')">here</a> to change FoxyProxy settings
    
    <foxyproxy id="settings-1" mode="disabled" selectedTabIndex="0" toolbaricon="true" toolsMenu="true" contextMenu="true" advancedMenus="false" previousMode="3004116187" resetIconColors="true" useStatusBarPrefix="true" excludePatternsFromCycling="false" excludeDisabledFromCycling="false" ignoreProxyScheme="false" apiDisabled="false"><random includeDirect="false" includeDisabled="false"/><statusbar icon="true" text="false" left="options" middle="cycle" right="contextmenu" width="0"/><toolbar left="options" middle="cycle" right="contextmenu"/><logg enabled="false" maxSize="500" noURLs="false"/><warnings confirmDeleteProxy="false" white-patterns="false"/><autoadd enabled="false" temp="false" reload="true" notify="true" notifyWhenCanceled="true" prompt="true"><match enabled="true" name="Dynamic AutoAdd Pattern" pattern="*://${3}${6}/*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="" pattern="*You are not authorized to view this page*" isRegEx="false" isBlackList="false" isMultiLine="true" caseSensitive="false" fromSubscription="false"/></autoadd><quickadd enabled="false" temp="false" reload="true" notify="true" notifyWhenCanceled="true" prompt="true"><match enabled="true" name="Dynamic QuickAdd Pattern" pattern="*://${3}${6}/*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/></quickadd><defaultPrefs origPrefetch="17" origDiskCache="false" origMemCache="false" origOfflineCache="false" origSSLCache="false" origCookieBehavior="2"/><proxies><proxy name="localhost:9090" id="1878135280" notes="" enabled="true" mode="manual" selectedTabIndex="0" lastresort="false" animatedIcons="true" includeInCycle="true" color="#1FE600" proxyDNS="true" noInternalIPs="true" autoconfMode="pac" clearCacheBeforeUse="true" disableCache="true" clearCookiesBeforeUse="true" rejectCookies="true"><matches><match enabled="true" name="localhost - Matches the local host optionally prefixed by a user:password authentication string and optionally suffixed by a port number. Note that the entire local subnet (127.0.0.0/8) matches. Pattern exists because "Do not use this proxy for internal IP addresses" is checked" pattern="^https?://(?:[^:@/]+(?::[^@/]+)?@)?(?:localhost|127\.\d+\.\d+\.\d+)(?::\d+)?/.*" isRegEx="true" isBlackList="true" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="local subnets (IANA reserved address space). Pattern exists because "Do not use this proxy for internal IP addresses" is checked" pattern="^https?://(?:[^:@/]+(?::[^@/]+)?@)?(?:192\.168\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(?:1[6789]|2[0-9]|3[01])\.\d+\.\d+)(?::\d+)?/.*" isRegEx="true" isBlackList="true" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="local hostnames (usually no dots in the name). Pattern exists because "Do not use this proxy for internal IP addresses" is checked" pattern="^https?://(?:[^:@/]+(?::[^@/]+)?@)?[\w-]+(?::\d+)?/.*" isRegEx="true" isBlackList="true" isMultiLine="false" caseSensitive="false" fromSubscription="false"/><match enabled="true" name="google" pattern="*google.com/*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/></matches><autoconf url="" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><autoconf url="http://wpad/wpad.dat" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><manualconf host="localhost" port="9090" socksversion="5" isSocks="false"/></proxy><proxy name="Ireland" id="3004116187" notes="This is my Irish proxy" enabled="false" mode="auto" selectedTabIndex="1" lastresort="false" animatedIcons="true" includeInCycle="true" color="#E60058" proxyDNS="false" noInternalIPs="false" autoconfMode="pac" clearCacheBeforeUse="false" disableCache="false" clearCookiesBeforeUse="false" rejectCookies="false"><matches/><autoconf url="http://foo.com/proxy.pac" loadNotification="true" errorNotification="true" autoReload="true" reloadFreqMins="60" disableOnBadPAC="true"/><autoconf url="http://wpad/wpad.dat" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><manualconf host="localhost" port="9090" socksversion="5" isSocks="false"/></proxy><proxy name="Default" id="4170519589" notes="These are the settings that are used when no patterns match a URL." enabled="true" mode="direct" selectedTabIndex="0" lastresort="true" animatedIcons="false" includeInCycle="true" color="#0055E5" proxyDNS="true" noInternalIPs="false" autoconfMode="pac" clearCacheBeforeUse="false" disableCache="false" clearCookiesBeforeUse="false" rejectCookies="false"><matches><match enabled="true" name="All" pattern="*" isRegEx="false" isBlackList="false" isMultiLine="false" caseSensitive="false" fromSubscription="false"/></matches><autoconf url="" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><autoconf url="http://wpad/wpad.dat" loadNotification="true" errorNotification="true" autoReload="false" reloadFreqMins="60" disableOnBadPAC="true"/><manualconf host="" port="" socksversion="5" isSocks="false"/></proxy></proxies></foxyproxy>
    
    </body>
    </html>
    

setMode()

Requires Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6 or greater


NameDescriptionSinceRequires
setMode(newMode, notificationCallback)Sets the FoxyProxy mode, but only if the user permits the change and apiDisabled is
false
. A shortcut to get/set the mode is to use the mode property.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 9+ (Firefox 9+, Thunderbird 9+, SeaMonkey 2.6+)

Acceptable values for

newMode
are patterns, disabled, random, roundrobin, previous, and proxy-id. Mode value determines the core behavior of FoxyProxy. patterns is Use proxies based on their pre-defined patterns and priorities. proxy-id means that all URLs are loaded through the proxy with the specified internal id (all proxies have a unique id--see the settings DOM reference). Random and roundrobin are not fully implemented yet. Disabled means FoxyProxy is completed disabled. previous is an internal-only mode; read more about it in the previousMode attribute.

Examples

Set the Current Mode


        if (typeof(FoxyProxy) == "undefined")
        alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
        else if (FoxyProxy.apiDisabled)
        alert("I cannot change your FoxyProxy mode because the FoxyProxy API is disabled on your system.");
        else
        FoxyProxy.setMode("disabled", {
        success: function(newMode) {
        alert("Cool. Your mode is now changed to " + newMode);
      },
      error: function(msg) {
      alert("Error: " + msg);
    },
    rejected: function rejectedByUser() {
    // User didn't allow us to make changes to FoxyProxy
    alert("Please allow me to change the FoxyProxy mode. Please try again and click the 'Allow' button.");
    }   
    });
    

getProxyConfigs()

Requires Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6 or greater

NameDescriptionSinceRequires
getProxyConfigs(notificationCallback)Gets the ProxyConfigs object, but only if the user permits it and apiDisabled is
false
. With the ProxyConfigs object, you can add, edit, and delete individual ProxyConfig objects. If the user permits this call, the ProxyConfigs object is handed to you in the success() function of the notificationCallback.
Basic: 2.6
Standard: 3.6
Plus: 4.6
Gecko 9+ (Firefox 9+, Thunderbird 9+, SeaMonkey 2.6+)

Examples

Set the Current Mode


        if (typeof(FoxyProxy) == "undefined")
        alert("Please install FoxyProxy Basic 2.6+, Standard 3.6+, or Plus 4.6+");
        else if (FoxyProxy.apiDisabled)
        alert("I cannot change FoxyProxy because the FoxyProxy API is disabled on your system.");
        else
        FoxyProxy.getProxyConfigs({
        success: function(proxyConfigs) {
        alert("Cool. Your mode is now changed to " + newMode);
      },
      error: function(msg) {
      alert("Error: " + msg);
    },
    rejected: function rejectedByUser() {
    // User didn't allow us to make changes to FoxyProxy
    alert("Please allow me to change FoxyProxy. Please try again and click the 'Allow' button.");
    }   
    });