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,      // Pointer to URL to be downloaded
  LPTSTR szFileName,  // Pointer to 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] 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 directly returns 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 downloads 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.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in urlmon.h.

See Also

IBindStatusCallback, IBindStatusCallback::OnProgress