Share via

FetchUrl Method of the IFPCCacheContents Interface

  • Article

The FetchUrl method causes the Forefront TMG Web proxy to retrieve an object and store it in the cache. This method can also be used to delete an object from the cache.
The Forefront TMG Web proxy normally fetches objects from the Internet and caches them automatically as clients request them (passive 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.

C++

Syntax

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

Parameters

  • FetchUrl
    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 Forefront TMG Web proxy currently supports the HTTP and FTP 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
    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 (https:// or ftp://), but the domain specified need not be accessible from the Forefront TMG 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
    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 Forefront TMG can delete both fresh and expired objects from the cache if the disk space allocated for caching on the cache drives becomes 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
    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 neither the ffpcFetchTtlOverride or fpcFetchTtlIfNone flag is set, 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 flag is obsolete.

    • fpcFetchNoArrayRouting
      Store the object in the cache of the Forefront TMG computer on which the method is called even if the Cache Array Routing Protocol (CARP) is enabled and indicates that the object should be cached on a different array member. If CARP is enabled and this flag is not set, the object is automatically cached on the array member that the CARP algorithm designates. This flag applies only to arrays with two or more Forefront TMG computers.

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

    • fpcFetchDynamicCache
      Cache the object even if the CacheUrl parameter contains a question mark and the response contains a header that normally prohibits the object from being cached according to the HTTP specification.

Return Value

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

Visual Basic

Syntax

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

Parameters

  • FetchUrl
    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 Forefront TMG Web proxy currently supports the HTTP and FTP 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
    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 (https:// or ftp://), but the domain specified need not be accessible from the Forefront TMG 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
    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 Forefront TMG can delete both fresh and expired objects from the cache if the disk space allocated for caching on the cache drives becomes 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
    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 neither the ffpcFetchTtlOverride or fpcFetchTtlIfNone flag is set, 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 flag is obsolete.

    • fpcFetchNoArrayRouting
      Store the object in the cache of the Forefront TMG computer on which the method is called even if the Cache Array Routing Protocol (CARP) is enabled and indicates that the object should be cached on a different array member. If CARP is enabled and this flag is not set, the object is automatically cached on the array member that the CARP algorithm designates. This flag applies only to arrays with two or more Forefront TMG computers.

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

    • fpcFetchDynamicCache
      Cache the object even if the CacheUrl parameter contains a question mark and the response contains a header that normally prohibits the object from being cached according to the HTTP specification.

Return Value

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

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.

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 be removed 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.

Requirements

Client Requires Windows 7 or Windows Vista.
Server Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2.
Version Requires Forefront Threat Management Gateway (TMG) 2010.
IDL

Declared in Msfpccom.idl.
DLL

Requires Msfpccom.dll.

See Also

FPCCacheContents

Send comments about this topic to Microsoft

Build date: 6/30/2010