URLDownloadToFile function

Article
07/13/2016

Downloads bits from the Internet and saves them to a file.

Syntax

HRESULT URLDownloadToFile(
             LPUNKNOWN            pCaller,
             LPCTSTR              szURL,
             LPCTSTR              szFileName,
  _Reserved_ DWORD                dwReserved,
             LPBINDSTATUSCALLBACK lpfnCB
);

Parameters

pCaller
A pointer to the controlling IUnknown interface of the calling ActiveX component, if the caller is an ActiveX component. If the calling application is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component, such as an ActiveX control in the context of an HTML page. This parameter represents the outermost IUnknown of the calling component. The function attempts the download in the context of the ActiveX client framework, and allows the caller container to receive callbacks on the progress of the download.
szURL
A pointer to a string value that contains the URL to download. Cannot be set to NULL. If the URL is invalid, INET_E_DOWNLOAD_FAILURE is returned.
szFileName
A pointer to a string value containing the name or full path of the file to create for the download. If szFileName includes a path, the target directory must already exist.
dwReserved
Reserved. Must be set to 0.
lpfnCB
A pointer to the IBindStatusCallback interface of the caller. By using IBindStatusCallback::OnProgress, a caller can receive download status. URLDownloadToFile calls the IBindStatusCallback::OnProgress and IBindStatusCallback::OnDataAvailable methods as data is received. The download operation can be canceled by returning E_ABORT from any callback. This parameter can be set to NULL if status is not required.

Return value

This function can return one of these values.

Return code	Description
S_OK	The download started successfully.
E_OUTOFMEMORY	The buffer length is invalid, or there is insufficient memory to complete the operation.
INET_E_DOWNLOAD_FAILURE	The specified resource or callback interface was invalid.

Remarks

URLDownloadToFile binds to a host that supports IBindHost to perform the download. To do this, it first queries the controlling IUnknown passed as pCaller for IServiceProvider, then calls IServiceProvider::QueryService with SID_SBindHost. If pCaller does not support IServiceProvider, IOleObject or IObjectWithSite is used to query the object's host container. If no IBindHost interface is supported, or pCaller is NULL, URLDownloadToFile creates its own bind context to intercept download notifications.

URLDownloadToFile returns S_OK even if the file cannot be created and the download is canceled. If the szFileName parameter contains a file path, ensure that the destination directory exists before calling URLDownloadToFile. For best control over the download and its progress, an IBindStatusCallback interface is recommended.

Windows Internet Explorer 8. URLDownloadToFile does not support IBindStatusCallbackEx and cannot be used to download files over 4 gigabytes (GB) in size. Refer instead to IBindStatusCallbackEx::GetBindInfoEx for a code example.

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows 2000 Server
Product	Internet Explorer 3.0
Header	Urlmon.h
Library	Urlmon.lib
DLL	Urlmon.dll
Unicode and ANSI names	URLDownloadToFileW (Unicode) and URLDownloadToFileA (ANSI)

Share via