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

ndling Structures with Variable Size formation

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

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

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

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.

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

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.