public interface PacHelperMethodsMicrosoft
PacHelperMethodsNetscape
).
The JavaScript helper functions are defined in Java terms by this interface. The Java methods are named exactly as their JavaScript counterparts.
Microsoft has added these methods in recognition that the original Netscape functions were defined at a time before IPv6 became widely used or was even finalized. The original Netscape functions simply didn't take IPv6 into account and should therefore be interpreted in an IPv4-only context. Support for these new functions were first introduced in Internet Explorer v7. Other browsers, e.g. Chrome, have since then implemented them too.
Microsoft also defined a new entry-point function, FindProxyForURLEx(url, host)
,
which should replace the legacy FindProxyForURL(url, host)
function.
Microsoft only makes the new helper functions available from this new entry
function. However, Chrome does it differently in that the new helper
functions are indeed available, but there's no support for the new entry function,
FindProxyForURLEx
, meaning the new helper functions are
available from the old entry method, FindProxyForURL
.
An implementation of PacScriptEvaluator
should strive for maximum
compatibility meaning all helper functions should be available regardless
of entry point.
Modifier and Type | Method and Description |
---|---|
String |
dnsResolveEx(String host)
Resolves the given host name into its address or addresses.
|
String |
getClientVersion()
Gets the version of the PAC script processing engine.
|
boolean |
isInNetEx(String host,
String ipPrefix)
True if the IP address of the host matches the specified IP address
pattern.
|
boolean |
isResolvableEx(String host)
Tries to resolve the hostname.
|
String |
myIpAddressEx()
Returns the IP addresses the local host is known by.
|
String |
sortIpAddressList(String ipAddressList)
Sorts a list of IP addresses in ascending order.
|
boolean isResolvableEx(String host)
isResolvable()
, this function supports
both IPv4 and IPv6 addresses, meaning it should return true
if the
input can be resolved to any type of IP address.
Examples of usage from JavaScript:
isResolvable("www.netscape.com") is true (unless DNS fails to resolve it due to a firewall or some other reason). isResolvable("bogus.domain.foobar") is false.
host
- String dnsResolveEx(String host)
Example of usage from JavaScript:
dnsResolveEx("testmachine1"); returns the string "2001:4898:28:7:982d:a3b3:97ad:7dd0;192.168.1.99"
host
- String myIpAddressEx()
Example of usage from JavaScript:
myIpAddressEx() would return the string "2001:4898:28:7:982d:a3b3:97ad:7dd0;198.95.249.79" if you were running the application on that host.
String sortIpAddressList(String ipAddressList)
Example of usage from JavaScript:
sortIpAddressList("10.2.3.9;2001:4898:28:3:201:2ff:feea:fc14;::1;127.0.0.1;::9"); returns "::1;::9;2001:4898:28:3:201:2ff:feea:fc14;10.2.3.9;127.0.0.1";
NOTE: Microsoft Internet Explorer 11 (tested on 11.608.15063.0) doesn't
give correct results on this function. For example the result of
sortIpAddressList("10.2.3.9;2001:4898:28:3:201:2ff:feea:fc14;::1;127.0.0.1;::9")
is
"[::1];10.2.3.9;127.0.0.1;[2001:4898:28:3:201:2ff:feea:fc14];[::9]"
which is incorrect in more ways than one. In contrast, Chrome does it as
expected and as in the example above. In summary the following problems
are seen with the IE 11 implementation of this function:
fe80::5efe:157.59.139.22
doesn't seem to be working. This is strange as it is used in the
example in Microsoft's own documentation.
Such an IP literal seems to throw an error which means
the PAC script will not return a result, which means IE will choose
its default option, namely "DIRECT".
"1080:0:0:0:8:800:200c:417a"
in the input will become
"[1080:0:0:0:8:800:200c:417a]"
in the output.
This too is in contrast to the documentation.
ipAddressList
- a semi-colon delimited string containing IP addressesString getClientVersion()
Microsoft added this function to allow IT administrators to update their PAC scripts to use different versions of the PAC processing engine without causing breaks to their existing deployment. For example, if Microsoft added a function to the 2.0 version of the the Microsoft PAC processing engine, then administrators can check the version before attempting to call that function. This allows their script to work with client running versions 1.0 and 2.0 of the engine.
Note to implementers: Currently this function should simply return "1.0" in order retain compatibility with Microsoft world.
boolean isInNetEx(String host, String ipPrefix)
Microsoft's documentation is vague / contradictory on what the pattern
argument, ipPrefix
, is, meaning is it a list of patterns
or is it a singular pattern?. We err on the side of caution and decide that
the ipPrefix
is a semi-colon separated list of patterns and that
the method must return true
if the supplied ipAddress
matches any of the patterns in the list.
Similarly, the interpretation of the first argument, host
,
is open for discussion. In the sibling function, isInNet
, it
is clearly stated that this argument can be either a host name or a
literal IP address. But Microsoft's documentation on isInNetEx
limits the argument to only being a literal IP address. Again we err
on the side of caution and decide that this argument can be either. If
it is a host name then the method must do a name service lookup first
(to convert to IP), before the actual comparison can begin.
Examples of usage from JavaScript:
isInNetEx(ipAddress, "198.95.249.79/32"); true if the IP address of host matches exactly 198.95.249.79 isInNetEx(ipAddress, "198.95.0.0/16"); true if the IP address of the host matches 198.95.*.* isInNetEx(ipAddress, "3ffe:8311:ffff/48"); true if the IP address of the host matches 3ffe:8311:fff:*:*:*:*:* isInNetEx(ipAddress, "198.95.249.0/24;198.122.0.0/16"); true if the IP address of host matches 198.95.249.* or matches 198.122.*.*
host
- a string containing an IPv6/IPv4 addresses or a host name.ipPrefix
- a string containing semi-colon delimited IP prefixes with
top n bits specified in the bit field
(i.e. 3ffe:8311:ffff::/48 or 123.112.0.0/16).true
if the IP address matches the specified IP address
pattern ({code ipPrefix}). Also returns false
if the prefix
is not in the correct format or if addresses and prefixes of different
types are used in the comparison (i.e. IPv4 prefix and an IPv6 address).