FPCCacheContents.FetchUrl Method

Causes the Web proxy to retrieve an object and store it in the cache.

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.

VBScript Syntax[VBScript]

FPCCacheContents.FetchUrl( lpszFetchUrl, lpszCacheUrl, lTtlInMinutes, lFlags )

C++ Syntax[C++]

HRESULT FetchUrl(
  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).

Parameters

lpszFetchUrl

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 cache.

lpszCacheUrl

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 lpszFetchUrl parameter.

lTtlInMinutes

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.

lFlags

Long value that specifies a set of bit flags to control the TTL of the object in the Web proxy's cache:

fpcFetchTtlOverride

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.

fpcFetchTtlIfNone

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:

fpcFetchSynchronous

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.

fpcFetchNoArrayRouting

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.

fpcFetchForceCache

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.

Remarks

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 to 0.

The DeleteURL VBScript provided with ISA in the folder SDK\samples\admin\scripts, demonstrates how to delete a cached object.

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.

Applies To

FPCCacheContents