URLDownloadToCacheFile

Downloads data into the Internet cache and returns the name of the cached file. The client can optionally be notified of progress by means of a notification callback.

HRESULT URLDownloadToCacheFile(

LPUNKNOWN pCaller,

// Caller’s controlling IUnknown

LPCWSTR szURL,

// URL to be downloaded

LPTSTR szFileName,

// Name of cached file

DWORD dwBufLen,

// Size of szFileName

DWORD dwResv,

// Reserved for future use

LPBINDSTATUSCALLBACK lpfnCB

// Caller’s IBindStatusCallback

);

Parameters

pCaller: [in] Pointer to the caller’s controlling IUnknown. If the caller is not an ActiveX component, this value may be set to NULL.
szURL: [in] Pointer to the URL to be downloaded. Cannot be NULL.
szFileName: [out] Indirect pointer to the name of the cached file returned by this function. The user should pass a buffer to be filled and, preferably, use MAX_PATH to allocate the maximum path size.
dwBufLen: [in] The size of the buffer passed in szFileName.
dwResv: [in] Reserved for future use; must be zero.
lpfnCB: [in] Pointer to the caller’s IBindStatusCallback interface. Can be NULL.

Return Values

E_OUTOFMEMORY: dwBufLen is smaller than the length of szFileName.

This moniker also returns the same values as IBindHost::MonikerBindToStorage.

Remarks

URLDownloadToFile calls the caller’s IBindStatusCallback interface to provide notifications during the binding process. In particular, URLDownloadToFile calls IBindStatusCallback::OnProgress to report the ongoing status of the download. The caller does not need not implement any of the notification callbacks for the function to succeed, but doing so allows the client to receive notifications, if interested, and allows downloads to be canceled by returning E_ABORT from the OnProgress call.

This function always returns a filename if the dowload operation succeeds. If the given URL is a file URL (i.e., contains “file:”), URLDownloadToCacheFile will directly return the filename for the file URL, rather than copying the file to the cache. If the given URL is an Internet URL (i.e., contains “http:” or “ftp:”), URLDownloadToCacheFile will download this file and return the local filename of the cached copy. Using this function ensures that a filename is returned without unnecessary copying of data.

If pCaller is non-NULL, the caller is a COM object that is contained in another component, such as an ActiveX Control in the context of an HTML page.In this case, the function attempts the download in the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.

LPUNKNOWN pCaller,	// Caller’s controlling IUnknown
LPCWSTR szURL,	// URL to be downloaded
LPTSTR szFileName,	// Name of cached file
DWORD dwBufLen,	// Size of szFileName
DWORD dwResv,	// Reserved for future use
LPBINDSTATUSCALLBACK lpfnCB	// Caller’s IBindStatusCallback
);