Brought to you by the
RFC INDEX PAGE
Google
 

Microsoft Win32 Internet Programmer's Reference


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.

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.

lpszUrlName
Address of a string that contains the name of the URL. The string should not contain any escape character.
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.

lpszUrlName
Address of a string that contains the name of the cache entry. The name string should not contain any escape character.
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.

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.

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 RetrieveCacheEntryStream(
    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.

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.

lpszUrlName
Address of a string that contains the name of the cache entry. The name string should not contain any escape character.
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.

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.

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.

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.

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.

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.

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