## Persistent URL Cache Functions

This section describes the functions used by clients that need persistent caching services. The functions allow an application to save data in the local file system for subsequent use, such as in situations where access to the data is over a low bandwidth link, or the access is not available at all. The calling program that inserts data into the persistent cache assigns a source name that is used to do operations such as retrieve the data, set and get some properties on it, and delete it.

The protocols implemented in Win32 Internet functions use the cache functions to provide persistent caching and off-line browsing. Unless explicitly specified not to cache through the INTERNET_FLAG_NO_CACHE_WRITE flag, Win32 Internet functions cache all data downloaded from the network. The responses to POST data are not cached.

### Handling Structures with Variable Size Information

The cache may contain variable size information for each URL stored. This is reflected in the INTERNET_CACHE_ENTRY_INFO structure. When the cache functions return this structure, they create a buffer that is always the size of INTERNET_CACHE_ENTRY_INFO plus any variable-size information. If a pointer member is not NULL, it points to the memory area immediately after the structure. While copying the returned buffer from a function into another buffer, the pointer members should be fixed to point to the appropriate place in the new buffer, as the following example shows:

    lpDstCEInfo->lpszSourceUrlName =
        (LPINTERNET_CACHE_ENTRY_INFO) ((LPBYTE) lpSrcCEInfo +
    ((DWORD) (lpOldCEInfo->lpszSourceUrlName) - (DWORD) lpOldCEInfo))

Some cache functions fail with the ERROR_INSUFFICIENT_BUFFER error value if you specify a buffer that is too small to contain the cache-entry information retrieved by the function. In this case, the function also returns the required size of the buffer. You can then allocate a buffer of the appropriate size and call the function again. If you want the function to succeed on the first call, allocate a buffer of the size specified by the MAX_CACHE_ENTRY_INFO_SIZE value, and then set the dwStructSize member of the INTERNET_CACHE_ENTRY_INFO structure to MAX_CACHE_ENTRY_INFO_SIZE when calling the function.

### Cache APIs

#### CommitUrlCacheEntry

    BOOL CommitUrlCacheEntry(
        IN LPCSTR lpszUrlName,
        IN LPCTSTR lpszLocalFileName,
        IN FILETIME ExpireTime,
        IN FILETIME LastModifiedTime,
        IN DWORD CacheEntryType,
        IN LPCBYTE lpHeaderInfo,
        IN DWORD dwHeaderSize,
        IN LPCTSTR lpszFileExtension,
        IN DWORD dwReserved
        );

Caches data in the specified file in the cache storage and associates it with the given URL.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_FILE_NOT_FOUND | The specified local file is not found.
  ERROR_DISK_FULL | The cache storage is full.

lpszUrlName
  Address of a string that contains the source name of the cache entry. The name string must be unique, and should not contain any escape characters.
lpszLocalFileName
  Address of a string that contains the name of the local file that is being cached. This should be the same name as that returned by CreateUrlCacheEntry.
ExpireTime
  A FILETIME structure that contains the expire date and time (GMT) of the file that is being cached. If the expire date and time is unknown, set this parameter to zero.
LastModifiedTime
  A FILETIME structure that contains the last modified date and time (GMT) of the URL that is being cached. If the last modified date and time is unknown, set this parameter to zero.
CacheEntryType
  Type of the cache entry.
lpHeaderInfo
  Address of the header information. If this parameter is not NULL, the header information is treated as extended attributes of the URL and is returned back in the INTERNET_CACHE_ENTRY_INFO structure.
dwHeaderSize
  Size of the header information. If lpHeaderInfo is not NULL, this value is assumed to indicate the size of the header information. An application can maintain headers as part of the data and provide dwHeaderSize, together with a NULL value for lpHeaderInfo.
lpszFileExtension
  Address of a buffer that contains information maintained in the cache database for future use. In this version of Win32 Internet functions, this information is not used.
dwReserved
  Reserved; must be zero.

If the cache storage is full, the function invokes cache cleanup to make space for this new file. If the file size is bigger than the cache size, the function returns ERROR_DISK_FULL. If the cache entry already exists, the function overwrites the entry. The user could specify SPARSE_CACHE_ENTRY in the Commit to indicate that the size of the data is incomplete.

#### CreateUrlCacheEntry

    BOOL CreateUrlCacheEntry(
        IN LPCSTR lpszUrlName,
        IN DWORD dwExpectedFileSize,
        IN DWORD lpszFileExtension,
        OUT LPTSTR lpszFileName,
        IN DWORD dwReserved
    );

Allocates requested cache storage, and creates a local file name for saving the cache entry corresponding to the source name.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

lpszUrlName
  Address of a string that contains the name of the URL. The string should not contain any escape characters.
dwExpectedFileSize
  Expected size of the file needed to store the data corresponding to the source entity. If the expected size is unknown, set this value to zero.
lpszFileExtension
  Address of a string that contains an extension name of the file in the local storage.
lpszFileName
  Address of a buffer that receives the file name. The buffer should be large enough (MAX_PATH) to store the file path name of the created file.
dwReserved
  Reserved; must be zero.

Internet services that use the cache should call this function to write directly into the cache storage. The caller should indicate the expected size of the file, but it is not guaranteed. Once the file is completely received, the caller should call CommitUrlCacheEntry to commit the entry in the cache.

#### GetUrlCacheEntryInfo

    BOOL GetUrlCacheEntryInfo(
        IN LPCSTR lpszUrlName,
        IN LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
        IN OUT LPDWORD lpdwCacheEntryInfoBufferSize
    );

Retrieves information about a cache entry.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_INSUFFICIENT_BUFFER | The size of lpCacheEntryInfo as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.
  ERROR_FILE_NOT_FOUND | The specified cache entry is not found in the cache.

lpszUrlName
  Address of a string that contains the name of the cache entry. The name string should not contain any escape characters.
lpCacheEntryInfo
  Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about the cache entry.
lpdwCacheEntryInfoBufferSize
  Address of a variable that specifies the size of the lpszCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.

#### ReadUrlCacheEntryStream

    BOOL ReadUrlCacheEntryStream(
        IN HANDLE hUrlCacheStream,
        IN  DWORD dwLocation,
        IN OUT LPVOID lpBuffer,
        IN OUT LPDWORD lpdwLen,
        IN DWORD dwReserved
        );

Reads the cached data from a stream that has been opened using the RetrieveUrlCacheEntryStream function.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

hUrlCacheStream
  Handle that was returned by the RetrieveUrlCacheEntryStream function.
dwLocation
  Offset to read from.
lpBuffer
  Address of a buffer that receives the data.
lpdwLen
  Address of a variable that specifies the length of the lpBuffer buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.
dwReserved
  Reserved; must be zero.

#### RetrieveUrlCacheEntryFile

    BOOL RetrieveUrlCacheEntryFile(
        IN LPCSTR lpszUrlName,
        OUT LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
        IN OUT LPDWORD lpdwCacheEntryInfoBufferSize
        IN DWORD dwReserved
        );

Retrieves a cache entry from the cache in the form of a file.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_FILE_NOT_FOUND | The cache entry specified by the source name is not found in the cache storage.
  ERROR_INSUFFICIENT_BUFFER | The size of the lpCacheEntryInfo buffer as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to get all the information.

lpszUrlName
  Source name of the cache entry. This must be a unique name. The name string should not contain any escape characters.
lpCacheEntryInfo
  Address of a cache entry information buffer. If the buffer is not sufficient to accommodate all the information associated with the URL, one or more of the embedded pointers will be NULL.
lpdwCacheEntryInfoBufferSize
  Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, this variable contains the size of the actual buffer used or required. The caller should check the return value in this variable. If the return size is less than or equal to the size passed in, all the relevant data has been returned.
dwReserved
  Reserved; must be zero.

If an extension was provided while calling CommitUrlCacheEntry, the file will have the specified extension. If the entry is not available in the cache, this function returns ERROR_FILE_NOT_FOUND; otherwise, it returns the name of the local file. The caller is given only read permission to the local file, so the caller should not attempt to write or delete the file.

The file is locked for the caller when it is retrieved; the caller should unlock the file after it has been used up. The cache manager will automatically unlock the locked files after a certain interval. While the file is locked, the cache manager will not remove the file from the cache. It is important to note that this function may be efficient or expensive, depending on the internal implementation of the cache. For instance, if the URL data is stored in a packed file that contains data for other URLs, the cache will make a copy of the data to a file in a temporary directory maintained by the cache. The cache will eventually delete the copy. It is recommended that this function be used only in situations where a file name is needed to launch an application. RetrieveUrlCacheEntryStream and associated stream functions should be used in most cases.

#### RetrieveUrlCacheEntryStream

    HANDLE RetrieveUrlCacheEntryStream(
        IN LPCSTR lpszUrlName,
        OUT LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
        IN OUT LPDWORD lpdwCacheEntryInfoBufferSize,
        IN BOOL fRandomRead,
        IN DWORD dwReserved
        );

Provides the most efficient and implementation-independent way of accessing the cache data.

- Returns a valid handle for use in the ReadUrlCacheEntryStream and UnlockUrlCacheEntryStream functions if successful, or INVALID_HANDLE_VALUE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_FILE_NOT_FOUND | The cache entry specified by the source name is not found in the cache storage.
  ERROR_INSUFFICIENT_BUFFER | The size of lpCacheEntryInfo as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.

lpszUrlName
  Address of a string that contains the source name of the cache entry. This must be a unique name. The name string should not contain any escape characters.
lpCacheEntryInfo
  Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about the cache entry.
lpdwCacheEntryInfoBufferSize
  Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable receives the number of bytes copied to the buffer, or the required size of the buffer.
fRandomRead
  Flag to indicate whether the stream is opened for random access or not. Set the flag to TRUE to open the stream for random access.
dwReserved
  Reserved; must be zero.

Cache clients that do not need URL data in the form of a file should use this function to access the data for a particular URL.

#### SetUrlCacheEntryInfo

    BOOL SetUrlCacheEntryInfo(
        IN LPCSTR lpszUrlName,
        IN LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
        IN DWORD dwFieldControl
    );

Sets the specified members of the INTERNET_CACHE_ENTRY_INFO structure.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_FILE_NOT_FOUND | The specified cache entry is not found in the cache.
  ERROR_INVALID_PARAMETER | The value(s) to be set is invalid.

lpszUrlName
  Address of a string that contains the name of the cache entry. The name string should not contain any escape characters.
lpCacheEntryInfo
  Address of an INTERNET_CACHE_ENTRY_INFO structure.
dwFieldControl
  Bitmask that indicates the members that are to be set. Can be a combination of the following values:

  CACHE_ENTRY_ATTRIBUTE_FC |
  CACHE_ENTRY_HITRATE_FC |
  CACHE_ENTRY_MODTIME_FC |
  CACHE_ENTRY_EXPTIME_FC |
  CACHE_ENTRY_ACCTIME_FC |
  CACHE_ENTRY_SYNCTIME_FC |
  CACHE_ENTRY_HEADERINFO_FC |

  The last two flags have not been implemented in this release.

#### UnlockUrlCacheEntryFile

    BOOL UnlockUrlCacheEntryFile(
        IN LPCSTR lpszUrlName,
        IN DWORD dwReserved
        );

Unlocks the cache entry that was locked while the file was retrieved for use from the cache.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. ERROR_FILE_NOT_FOUND indicates that the cache entry specified by the source name is not found in the cache storage.

lpszUrlName
  Address of a string that contains the source name of the cache entry that is being unlocked. The name string should not contain any escape characters.
dwReserved
  Reserved; must be zero.

The application should not access the file after calling this function.

When this function returns, the cache manager is free to delete the cache entry.

#### UnlockUrlCacheEntryStream

    BOOL UnlockUrlCacheEntryStream(
        IN HANDLE hUrlCacheStream,
        IN DWORD dwReserved
    );

Closes the stream that has been retrieved using the RetrieveUrlCacheEntryStream function.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

hUrlCacheStream
  Handle that was returned by the RetrieveUrlCacheEntryStream function.
dwReserved
  Reserved; must be zero.

See also RetrieveUrlCacheEntryStream

### Cache Enumeration

#### DeleteUrlCacheEntry

    BOOL DeleteUrlCacheEntry(
        IN LPCSTR lpszUrlName
    );

Removes the file associated with the source name from the cache, if the file exists.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_FILE_NOT_FOUND | The file is not in the cache.
  ERROR_ACCESS_DENIED | The file is in use.

lpszUrlName
  Address of a string that contains the name of the source corresponding to the cache entry.

#### FindCloseUrlCache

    BOOL FindCloseUrlCache(
        IN HANDLE hEnumHandle
    );

Closes the specified enumeration handle.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

hEnumHandle
  Handle returned by a previous call to the FindFirstUrlCacheEntry function.

See also FindFirstUrlCacheEntry

#### FindFirstUrlCacheEntry

    HANDLE FindFirstUrlCacheEntry (
        IN LPCSTR lpszUrlSearchPattern,
        OUT LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
        IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize
    );

Begins the enumeration of the cache.

- Returns a handle that the application can use in the FindNextUrlCacheEntry function to retrieve subsequent entries in the cache. If the function fails, the return value is NULL. To get extended error information, call GetLastError. ERROR_INSUFFICIENT_BUFFER indicates that the size of lpCacheEntryInfo as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.

lpszUrlSearchPattern
  Address of a string that contains the source name pattern to search for. If this parameter is NULL, the function uses *.*. (In this version, only *.* semantics are implemented.)
lpFirstCacheEntryInfo
  Address of an INTERNET_CACHE_ENTRY_INFO structure.
lpdwFirstCacheEntryInfoBufferSize
  Address of a variable that specifies the size of the lpFirstCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.

This function and the FindNextUrlCacheEntry function return variable size information. In order to not have the enumeration terminate due to ERROR_INSUFFICIENT_BUFFER, an application should create one buffer of the size specified by the MAX_CACHE_ENTRY_INFO_SIZE value, and pass the address of the buffer repeatedly to all the enumeration functions. After the function succeeds, another buffer may be used of the size returned by lpdwCacheEntryInfoBufferSize to keep the returned information. Be careful to fix the pointer elements while copying the buffer.

See also FindNextUrlCacheEntry

#### FindNextUrlCacheEntry

    BOOL FindNextUrlCacheEntry(
        IN HANDLE hEnumHandle,
        OUT LPINTERNET_CACHE_ENTRY_INFO lpNextCacheEntryInfo,
        IN OUT LPWORD lpdwNextCacheEntryInfoBufferSize
    );

Retrieves the next entry in the cache.

- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:

  Value | Meaning
  ERROR_NO_MORE_FILES | The enumeration completed.
  ERROR_INSUFFICIENT_BUFFER | The size of lpCacheEntryInfo as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.

hEnumHandle
  Enumeration handle obtained from a previous call to FindFirstUrlCacheEntry.
lpNextCacheEntryInfo
  Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about cache entry.
lpdwNextCacheEntryInfoBufferSize
  Address of a variable that specifies the size of the lpNextCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.

See also FindFirstUrlCacheEntry

© 1996 Microsoft Corporation