CreateUrlCacheGroup

This function creates a group in the Content cache container.

Declaration

GROUPID 
CreateUrlCacheGroup (
    DWORD dwFlags, 
    LPVOID lpReserved);

Parameters

The dwFlags argument varies the behaviour of the function and may specify the behaviour of the created group. The following bits are permitted:

The lpReserved argument must be NULL.

Return Value

If successful, the function returns a non-zero 64-bit identifier for the created group. The function returns 0 to indicate failure. An error code can be retrieved by calling GetLastError.

Behaviour

If any invalid bit is set in dwFlags or if lpReserved is not NULL, the function fails.

If URL caching is not yet initialised, it gets initialised as part of this function. Among other things, this involves loading the registry configuration of all cache containers in the applicable registry set and creating default groups in the Content container. If this initialisation fails, so too does the function.

This function works only with the Content container of the applicable registry set. If no Content container has been loaded, the function fails. The function also fails if it cannot secure its use of the Content container.

The CACHEGROUP_FLAG_GIDONLY bit in dwFlags has precedence. If it is set, the function is not to go as far as creating a group but is instead to stop just at obtaining a group identifier as if for a new group. In practice, this cannot fail. If no group identifier has yet been allocated for this Content container (from previous calls to this function), then the current system time is saved as a FILETIME in the container file’s header. Subsequently, this saved FILETIME is incremented for each new allocation. The group identifier is the 64 bits of this saved FILETIME but with the high 4 bits cleared.

Without the CACHEGROUP_FLAG_GIDONLY bit in dwFlags, the function must find a free GROUP_ENTRY structure in the container file, or create one. Failure at this is failure for the function. Having found a free GROUP_ENTRY structure, the function obtains a group identifier as above, except that if the CACHEGROUP_FLAG_NONPURGEABLE bit is set in dwFlags, the group identifier gets its 0x1000000000000000 bit set. Both the newly allocated group identifier and the given dwFlags are saved in the GROUP_ENTRY, which is then the persistent record of the newly created group. In all future use of the group, non-purgeability is determined by the flag in the group identifier, not by the bit that is saved from the dwFlags argument.

Usage Notes

Once a group is created with this function, additional properties can be set for it through the SetUrlCacheGroupAttribute function and URL entries can be assigned to the group by calling SetUrlCacheEntryGroup. Note that a URL entry can be assigned to multiple groups. To delete a group, call DeleteUrlCacheGroup.

The point to a sticky group, as created by specifying CACHEGROUP_FLAG_NONPURGEABLE, is that URL entries automatically become sticky (in the sense that their cache entry type acquires the STICKY_CACHE_ENTRY flag) when assigned to a sticky group.

The Content container has one group created by default (internally, without using this function) as an essential part of initialising URL caching. This built-in group is sticky. It is semi-documented, its group ID being declared symbolically in WININETI.H as CACHEGROUP_ID_BUILTIN_STICKY.

Availability

The CreateUrlCacheGroup function is exported by name from WININET.DLL version 4.71 and higher. It has long been documented. Note however that the documentation omits to mention that CACHEGROUP_FLAG_NONPURGEABLE is accepted.

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