
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.
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.
| ERROR_DISK_FULL | The cache storage is full. |
| ERROR_FILE_NOT_FOUND | The specified local file is not found. |
| 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.
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.
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.
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.
GROUPID CreateUrlCacheGroup (
IN DWORD dwFlags,
IN LPVOID lpReserved
);
Generates cache group identifications.
BOOL DeleteUrlCacheEntry(
IN LPCSTR lpszUrlName
);
Removes the file associated with the source name from the cache, if the file exists.
| ERROR_ACCESS_DENIED | The file is locked or in use. The entry will be marked and will be deleted when the file is unlocked. |
| ERROR_FILE_NOT_FOUND | The file is not in the cache. |
BOOLAPI DeleteUrlCacheGroup (
IN GROUPID GroupId,
IN DWORD dwFlags,
IN LPVOID lpReserved
);
Releases a GROUPID and any associated state in the cache index file.
BOOL FindCloseUrlCache(
IN HANDLE hEnumHandle
);
Closes the specified enumeration handle.
HANDLE FindFirstUrlCacheEntry (
IN LPCSTR lpszUrlSearchPattern,
OUT LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize
);
Begins the enumeration of the cache.
ERROR_INSUFFICIENT_BUFFER indicates that the size of lpFirstCacheEntryInfo as specified by lpdwFirstCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwFirstCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.
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.
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.
| 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. |
At the end of the enumeration, the application should call FindCloseUrlCache.
BOOL FindNextUrlCacheEntry(
IN HANDLE hEnumHandle,
OUT LPINTERNET_CACHE_ENTRY_INFO lpNextCacheEntryInfo,
IN OUT LPWORD lpdwNextCacheEntryInfoBufferSize
);
Retrieves the next entry in the cache.
| ERROR_INSUFFICIENT_BUFFER | The size of lpNextCacheEntryInfo as specified by lpdwNextCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwNextCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information. |
| ERROR_NO_MORE_ITEMS | The enumeration completed. |
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.
At the end of the enumeration, the application should call FindCloseUrlCache.
BOOL GetUrlCacheEntryInfo(
IN LPCSTR lpszUrlName,
IN LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
IN OUT LPDWORD lpdwCacheEntryInfoBufferSize
);
Retrieves information about a cache entry.
| ERROR_FILE_NOT_FOUND | The specified cache entry is not found in the cache. |
| 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. |
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.
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.
| ERROR_FILE_NOT_FOUND | The URL, after taking any cached redirections into account, was not found in the cache index. |
| ERROR_INSUFFICIENT_BUFFER | One or more of the buffers (lpCacheEntryInfo and lpszRedirectUrl) supplied was not large enough to hold the requested information. The size of the buffer needed will be returned to lpdwCacheEntryInfoBufSize and lpdwRedirectUrlSize. |
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.
If the buffer size is not sufficient, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and sets lpdwLen to the size necessary to contain all the information.
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.
| 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. |
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.
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.
| 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. |
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.
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.
| INTERNET_CACHE_GROUP_ADD | Adds the cache entry to the cache group. |
| INTERNET_CACHE_GROUP_REMOVE | Removes the entry from the cache group. |
A cache entry can belong to more than one cache group.
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.
| 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. |
| 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. |
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.
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.
BOOL UnlockUrlCacheEntryStream(
IN HANDLE hUrlCacheStream,
IN DWORD dwReserved
);
Closes the stream that has been retrieved using the RetrieveUrlCacheEntryStream function.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.