PerformOperationOverUrlCacheA

This function enumerates a URL cache container, calling an arbitrary function for each entry that matches the given search criteria.

Declaration

BOOL 
PerformOperationOverUrlCacheA (
    LPCSTR lpszUrlSearchPattern, 
    DWORD dwFlags, 
    DWORD dwFilter, 
    GROUPID GroupId, 
    LPVOID lpGroupAttributes, 
    LPDWORD lpcbGroupAttributes, 
    LPVOID lpReserved
    CACHE_OPERATOR op,
    PVOID pOperatorData);

Since the CACHE_OPERATOR type appears to be used nowhere else, it is as well given here:

typedef 
BOOL 
(*CACHE_OPERATOR) (
    INTERNET_CACHE_ENTRY_INFOA *pcei, 
    PDWORD pcbcei, 
    PVOID pOpData);

Parameters

The lpszUrlSearchPattern, dwFlags, dwFilter, GroupId, lpGroupAttributes, lpcbGroupAttributes and lpReserved arguments are exactly as for the FindFirstUrlCacheEntryEx function. The first four arguments specify search criteria. The last three are reserved: two are ignored and the last must be NULL.

The op argument provides the address of the callback function.

The pOperatorData argument provides a caller-specific context to be passed on each invocation of the callback function.

Return Value

The function returns TRUE if successful, else FALSE.

Behaviour

This is a utility function that conveniently wraps up the work of enumerating a URL cache container. Thus, it calls FindFirstUrlCacheEntryEx to prepare the enumeration, follows with however many calls to FindNextUrlCacheEntryEx are needed to see the enumeration to its end, and finishes with FindCloseUrlCache. The initial buffer for receiving information about URL entries is 0x0450 bytes, apparently chosen as 0x50 for the INTERNET_CACHE_ENTRY_INFO structure and a round-number allowance of 1KB for the variable-sized data that may follow this structure. Whenever a first call to find the next URL entry fails with ERROR_INSUFFICIENT_MEMORY as the error code, the buffer is replaced by a larger one, increasing always by as many whole multiples of 1KB as needed to cover the size that the called function suggested, and the call is repeated. Failure of a first call for any other reason, or of a second call for any reason, or of any request for memory, ends the enumeration.

On each successful attempt at finding another URL entry, the function notifies the caller, at the address given by the op argument. This callback function receives three arguments:

• the address of information about the URL entry;
• the address of a dword that gives the size, in bytes, of the information;
• the arbitrary context that the caller provided as the pOperatorData argument.

Why the size is passed by address is unclear: any change the callback function makes to it is ignored. The callback function returns FALSE to end the enumeration (prematurely). It seems expected that the callback function should set an error code. Certainly, if the callback function ends the enumeration but wants the PerformOperationOverUrlCacheA function to succeed, it should set ERROR_NO_MORE_ITEMS as the last error code. If the callback function returns anything other than FALSE, the PerformOperationOverUrlCacheA function looks for another entry.

The function succeeds or fails according to whether the enumeration appears to have completed, such that the last error code is ERROR_NO_MORE_ITEMS. (Although the coding does not check FindCloseUrlCache for success, it does depend on this call not to set a last error code if succeeding.)

Availability

The PerformOperationOverCacheEntryA function is exported as ordinal 103 from WININET version 5.0 and higher. Though it is not documented, it is declared in an SDK header file, named WININETI.H, and this article (more or less) follows that declaration’s nomenclature.

Though the function is exported, its only known use by Microsoft is internal to WININET, specifically when moving the Content container.

The behaviour described in this note is of version 7.0 from the original Windows Vista.