Microsoft Internet Security and
Acceleration Server 2000
Causes the Web proxy to retrieve an object and store it in the
The Web proxy normally fetches objects from the Internet and
caches them automatically as clients request them (passive
caching). In addition, the Web proxy will automatically keep
certain popular objects "fresh" within its cache by fetching them
itself (active caching). However, there are occasions when an
application needs a mechanism to override these automatic
operations. The override lets the application exercise greater
control either over the source of objects that are placed into the
cache or the time they are to remain there. The FetchURL
method allows you this greater degree of control.
To delete an object from the cache, set lpszFetchUrl =
<empty string>, and lpszCacheUrl = <cachedURL>. When
you delete an object by using FetchUrl, you can perform the
operation synchronously or asynchronously, and the Time to Live
(TTL) must be set to 0.
BSTR lpszFetchUrl, BSTR lpszCacheUrl, long lTtlInMinutes, FpcFetchURLFlags lFlags);
Note to C++ Programmers
The method returns an HRESULT to indicate success or
failure. If the result is an error, the error code portion of the
HRESULT (the low 16 bits of the value) may be a value
defined by Microsoft® Win32®, WinInet (Microsoft Win32 Internet
functions), or Windows Sockets (Winsock).
String that specifies the URL of the object to be fetched. The
URL may be any combination of protocol, domain, and path that the
Web proxy would normally be able to access. The Web proxy currently
supports the HTTP, FTP, and gopher protocols. If
lpszFetchUrl is an empty string then the FetchUrl
method removes the value in lpszCacheUrl from the
String that specifies the URL that clients use to retrieve the
fetched object from the Web proxy's cache. The URL must include one
of the protocols supported by the Web proxy (http:// or ftp://),
but the domain specified need not be accessible from the ISA server
computer. This is because the data itself will have been read from
the URL specified in the lpszFetchUrl parameter. The
lpszCacheUrl parameter can be the same as the
Long value that specifies the TTL, in minutes, that the object
should be served from the Web proxy cache. After the TTL has
passed, the object has "expired" and the Web proxy will not return
it again to requesting clients unless the Web proxy first verifies
that the object has not changed. In general, the application that
calls FetchUrl needs to set a TTL large enough to ensure
that the object will not expire before the application next
refreshes it. Note that ISA can delete both fresh and expired
objects from the cache if the cache directories become full.
This parameter is ignored unless the lFlags parameter
includes either the fpcFetchTtlIfNone or fpcFetchTtlOverride flag.
If neither flag is specified, the Web proxy's normal TTL
computation mechanism is used for the object.
Long value that specifies a set of bit flags to control the TTL
of the object in the Web proxy's cache:
Use the lTtlInMinutes flag to set the TTL for the object
regardless of any "Expires" or "Cache-Control: max-age" HTTP header
that the publishing Web server may have included with the object.
Be careful when overriding a TTL for objects that another party
authored; overriding may cause objects to be cached longer than
their intended lifetimes.
The lTtlInMinutes flag is used to set the TTL for the
object unless the publishing Web server has supplied an "Expires"
or "Cache-Control: max-age" HTTP header.
If you have set neither of these flags, the Web proxy uses its
normal TTL computation mechanism for the object, which uses an
"Expires" or "Cache-Control: max-age" HTTP header if available.
Otherwise, the Web proxy estimates a good TTL value based on the
time that has elapsed since the object was last modified.
In addition to the preceding flags, you can set one or more of
the following flags:
This function does not return to the caller until the fetch has
completed and you have stored the object in the cache, or until an
error occurs in the processing of the request. Such an error ends
the operation. If you do not specify this flag, the function
returns immediately and the fetch completes asynchronously to the
caller, in which case it is not possible to determine whether the
fetch completed successfully.
If the ISA server is a member of an array, store this object in
the cache of this particular proxy even if the normal array
cache-sharing mechanism, the Cache Array Routing Protocol (CARP),
indicates that the object should be cached on a different array
member. If you do not specify this flag, the object is
automatically cached on the array member that the CARP algorithm
designates. This flag is ignored if the ISA server is not a member
of an array. This flag therefore applies only to an array in ISA
Server Enterprise Edition. It does not apply to a stand-alone
server, or to ISA Server Standard Edition.
Cache the object even if the caching rules in the HTTP
specification normally prohibit this object from being cached; for
example, if the object contains a "Cache-Control: no-cache" HTTP
header or the response indicates a server error. Be careful when
using this flag for objects that were authored by another party.
There is often a good reason why the data could not be cached and
caching it might cause the site to function improperly or might
even be a violation of your license agreement for use of the data.
If the sCacheUrl parameter contains a question mark, this
flag alone will not allow the object to be cached. Use the FPCCacheConfiguration.CacheQuestionUrls
property to enable caching URLs containing question marks.
To retrieve a Hypertext Transfer Protocol (HTTP) object in
response to a FetchUrl call, the Web proxy service uses the
normal HTTP GET method to the URL specified by
lpszFetchUrl. If there is already a cached copy (which was
either loaded into the proxy previously by normal operations or by
an earlier call to FetchUrl) of the URL specified by
lpszCacheUrl, the proxy will include an "If-Modified-Since"
HTTP header in the request (also known as a conditional
GET). The response to a conditional GET may be either a new
copy of the data, which will be stored in the cache, or an HTTP
status code 304 "Not Modified" response, which will cause the proxy
to extend the TTL of the object without changing the contents of
the data in the cache.
To delete an object from the cache, set lpszFetchUrl
=<empty string>, and lpszCacheUrl = <cachedURL>. When
you delete an object using FetchUrl, you can perform the
operation synchronously or asynchronously, and the TTL must be set
The DeleteURL VBScript provided with ISA in the folder
SDK\samples\admin\scripts, demonstrates how to delete a cached
Note ERROR_INTERNET_UNABLE_TO_CACHE_FILE (decimal
value 12158, hex value 2f7e) is a new value that is not present in
all versions of WinInet
include files. This error code is returned if the HTTP headers in
the object or other factors prohibited the proxy from caching the
object. The caller may still be able to force the object into the
cache using the fpcFetchForceCache flag.