Persistent URL Cache Functions

Persistent URL Cache Functions


This section describes the functions used by applications that need persistent caching services. These 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 the data, and delete data.

The protocols implemented in Win32 Internet functions use the cache functions to provide persistent caching and offline 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.
CommitUrlCacheEntry
CreateUrlCacheEntry
CreateUrlCacheGroup
DeleteUrlCacheEntry
DeleteUrlCacheEntry
FindCloseUrlCache
FindFirstUrlCacheEntry
FindFirstUrlCacheEntryEx
FindNextUrlCacheEntry
FindNextUrlCacheEntryEx
GetUrlCacheEntryInfo
GetUrlCacheEntryInfoEx
ReadUrlCacheEntryStream
RetrieveUrlCacheEntryFile
RetrieveUrlCacheEntryStream
SetUrlCacheEntryGroup
SetUrlCacheEntryInfo
UnlockUrlCacheEntryFile
UnlockUrlCacheEntryStream

CommitUrlCacheEntry

BOOL CommitUrlCacheEntry(
    IN LPCSTR lpszUrlName,
    IN LPCSTR lpszLocalFileName,
    IN FILETIME ExpireTime,
    IN FILETIME LastModifiedTime,
    IN DWORD CacheEntryType,
    IN LPCBYTE lpHeaderInfo,
    IN DWORD dwHeaderSize,
    IN LPCSTR 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
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
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
Cache type bitmask. Currently, the cache entry type values have not been finalized, so this value does not serve a real purpose at this point, except for STICK_CACHE_ENTRY. Can be a combination of the following values:
COOKIE_CACHE_ENTRY
NORMAL_CACHE_ENTRY
OCX_CACHE_ENTRY
SPARSE_CACHE_ENTRY
STABLE_CACHE_ENTRY
STICKY_CACHE_ENTRY
TRACK_CACHE_ENTRY
TRACK_OFFLINE_CACHE_ENTRY
TRACK_ONLINE_CACHE_ENTRY
URLHISTORY_CACHE_ENTRY

The STICKY_CACHE_ENTRY type is used to make cache entries exempt from scavenging. The default exempt time for entries set using CommitUrlCacheEntry is one day. The exempt time can be changed using the SetUrlCacheEntryInfo function.

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 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, CommitUrlCacheEntry invokes cache cleanup to make space for this new file. If the cache entry already exists, the function overwrites the entry if it is not in use. An entry is in use when it has been retrieved with either RetrieveUrlCacheEntryStream or RetrieveUrlCacheEntryFile.

Clients who add entries to the cache should set the headers to at least "HTTP/1.0 200 OK\r\n\r\n"; otherwise, Microsoft Internet Explorer and other WinInet clients will disregard the entry.

CreateUrlCacheEntry

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

Creates a local file name for saving the cache entry corresponding to the source name and the file extension.

lpszUrlName
String value that contains the name of the URL. The string should not contain any escape characters.
dwExpectedFileSize
Unsigned long integer value that contains the 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
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 path of the created file.
dwReserved
Reserved; must be zero.

After CreateUrlCacheEntry is called, the application can write directly into the file in local storage. When the file is completely received, the caller should call CommitUrlCacheEntry to commit the entry in the cache.

CreateUrlCacheGroup

GROUPID CreateUrlCacheGroup (
    IN DWORD dwFlags,
    IN LPVOID lpReserved
);

Generates cache group identifications.

dwFlags
DWORD value that contains the flags to control the creation of the cache group. No flags are currently implemented. Must be set to zero.
lpReserved
Reserved. Must be set to NULL.

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.

DeleteUrlCacheGroup

BOOLAPI DeleteUrlCacheGroup (
    IN GROUPID GroupId,
    IN DWORD dwFlags,
    IN LPVOID lpReserved
);

Releases a GROUPID and any associated state in the cache index file.

GroupId
GROUPID value that is associated with the cache group to be released.
dwFlags
DWORD value containing the flags to control the cache group deletion. No flags are currently implemented. Must be set to zero.
lpReserved
Reserved. Must be set to NULL.

FindCloseUrlCache

BOOL FindCloseUrlCache(
    IN HANDLE hEnumHandle
);

Closes the specified enumeration handle.

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.

lpszUrlSearchPattern
Address of a string that contains the source name pattern to search for. Can be set to "cookie:" or "visited:" to enumerate the cookies and URL History entries in the cache. If this parameter is NULL, the function uses *.*.
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.

FindFirstUrlCacheEntry and FindNextUrlCacheEntry return variable size information. If ERROR_INSUFFICIENT_BUFFER is returned, the application should allocate a buffer of the size specified by lpdwFirstCacheEntryInfoBufferSize. For more information, see Appendix B: Using Buffers in the Win32 Internet Functions Overview.

FindFirstUrlCacheEntryEx

HANDLE FindFirstUrlCacheEntryEx (
    IN LPCSTR lpszUrlSearchPattern,
    IN DWORD dwFlags,
    IN DWORD dwFilter,
    IN GROUPID GroupId
    OUT LPINTERNET_CACHE_ENTRY_INFO  lpFirstCacheEntryInfo,
    IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize,
    OUT LPVOID lpGroupAttributes,
    IN OUT LPDWORD pcbGroupAttributes,
    IN LPVOID lpReserved
);

Starts a filtered enumeration of the cache.

lpszUrlSearchPattern
String value containing the search pattern. Search patterns are currently not supported, so the value must be set to NULL to indicate all entries with the matching GROUPID.
dwFlags
DWORD value containing the flags controlling the enumeration. No flags are currently implemented. Must be set to zero.
dwFilter
DWORD value that indicates the cache entry types that are allowed. Can be any combination of cache entry types:
NORMAL_CACHE_ENTRY Normal cache entry; can be deleted to recover space for new entries.
SPARSE_CACHE_ENTRY Not currently implemented.
STABLE_CACHE_ENTRY Not currently implemented.
STICKY_CACHE_ENTRY Not currently implemented.

The following list contains the values that indicate what is being cached. Can be one of the following values:
COOKIE_CACHE_ENTRY Cookie cache entry.
OCX_CACHE_ENTRY Not currently implemented.
URLHISTORY_CACHE_ENTRY Visited link cache entry.

GroupId
GROUPID value indicating the cache group to enumerate. Set the value to zero to enumerate all entries that are not grouped.
lpFirstCacheEntryInfo
Address of the buffer to hold the INTERNET_CACHE_ENTRY_INFO structure that the cache entry information will be stored in.
lpdwFirstCacheEntryInfoBufferSize
Address of a DWORD value that indicates the size of lpFirstCacheEntryInfo.
lpGroupAttributes
Must be set to NULL.
pcbGroupAttributes
Must be set to NULL.
lpReserved
Reserved. Must be set to NULL.

At the end of the enumeration, the application should call FindCloseUrlCache.

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

FindNextUrlCacheEntryEx

BOOLAPI FindNextUrlCacheEntryEx (
    IN HANDLE hEnumHandle,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
    IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize,
    OUT LPVOID lpGroupAttributes,
    IN OUT LPDWORD pcbGroupAttributes,
    IN LPVOID lpReserved
);

Finds the next cache entry in a cache enumeration started by FindFirstUrlCacheEntryEx.

hEnumHandle
HANDLE type value returned by FindFirstUrlCacheEntryEx, which started a cache enumeration.
lpFirstCacheEntryInfo
Address of the buffer to hold the INTERNET_CACHE_ENTRY_INFO structure that the cache entry information will be stored in.
lpdwFirstCacheEntryInfoBufferSize
Address of a DWORD value that indicates the size of the buffer.
lpGroupAttributes
Must be set to NULL.
pcbGroupAttributes
Must be set to NULL.
lpReserved
Reserved. Must be set to NULL.

At the end of the enumeration, the application should call FindCloseUrlCache.

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 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 contains the number of bytes copied to the buffer, or the required size of the buffer.

GetUrlCacheEntryInfo does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL http://example.com/example.htm#sample was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

GetUrlCacheEntryInfoEx

BOOL GetUrlCacheEntryInfoEx(
    IN LPCSTR lpszUrl,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
    IN OUT LPDWORD lpdwCacheEntryInfoBufSize,
    OUT LPSTR lpszReserved,
    IN OUT LPDWORD lpdwReserved,
    LPVOID lpReserved,
    DWORD dwFlags
);

Searches for the URL after translating any cached redirections that would be applied in offline mode by HttpSendRequest.

lpszUrl
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.
lpdwCacheEntryInfoBufSize
Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.
lpszReserved
Reserved. Must be set to NULL.
lpdwReserved
Reserved. Must be set to NULL.
lpReserved
Reserved. Must be set to NULL.
dwFlags
Reserved. Must be set to zero.

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.

If the buffer size is not sufficient, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and sets lpdwLen to the size necessary to contain all the information.

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, the variable contains the size of the actual buffer used or required. The caller should check the return value in this parameter. 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.

RetrieveUrlCacheEntryFile does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

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 automatically unlocks 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.

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 open for random access. Set the flag to TRUE to open the stream for random access.
dwReserved
Reserved; must be zero.

RetrieveUrlCacheEntryStream does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

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.

SetUrlCacheEntryGroup

BOOLAPI SetUrlCacheEntryGroup (
    IN LPCSTR lpszUrlName,
    IN DWORD dwFlags,
    IN GROUPID GroupId,
    IN LPBYTE pbGroupAttributes,
    IN DWORD cbGroupAttributes,
    IN LPVOID lpReserved
);

Adds entries to or removes entries from a cache group.

lpszUrlName
String value that contains the URL of the cached resource.
dwFlags
DWORD value that determines whether the entry is added to or removed from a cache group. Can be one of the following values:
INTERNET_CACHE_GROUP_ADD Adds the cache entry to the cache group.
INTERNET_CACHE_GROUP_REMOVE Removes the entry from the cache group.
GroupId
GROUPID value that indicates the cache group that the entry will be added to or removed from.
pbGroupAttributes
Must be set to NULL.
cbGroupAttributes
Must be set to zero.
lpReserved
Reserved. Must be set to NULL.

A cache entry can belong to more than one cache group.

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 characters.
lpCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure containing the values to be assigned to the cache entry designated by lpszUrlName.
dwFieldControl
Bitmask that indicates the members that are to be set. Can be a combination of the following values:
CACHE_ENTRY_ACCTIME_FC Sets the last access time.
CACHE_ENTRY_ATTRIBUTE_FC Sets the cache entry type.
CACHE_ENTRY_EXEMPT_DELTA_FC Sets the exempt delta.
CACHE_ENTRY_EXPTIME_FC Sets the expire time.
CACHE_ENTRY_HEADERINFO_FC Sets the header info.
CACHE_ENTRY_HITRATE_FC Sets the hit rate.
CACHE_ENTRY_MODTIME_FC Sets the last modified time.
CACHE_ENTRY_SYNCTIME_FC Sets the last sync time.

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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.