Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function downloads data into the Internet cache and returns the file name of the cache location for retrieving the bits.

Syntax 

HRESULT URLDownloadToCacheFile(
  LPUNKNOWN 
lpUnkcaller,
  LPCSTR 
szURL,
  LPTSTR 
szFileName,
  DWORD 
dwBufLength,
  DWORD 
dwReserved,
  IBindStatusCallback* 
pBSC
);

Parameters

lpUnkcaller

Address of the controlling IUnknowninterface of the calling Microsoft ActiveX component, if the caller is an ActiveX component. If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a Component Object Model (COM) object that is contained in another component, such as an ActiveX control within the context of an HTML page. This parameter represents the outermost IUnknownof the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.

szURL

Address of a string value that contains the URL to be downloaded. This cannot be set to NULL.

szFileName

Address of a string value that contains the name of the downloaded file. This cannot be set to NULL.

dwBufLength

Unsigned long integer value that contains the size of the szFileNamebuffer in bytes.

dwReserved

Reserved. Must be set to zero.

pBSC

Address of the caller's IBindStatusCallbackinterface. URLDownloadToCacheFilecalls this interface's IBindStatusCallback::OnProgressmethod on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailableis never called. Implementing IBindStatusCallback::OnProgressallows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgresscall. This can be set to NULL.

Return Value

This function returns one of the values shown in the following table.

Value Description

E_FAIL

The operation failed.

E_OUTOFMEMORY

The buffer length is invalid or there was insufficient memory to complete the operation.

S_OK

The operation succeeded.

Remarks

The client can choose to be notified of progress through a notification callback.

This function always returns a file name if the download operation succeeds. If the given URL is a file: URL, URLDownloadToCacheFiledirectly returns the file name for the file: URL rather than making a copy to the cache. If the given URL is an Internet URL (http:, ftp:), URLDownloadToCacheFiledownloads this file and returns the local file name of the cached copy. Using this function ensures that a file name is returned without unnecessary copying of data.

For Windows Mobile when Internet Explorer Mobile starts to run it will assume that the cache folder is a system folder and make it hidden.

Requirements

Header urlmon.h, urlmon.idl
Library urlmon.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later