Microsoft Internet Security and Acceleration Server 2004 SDK

IFPCCacheContents::FetchUrl[C++]

FPCCacheContents.FetchUrl [Visual Basic]

[C++]

The FetchUrl method causes the ISA Server Web proxy to retrieve an object and store it in the cache.

The ISA Server Web proxy normally fetches objects from the Internet and caches them automatically as clients request them (passive caching). In addition, the Web proxy automatically keeps certain popular objects fresh within its cache by fetching them (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 FetchUrl to an empty string, and set CacheUrl to the URL of the object to remove from the cache. 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.

HRESULT FetchUrl(
  BSTR FetchUrl,
  BSTR CacheUrl,
  long TtlInMinutes,
  FpcFetchUrlFlags Flags
);

Parameters

FetchUrl
[in] String value 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 FetchUrl is set to an empty string, the FetchUrl method removes the object specified by the value in CacheUrl from the cache.
CacheUrl
[in] String value that specifies the URL that clients use to retrieve the fetched object from the 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 will have been read from the URL specified in the FetchUrl parameter. The CacheUrl parameter can be the same as the FetchUrl parameter.
TtlInMinutes
[in] A 32-bit integer that specifies the TTL, in minutes, during which the object should be served from the 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, an 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 Server can delete both fresh and expired objects from the cache if the cache directories become full.

This parameter is ignored unless the Flags 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.

Flags
[in] Bitmask of the FpcFetchUrlFlags enumerated type that specifies a set of bit flags to control the TTL of the object in the Web proxy's cache:
fpcFetchTtlOverride
Use the TtlInMinutes parameter 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 TtlInMinutes parameter 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
The method 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 method returns immediately and the fetch completes asynchronously to the caller, in which case it is not possible to determine whether the fetch completed successfully.
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 CacheUrl parameter contains a question mark, this flag alone will not allow the object to be cached.

Return Values

This method returns S_OK if the call is successful; otherwise, it returns an error code. If an error is returned, the error code portion of the HRESULT (the low 16 bits of the value) may be a value defined by the Windows Internet (WinINet) API or Windows Sockets (Winsock).

Remarks

To retrieve an HTTP object in response to a FetchUrl call, the Web proxy uses the normal HTTP GET method to the URL specified by FetchUrl. If there is already a cached copy (which was either loaded into the proxy server previously by normal operations or by an earlier call to FetchUrl) of the URL specified by CacheUrl, the Web proxy will include an If-Modified-Since header in the request (such a request is known as a conditional GET request). The response to a conditional GET may be either a new copy of the data, which will be stored in the cache, or a 304 (Not Modified) response, which will cause the Web 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 FetchUrl to an empty string, and set CacheUrl to the URL of the object to remove from the cache. 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 Server 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 the WinINet API include files. This error code is returned if the HTTP headers in the object or other factors prohibited the Web proxy from caching the object. The caller may still be able to force the object into the cache using the fpcFetchForceCache flag.

[Visual Basic]

The FetchUrl method causes the ISA Server Web proxy to retrieve an object and store it in the cache.

The ISA Server Web proxy normally fetches objects from the Internet and caches them automatically as clients request them (passive caching). In addition, the Web proxy automatically keeps certain popular objects fresh within its cache by fetching them (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 FetchUrl to an empty string, and set CacheUrl to the URL of the object to remove from the cache. 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.

Sub FetchUrl( _
  ByVal FetchUrl As String, _
  ByVal CacheUrl As String, _
  ByVal TtlInMinutes As Long, _
  ByVal Flags As FpcFetchUrlFlags _
)

Parameters

FetchUrl
[in] String value 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 FetchUrl is set to an empty string, the FetchUrl method removes the object specified by the value in CacheUrl from the cache.
CacheUrl
[in] String value that specifies the URL that clients use to retrieve the fetched object from the 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 will have been read from the URL specified in the FetchUrl parameter. The CacheUrl parameter can be the same as the FetchUrl parameter.
TtlInMinutes
[in] A 32-bit integer that specifies the TTL, in minutes, during which the object should be served from the 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, an 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 Server can delete both fresh and expired objects from the cache if the cache directories become full.

This parameter is ignored unless the Flags 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.

Flags
[in] Bitmask of the FpcFetchUrlFlags enumerated type that specifies a set of bit flags to control the TTL of the object in the Web proxy's cache:
fpcFetchTtlOverride
Use the TtlInMinutes parameter 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 TtlInMinutes parameter 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
The method 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 method returns immediately and the fetch completes asynchronously to the caller, in which case it is not possible to determine whether the fetch completed successfully.
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 CacheUrl parameter contains a question mark, this flag alone will not allow the object to be cached.

Return Values

This method has no return values. If the call is unsuccessful, an error is raised that can be intercepted by using an error handler.

Remarks

To retrieve an HTTP object in response to a FetchUrl call, the Web proxy uses the normal HTTP GET method to the URL specified by FetchUrl. If there is already a cached copy (which was either loaded into the proxy server previously by normal operations or by an earlier call to FetchUrl) of the URL specified by CacheUrl, the Web proxy will include an If-Modified-Since header in the request (such a request is known as a conditional GET request). The response to a conditional GET may be either a new copy of the data, which will be stored in the cache, or a 304 (Not Modified) response, which will cause the Web 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 FetchUrl to an empty string, and set CacheUrl to the URL of the object to remove from the cache. 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 Server 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 the WinINet API include files. This error code is returned if the HTTP headers in the object or other factors prohibited the Web proxy from caching the object. The caller may still be able to force the object into the cache using the fpcFetchForceCache flag.

Requirements

Server: Requires Windows Server 2003 or Windows 2000.
Version: Requires Internet Security and Acceleration Server 2004.
Header: Declared in Msfpccom.idl.
Library: Use Microsoft Internet Security and Acceleration Server 2004 Administration Library.

See Also

FPCCacheContents