Persistent URL Cache API

February 25, 1996

Version 1.05
© Microsoft Corporation 1995. All Rights Reserved.

NOTE: THIS DOCUMENT IS AN EARLY RELEASE OF THE FINAL SPECIFICATION. IT IS

MEANT TO SPECIFY AND ACCOMPANY SOFTWARE THAT IS STILL IN DEVELOPMENT.
SOME OF THE INFORMATION IN THIS DOCUMENTATION MAY BE INACCURATE OR MAY
NOT BE AN ACCURATE REPRESENTATION OF THE FUNCTIONALITY OF THE FINAL
SPECIFICATION OR SOFTWARE . MICROSOFT ASSUMES NO RESPONSIBILITY FOR ANY
DAMAGES THAT MIGHT OCCUR EITHER DIRECTLY OR INDIRECTLY FROM THESE
INACCURACIES . MICROSOFT MAY HAVE TRADEMARKS , COPYRIGHTS, PATENTS OR
PENDING PATENT APPLICATIONS, OR OTHER INTELLECTUAL PROPERTY RIGHTS
COVERING SUBJECT MATTER IN THIS DOCUMENT . THE FURNISHING OF THIS
DOCUMENT DOES NOT GIVE YOU A LICENSE TO THESE TRADEMARKS , COPYRIGHTS,
PATENTS, OR OTHER INTELLECTUAL PROPERTY RIGHTS.
Persistent URL Cache API

1. Overview
This document outlines the API used by clients that need persistent caching services. The APIs
allow the callers to save data in the local filesystem for subsequent use, such as in situations
where the accesses 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 which is
used to do operations like retrieve the data, set and get some properties on it and delete it.

2. Cache APIs

2.1 Structure Definitions

//
// cache entry type flags
//

#define NORMAL_CACHE_ENTRY 0x00000001

// Normal cache entry, may be deleted to recover space for new entries.
#define STABLE_CACHE_ENTRY 0x00000002
// stable cache entry such as graphic and audio/video files, may be deleted to recover
// space for the new entries only when there is no more NORMAL_CACHE_ENTRY.
#define STICKY_CACHE_ENTRY 0x00000004
// These entries will never be removed automatically by the cache management system.
#define SPARSE_CACHE_ENTRY 0x00010000
// indicate this cache entry is incomplete.
#define OCX_CACHE_ENTRY 0x00020000
// Special OCX type cache entry.

typedef struct _CACHE_ENTRY_INFO {

DWORD dwVersion; // version of cache system, ?? do we need this for all entries.
LPSTR lpszSourceUrlName; // embedded pointer to the URL name string.
LPTSTR% lpszLocalFileName; // embedded pointer to the local file name.
DWORD CacheEntryType; // cache type bit mask.
DWORD dwUseCount; // current users count of the cache entry.
DWORD dwHitRate; // number of times the cache entry was retrieved.
DWORD dwSizeLow; // low DWORD of the file size.
6/15/2019 6/15/20196/15/2019 2
 DWORD dwSizeHigh; // high DWORD of the file size.
FILETIME LastModifiedTime; // last modified time of this file in GMT format.
FILETIME ExpireTime; // expiration time of this file in GMT format.
FILETIME LastAccessTime; // last Accessed time in GMT format.
LPBYTE lpHeaderInfo; // embedded pointer to the header info
DWORD dwHeaderInfoSize; // size of the above header.
LPTSTR% lpszFileExtension; // File extension used to retrieve the data as a file.
DWORD dwReserved; // reserved for future use.
} CACHE_ENTRY_INFO, *LPCACHE_ENTRY_INFO;

2.2.1 CreateUrlCacheEntry
CreateUrlCacheEntry API will allocate requested cache storage and make a local file name that
will be used to save the cache entry corresponding to the source name. Internet services that
use the cache should call this API to write directly into the cache storage. The caller should
indicate the expected size of the file, but it is not guaranteed. Once the file is completely
received, the caller should call CommitUrlCacheEntry to commit the entry in the cache.

BOOL
WINAPI
CreateUrlCacheEntry(
IN LPCSTR lpszUrlName,
IN DWORD dwExpectedFileSize,
OUT LPTSTR lpszFileName,
IN DWORD dwReserved
);

Parameters:

lpszUrlName : Name of the . The name string should not contain any escape character.
dwExpectedFileSize : Expected size of the file needed to store the data corresponding to the
source entity. If the expected size is unknown then set this value to zero.
lpszFileName : Pointer to a file name buffer. The buffer should be (MAX_PATH) large enough to
store the file path name of the create file.
dwReserved : for future use.

Return Error Codes:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.
6/15/2019 6/15/20196/15/2019 3
2.2.2 CommitUrlCacheEntry
CommitUrlCacheEntry API caches data in the specified file in the cache storage and associates
it with the URL specified by lpszUrlName. If the storage is full then it invokes cache cleanup to
make space for this new file. If the file size is bigger than the cache size, the API returns
ERROR_DISK_FULL. If the cache entry already exists, the cache will overwrite it with this call.
The user could specify SPARSE_CACHE_ENTRY in the Commit to indicate to himself that the
size of the data is incomplete.

BOOL
WINAPI
CommitUrlCacheEntry(
IN LPCSTR lpszUrlName,
IN LPCTSTR lpszLocalFileName,
IN FILETIME ExpireTime,
IN FILETIME LastModifiedTime,
IN DWORD CacheEntryType,
IN LPCBYTE lpHeaderInfo,
IN DWORD dwHeaderSize,
IN LPCTSTR lpszFileExtension,
IN DWORD dwReserved
);

Parameters :

lpszUrlName : Source Name of the cache entry. This must be an unique name. The name string
should not contain any escape character.
lpszLocalFileName : Name of the local file that is being cached. The file will be moved to the
cache storage if the storage is in the same volume of the local file otherwise the file is
copied to the cache storage and then the local file is deleted. Typically this would be the
same as is returned in the CreateCacheEntry API, in which case the entry is marked as
being committed.
ExpireTime : Expire date and time (GMT) of the file that is being cached. If it is unknown set it to
zero.
LastModifiedTime : Last modified date and time (GMT) of the file that is being cached. If it is
unknown set it to zero.
CacheEntryType: Type of the cache entry.
lpHeaderInfo : Pointer to the headerinfo data. If this is non-NULL, headerinfo is treated as
extended attributes of the URL and is returned back in CACHE_ENTRY_INFO.

6/15/2019 6/15/20196/15/2019 4
dwHeaderSize: Size of the above header info. If lpHeaderInfo is non-NULL, this value is
assumed to indicate the size of the headerinfo. Caller can maintain headers as part of
the data and provide dwHeaderSize, together with a NULL value for lpHeaderInfo.
lpszFileExtension : if it is not NULL, the cache system uses this extension to name the file in the
local storage. It is recommended that the extension be kept less than three letters, for
the sake of efficient handling of internal data.
dwReserved : For future use.

Return Error Codes :

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

ERROR_FILE_NOT_FOUND : if the specified local file is not found.

ERROR_DISK_FULL : if the cache storage is full.

2.2.3 RetrieveUrlCacheEntryFile
RetrieveUrlCacheEntryFile API retrieves a cache entry from the cache in the form of a file. If
an extension was provided while calling CommitCacheEntry then the file will have the specified
extension. If the entry is not available in cache it 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 1. The file is locked for the caller when it is
retrieved, the caller should unlock the file after it has been used up. Cache manager will
automatically unlock the locked files after certain interval. While the file is locked cache
manager will not remove the file from cache. It important to note that this API 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 which contains data for other URLs, then 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 API be used only in situations where a filename is
needed in order to launch an application. RetrieveUrlCacheEntryStream and associated stream
APIs should be used in most cases.

BOOL
WINAPI
RetrieveUrlCacheEntryFile(
IN LPCSTR lpszUrlName,
OUT LPCACHE_ENTRY_INFO lpCacheEntryInfo,
1
How can this be enforced? We can set the file mode to read only during a file is locked, that makes the
user unable to delete or overwrite the file, and also protect the cache management code accidentally
deleting or overwriting this file.
6/15/2019 6/15/20196/15/2019 5
 IN OUT LPDWORD lpdwCacheEntryInfoBufferSize
IN DWORD dwReserved
);

Parameters:

lpszUrlName : Source Name of the cache entry. This must be an unique name. The name string
should not contain any escape characters.
lpCacheEntryInfo : Pointer to a cache entry info 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 : pointer to a DWORD location when the size of the above buffer
is passed in, on return this will contain the size of the actual buffer used or required. The
caller should check the return value in this field. If the return size is less than or equal to
the size passed in, all the relevant data has been returned.
dwReserved : for future use.

Return Error Codes :

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

ERROR_FILE_NOT_FOUND : if the cache entry specified by the source name is not found in
the cache storage.

2.2.4 UnlockUrlCacheEntryFile

UnlockUrlCacheEntryFile API unlocks the cache entry which was locked while the file was
retrieved for use from cache. The caller should not access the file after it calls this API. The
cache manager is now free to delete the cache entry if it wants.

BOOL
WINAPI
UnlockUrlCacheEntryFile(
IN LPCSTR lpszUrlName,
IN DWORD dwReserved
);

Parameters:

6/15/2019 6/15/20196/15/2019 6
lpszUrlName : Source name of the cache entry that is being unlocked. The name string should
not contain any escape characters.
dwReserved : for future use.

Return Error Codes :

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

ERROR_FILE_NOT_FOUND : if the cache entry specified by the source name is not found in
the cache storage.

2.2.5 RetrieveUrlCacheEntryStream
RetrieveCacheEntryStream API provides the most efficient and implementation independent
way of accessing the cache data. Cache clients that do not need URL data in the form of a file
should use this API in order to access the data for a particular URL.

HANDLE
WINAPI
RetrieveCacheEntryStream(
IN LPCSTR lpszUrlName,
OUT LPCACHE_ENTRY_INFO lpEntryInfo,
IN OUT LPDWORD lpdwCacheEntryInfoBufferSize,
IN BOOL fRandomRead,
IN DWORD dwReserved
);

Parameters:

lpszUrlName : Source Name of the cache entry. This must be an unique name. The name string
should not contain any escape characters.
lpCacheEntryInfo : Pointer to a cache entry info buffer.
lpdwCacheEntryInfoBufferSize : pointer to a DWORD location when the size of the above buffer
is passed in, on return this will contain the size of the actual buffer used or required.
fRandomRead : Flag to indicate that the stream is opened for random access or not. Set the flag
to TRUE to open the stream for random access.
dwReserved : for future use.

Return Error Codes :

6/15/2019 6/15/20196/15/2019 7
This API returns a valid handle (to be used in the other stream APIs) if it completes successfully,
otherwise it returns INVALID_HANDLE_VALUE, and GetLastError() returns the error code
value.

ERROR_FILE_NOT_FOUND : if the cache entry specified by the source name is not found in
the cache storage.

2.2.6 ReadUrlCacheEntryStream

ReadUrlCacheEntryStream provides a method of reading the cached data from a stream

which has been opened using the RetrieveUrlCacheEntryStream API.

BOOL
ReadUrlCacheEntryStream(
IN HANDLE hUrlCacheStream,
IN DWORD dwLocation,
IN OUT LPVOID lpBuffer,
IN OUT LPDWORD lpdwLen,
IN DWORD dwReserved
);

Parameters:

hUrlCacheStream : Handle that was returned by the RetrieveCacheEntryStream API.

dwLocation : Offset to read from.
lpBuffer : Pointer to a buffer where the data is read.
lpdwLen : Pointer to a DWORD location where the length of the above buffer passed in, on
return it contains the actual length of the data read.
dwReserved : For future use.

Return Error Codes :

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

2.2.7 UnlockUrlCacheEntryStream

UnlockCacheEntryStream API closes the stream that has been retrieved using the
RetrieveCacheUrlEntryStream API.
6/15/2019 6/15/20196/15/2019 8
BOOL

WINAPI
UnlockUrlCacheEntryStream(
IN HANDLE hUrlCacheStream,
IN DWORD dwReserved
);

Parameters:

hUrlCacheStream : Handle that was returned by the RetrieveCacheEntryStream API.

dwReserved : For future use.

Return Error Codes :

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

2.2.8 UrlCacheValidate
UrlCacheValidate API validates the cache consistency. Internet Services that use the URL
cache should call this API at appropriate time before using the cache system. This API takes
several seconds before it returns depending upon the size of the cache.

BOOL
WINAPI
UrlCacheValidate(
IN BOOL bFixIt,
IN DWORD dwReserved
);

Parameters :

bFixIt : Fix the invalid entries if possible when this flag is set to TRUE.
dwReserved : for future use.

Return Values:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

2.2.9 GetUrlCacheEntryInfo
GetUrlCacheEntryInfo API retrieves the information of the specified cache entry.
6/15/2019 6/15/20196/15/2019 9
BOOL
WINAPI
GetUrlCacheEntryInfo(
IN LPCSTR lpszUrlName,
IN LPCACHE_ENTRY_INFO lpCacheEntryInfo,
IN OUT LPDWORD lpdwCacheEntryInfoBufferSize
);

Parameters:

lpszUrlName : Name of the cache entry. The name string should not contain any escape
character.
lpCacheEntryInfo : Pointer to a CACHE_ENTRY structure buffer.
lpdwCacheEntryInfoBufferSize : pointer to a DWORD location that carries the size of the above
buffer. On return this location contains the size of the data (in bytes) returned.

Return Error Codes:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

ERROR_FILE_NOT_FOUND : if the specified cache entry is not found in the cache.

2.2.10 SetUrlCacheEntryInfo
SetUrlCacheEntryInfo API sets the specified fields of the cache entry info.

BOOL
WINAPI
SetUrlCacheEntryInfo(
IN LPCSTR lpszUrlName,
IN LPCACHE_ENTRY_INFO lpCacheEntryInfo,
IN DWORD dwFieldControl
);

Parameters:

lpszUrlName : Name of the cache entry. The name string should not contain any escape
character.
lpCacheEntryInfo : Pointer to a CACHE_INFO structure.
dwFieldControl : bitmask that indicates the fields that are to be set. Must be one or more of the
following mask OR together.

6/15/2019 6/15/20196/15/2019 10
 #define CACHE_ENTRY_ATTRIBUTE_FC 0x00000004
#define CACHE_ENTRY_HITRATE_FC 0x00000010
#define CACHE_ENTRY_MODTIME_FC 0x00000040
#define CACHE_ENTRY_EXPTIME_FC 0x00000080
#define CACHE_ENTRY_ACCTIME_FC 0x00000100

Return Error Codes:

ERROR_FILE_NOT_FOUND : if the specified cache entry is not found in the cache.

2.2.11 Cache Enumeration

2.2.11.1 FindFirstUrlCacheEntry
FindFirstUrlCacheEntry API begins the enumeration of the cache (in no particular order ??).
The returned handle can be used in the FindNextUrlCacheEntry to get subsequent entries in
the cache.

HANDLE
WINAPI
FindFirstUrlCacheEntry (
IN LPCSTR lpszUrlSearchPattern,
OUT LPCACHE_ENTRY_INFO lpFirstCacheEntryInfo,
IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize
);

Parameters:

lpszUrlSearchPattern : source name pattern to search for. If NULL, *.* is assumed. (In this
version we may implement only *.* semantics).
lpFirstCacheEntryInfo : Pointer to a buffer of the type CACHE_ENTRY_INFO.
lpdwFirstCacheEntryInfoBufferSize : pointer to a DWORD location that carries the size of the
above buffer. On return this location contains the size of the data (in bytes) returned.

Return Value:

This API returns a valid handle (to be used to enumerate rest of the URL entries) if it completes
successfully, otherwise it returns INVALID_HANDLE_VALUE, and GetLastError() returns the
error code value.

6/15/2019 6/15/20196/15/2019 11
2.2.11.2 FindNextUrlCacheEntry
FindNextUrlCacheEntry API returns the next entry in the cache.

BOOL
WINAPI
FindNextUrlCacheEntry(
IN HANDLE hEnumHandle,
OUT LPCACHE_ENTRY_INFO lpNextCacheEntryInfo,
IN OUT LPWORD lpdwNextCacheEntryInfoBufferSize
);

Parameters:

hEnumHandle : Enumeration handle obtained on FindFirstUrlCacheEntry call.

lpNextCacheEntryInfo : Buffer to return the info about cache entry.
lpdwNextCacheEntryInfoBufferSize : pointer to a DWORD location that carries the size of the
above buffer. On return this location contains the size of the data (in bytes) returned.

Return Value:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

ERROR_NO_MORE_FILES - when the enumeration completes.

2.2.11.3 FindCloseUrlCache

FindCloseUrlCache closes the specified enumeration handle.

BOOL
WINAPI
FindCloseUrlCache(
IN HANDLE hEnumHandle
);

Parameters:

hEnumHandle : Handle returned by FindFirstUrlCacheEntry

Return Value:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

6/15/2019 6/15/20196/15/2019 12
2.2.12 DeleteUrlCacheEntry
DeleteUrlCacheEntry API removes the file associated with the source name from the cache, if it
exists.

BOOL
WINAPI
DeleteUrlCacheEntry(
IN LPCSTR lpszUrlName
);

Parameters:

lpszUrlName: Name of the source corresponding to the cache entry.

Return Value:

TRUE if successful. If FALSE use GetLastError()to get extended error code. If the entry
corresponding to the remote name is not in the cache GetLastError returns
ERROR_FILE_NOT_FOUND. If it is in use i.e. RetrieveUrlCacheEntry has been called
on it, then the call fails with ERROR_ACCESS_DENIED.

2.2.13 FreeUrlCacheSpace (not implemented as of 2/26/96)

FreeUrlCacheSpace API allows the caller to free a percentage of the cache space. This
functionality is useful for managing the disk space.

BOOL
WINAPI
FreeUrlCacheSpace(
IN LPCTSTR lpszCachePath,
IN DWORD dwSize,
IN DWORD dwSizeType
);

Parameters:

lpszCachePath: Path from which to free up the cache space. If the path is a volume the cache
will free up appropriate amount of space from the volume. If the parameter is NULL,
the cache will make the decision about which cache path to use.
dwSize : amount of cache space to be freed
dwSizeType : size type, could be any of FCS_PERCENT_CACHE_SPACE,
FCS_PERCENT_DISK_SPACE, FCS_ABSOLUTE_SIZE

6/15/2019 6/15/20196/15/2019 13
Return Value:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

3. Cache Management
The cache management APIs provide controls to administrator to manage the files that are
cached on the client storage. The management APIs are to be used only by a control panel
applet to configure the cache.

3.1 Structure Definitions:

typedef struct _CACHE_CONFIG_PATH_ENTRY {

TCHAR CachePath[MAX_PATH];
DWORD dwCacheSize; // IN Kbytes
} CACHE_CONFIG_PATH_ENTRY, *LPCACHE_CONFIG_PATH_ENTRY;

typedef struct _CACHE_CONFIG_INFO {

DWORD dwFreshnessInterval; // time to wait before file update
DWORD dwCleanupInterval; // time interval between the unused file cleanups.
DWORD dwCleanupFactor; // % of the cache storage freed up during cleanup.
DWORD dwTimeToCleanup; // schedule cleanup, 0 - mid-night, 1 - 1:00 AM and so on.
BOOL bPersistentCache; // if set the cache is persistent across service restart.
DWORD dwNumCachePaths;
CACHE_PATH_ENTRY CachePaths[ANYSIZE_ARRAY];
} CACHE_CONFIG_INFO, *LPCACHE_CONFIG_INFO;

#define CACHE_CONFIG_FRESHNESS_INTERVAL_FC 0x00000001

#define CACHE_CONFIG_CLEANUP_INTERVAL_FC 0x00000002
#define CACHE_CONFIG_CLEANUP_FACTOR_FC 0x00000004
#define CACHE_CONFIG_CLEANUP_TIME_FC 0x00000008
#define CACHE_CONFIG_PERSISTENT_CACHE_FC 0x00000010
#define CACHE_CONFIG_FORCE_CLEANUP_FC 0x00000020
#define CACHE_CONFIG_DISK_CACHE_PATHS_FC 0x00000040

3.2 Cache Configuration APIs

3.2.1 GetUrlCacheConfigInfo
GetUrlCacheConfigInfo API retrieves the current cache configuration information.
6/15/2019 6/15/20196/15/2019 14
BOOL
WINAPI
GetUrlCacheConfigInfo(
IN LPCACHE_ CONFIG_INFO lpCacheConfigInfo,
IN OUT LPDWORD lpdwCacheConfigInfoBufferSize,
IN DWORD dwFieldControl
);

Parameters:

lpCacheConfigInfo : The buffer in which the cache info is to be returned.

lpdwCacheInfoBufferSize : pointer to a DWORD location that carries the size of the above buffer.
On return this location contains the size of the data (in bytes) returned.
dwFieldControl : Bitmask that controls the fields to be returned in the above buffer.

Return:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

3.2.2 SetUrlCacheConfigInfo
SetUrlCacheConfigInfo API sets the specified cache configuration information. If any setting is
changed, all the top level windows get WM_SETTINGCHANGE message.

BOOL
WINAPI
SetUrlCacheConfigInfo(
IN LPCACHE_CONFIG_INFO lpCacheInfo
IN DWORD dwFieldControl
);

Parameters:

lpCacheConfigInfo : CachInfo structure to set information in the registry.

dwFieldControl : Bitmask that controls the fields to be returned in the above buffer.

Return Value:

This API returns TRUE if it completes successfully, otherwise it returns FALSE, and
GetLastError() returns the error code value.

6/15/2019 6/15/20196/15/2019 15
6/15/2019 6/15/20196/15/2019 16