Edit

Share via

CommitUrlCacheEntryA function (wininet.h)

  • Article

Stores data in the specified file in the Internet cache and associates it with the specified URL.

Syntax

BOOL CommitUrlCacheEntryA(
  [in] LPCSTR   lpszUrlName,
  [in] LPCSTR   lpszLocalFileName,
  [in] FILETIME ExpireTime,
  [in] FILETIME LastModifiedTime,
  [in] DWORD    CacheEntryType,
  [in] LPBYTE   lpHeaderInfo,
  [in] DWORD    cchHeaderInfo,
  [in] LPCSTR   lpszFileExtension,
  [in] LPCSTR   lpszOriginalUrl
);

Parameters

[in] lpszUrlName

Pointer to a string variable that contains the source name of the cache entry. The name string must be unique and should not contain any escape characters.

[in] lpszLocalFileName

Pointer to a string variable that contains the name of the local file that is being cached. This should be the same name as that returned by CreateUrlCacheEntryA.

[in] ExpireTime

FILETIME structure that contains the expire date and time (in Greenwich mean time) of the file that is being cached. If the expire date and time is unknown, set this parameter to zero.

[in] LastModifiedTime

FILETIME structure that contains the last modified date and time (in Greenwich mean time) of the URL that is being cached. If the last modified date and time is unknown, set this parameter to zero.

[in] CacheEntryType

A bitmask indicating the type of cache entry and its properties. The cache entry types include: history entries (URLHISTORY_CACHE_ENTRY), cookie entries (COOKIE_CACHE_ENTRY), and normal cached content (NORMAL_CACHE_ENTRY).

This parameter can be zero or more of the following property flags, and cache type flags listed below.

Value Meaning
COOKIE_CACHE_ENTRY
 Cookie cache entry.
EDITED_CACHE_ENTRY
 Cache entry file that has been edited externally. This cache entry type is exempt from scavenging.
NORMAL_CACHE_ENTRY
 Normal cache entry; can be deleted to recover space for new entries.
SPARSE_CACHE_ENTRY
 Partial response cache entry.
STICKY_CACHE_ENTRY
 Sticky cache entry; exempt from scavenging.
TRACK_OFFLINE_CACHE_ENTRY
 Not currently implemented.
TRACK_ONLINE_CACHE_ENTRY
 Not currently implemented.
URLHISTORY_CACHE_ENTRY
 Visited link cache entry.

[in] lpHeaderInfo

Pointer to the buffer that contains the header information. If this parameter is not NULL, the header information is treated as extended attributes of the URL that are returned in the lpHeaderInfo member of the INTERNET_CACHE_ENTRY_INFO structure.

[in] cchHeaderInfo

Size of the header information, in TCHARs. If lpHeaderInfo is not NULL, this value is assumed to indicate the size of the buffer that stores the header information. An application can maintain headers as part of the data and provide cchHeaderInfo together with a NULL value for lpHeaderInfo.

[in] lpszFileExtension

This parameter is reserved and must be NULL.

[in] lpszOriginalUrl

Pointer to a string that contains the original URL, if redirection has occurred.

Return value

Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. The following are possible error values.

Return code Description
ERROR_DISK_FULL
 The cache storage is full.
ERROR_FILE_NOT_FOUND
 The specified local file is not found.

Remarks

The STICKY_CACHE_ENTRY type is used to make cache entries exempt from scavenging. The default exempt time for entries set using CommitUrlCacheEntryA is ten minutes. The exempt time can be changed by setting the expires time parameter in the INTERNET_CACHE_ENTRY_INFO structure in the call to the SetUrlCacheEntryInfo function.

If the cache storage is full, CommitUrlCacheEntryA 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 that 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 client applications should disregard the entry.

See Caching for example code calling CreateUrlCacheEntryA.

Like all other aspects of the WinINet API, this function cannot be safely called from within DllMain or the constructors and destructors of global objects.

Note  WinINet does not support server implementations. In addition, it should not be used from a service. For server implementations or services use Microsoft Windows HTTP Services (WinHTTP).
 

Note

The wininet.h header defines CommitUrlCacheEntry as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header wininet.h
Library Wininet.lib
DLL Wininet.dll

See also

Caching

WinINet Functions