URLDownloadToFile Function
Downloads bits from the Internet and saves them to a file.
Syntax
HRESULT URLDownloadToFile( LPUNKNOWN pCaller, LPCTSTR szURL, LPCTSTR szFileName, DWORD dwReserved, LPBINDSTATUSCALLBACK lpfnCB );
Parameters
- pCaller
- A pointer to the controlling IUnknown interface of the calling Microsoft 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 Component Object Model (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 OnProgress, a caller can receive download status. URLDownloadToFile calls the OnProgress and 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
Returns one of the following values.
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.
Function Information
Stock Implementation urlmon.dll Custom Implementation No Header Urlmon.h Import library Urlmon.lib Minimum availability Internet Explorer 3.0 Minimum operating systems Windows NT 4.0, Windows 95 Unicode Implemented as ANSI and Unicode versions.
Community Content
Vasanthakumar Pandurangan
URLDownloadToFile() API is not working properly in multi-homed servers
We are using a WMI Provider (in C++) which does an HTTP query (Ex: http://169.254.175.28/xmldata?item=all) to another embedded device to get an xml file. Provider uses this xml file internally to get system information.
To download this file, Provider uses URLDownloadToFile API. No problem in the API when that device IP is configured statically or in DHCP mode.
This API does not work only in some servers which has link local IP address (169.254.X.X) for that embedded device. It returns 0x800c000c - INET_E_INVALID_REQUEST error.
Note that the device is directly connected to the server and i'm able to ping the link local IP.
Also even in those servers, this API works when it is part of a sample code. (just copy pasted code which calls this API from the Provider)
Provider code works fine, when i change that device IP configuration to static or DHCP.
The function which has URLDownloadToFile API is exactly similar in WMI Provider and sample code. i dont know why it works for link local address in sample code, but doesn't work when its part of Provider.
Please let me know if you have any insights about this function or is there any other better way to achieve the same thing.
Pluto is a Planet
Full Error Codes List
Look up what error code you got by doing this, then matching it to something from below:
printf("%x",hr);
INET_E_INVALID_URL (800C000)
INET_E_NO_SESSION (800C0003)
INET_E_CANNOT_CONNECT (800C0004)
INET_E_RESOURCE_NOT_FOUND (800C0005)
INET_E_OBJECT_NOT_FOUND (800C0006)
INET_E_DATA_NOT_AVAILABLE (800C0007)
INET_E_DOWNLOAD_FAILURE (800C0008)
INET_E_AUTHENTICATION_REQUIRED (800C0009)
INET_E_NO_VALID_MEDIA (800C000A)
INET_E_CONNECTION_TIMEOUT (800C000B)
INET_E_INVALID_REQUEST (800C000C)
INET_E_UNKNOWN_PROTOCOL (800C000D)
INET_E_SECURITY_PROBLEM (800C000E)
INET_E_CANNOT_LOAD_DATA (800C000F)
INET_E_CANNOT_INSTANTIATE_OBJECT (800C0010)
INET_E_INVALID_CERTIFICATE (800C0019)
INET_E_REDIRECT_FAILED (800C0014)
INET_E_REDIRECT_TO_DIR (800C0015)
INET_E_CANNOT_LOCK_REQUEST (800C0016)
INET_E_USE_EXTEND_BINDING (800C0017)
INET_E_TERMINATED_BIND (800C0018)
INET_E_ERROR_FIRST (800C0002)
INET_E_CODE_DOWNLOAD_DECLINED (800C0100)
INET_E_RESULT_DISPATCHED (800C0200)
INET_E_CANNOT_REPLACE_SFP_FILE (800C0300)
INET_E_CODE_INSTALL_SUPPRESSED (800C0400)
INET_E_CODE_INSTALL_BLOCKED_BY_HASH_POLICY (800C0500)
printf("%x",hr);
INET_E_INVALID_URL (800C000)
INET_E_NO_SESSION (800C0003)
INET_E_CANNOT_CONNECT (800C0004)
INET_E_RESOURCE_NOT_FOUND (800C0005)
INET_E_OBJECT_NOT_FOUND (800C0006)
INET_E_DATA_NOT_AVAILABLE (800C0007)
INET_E_DOWNLOAD_FAILURE (800C0008)
INET_E_AUTHENTICATION_REQUIRED (800C0009)
INET_E_NO_VALID_MEDIA (800C000A)
INET_E_CONNECTION_TIMEOUT (800C000B)
INET_E_INVALID_REQUEST (800C000C)
INET_E_UNKNOWN_PROTOCOL (800C000D)
INET_E_SECURITY_PROBLEM (800C000E)
INET_E_CANNOT_LOAD_DATA (800C000F)
INET_E_CANNOT_INSTANTIATE_OBJECT (800C0010)
INET_E_INVALID_CERTIFICATE (800C0019)
INET_E_REDIRECT_FAILED (800C0014)
INET_E_REDIRECT_TO_DIR (800C0015)
INET_E_CANNOT_LOCK_REQUEST (800C0016)
INET_E_USE_EXTEND_BINDING (800C0017)
INET_E_TERMINATED_BIND (800C0018)
INET_E_ERROR_FIRST (800C0002)
INET_E_CODE_DOWNLOAD_DECLINED (800C0100)
INET_E_RESULT_DISPATCHED (800C0200)
INET_E_CANNOT_REPLACE_SFP_FILE (800C0300)
INET_E_CODE_INSTALL_SUPPRESSED (800C0400)
INET_E_CODE_INSTALL_BLOCKED_BY_HASH_POLICY (800C0500)
Hirden
@Darren 1995
@Darren 1995: The S_OK return value just indicates that the download has started properly. Not that it has finished downloading, for that information you will have to use the LPBINDSTATUSCALLBACK lpfnCB parameter to get a status callback.
Darren 1995
Full Documentation?
I wrote a little program which utilizes this function. It downloads some .txt file from a server and processes the .txt file. However, my code here
HRESULT result = URLDownloadToFile(NULL, URL, File, 0, NULL);
switch (result)
{
case S_OK: downloaded = true; break;
case E_OUTOFMEMORY: writeToAllTextboxes("Out of memory error"); break;
case INET_E_DOWNLOAD_FAILURE: writeToAllTextboxes("Cannot access server data"); break;
default: writeToAllTextboxes("Unknown error"); break;
}
the default case seems to be called. Why is that? I'm using Win XP and I'm 100% sure that the site works and the file path and everything is all set.
And probably more importantly for me, how do I fix this?
HRESULT result = URLDownloadToFile(NULL, URL, File, 0, NULL);
switch (result)
{
case S_OK: downloaded = true; break;
case E_OUTOFMEMORY: writeToAllTextboxes("Out of memory error"); break;
case INET_E_DOWNLOAD_FAILURE: writeToAllTextboxes("Cannot access server data"); break;
default: writeToAllTextboxes("Unknown error"); break;
}
the default case seems to be called. Why is that? I'm using Win XP and I'm 100% sure that the site works and the file path and everything is all set.
And probably more importantly for me, how do I fix this?
Chuck Walbourn - MSFT
COM
It should be noted that this function requires you have already called CoInitializeEx() in your program or it will fail to operate. In my case, it didn't return any error codes it just hung up the program indefinitely until I included this explicit COM initalization step.
LaVolpe
dwReserved may very well be reserved
Mr Hapi, that reference you quoted is not for this function, it is for the URLDownloadToCacheFile function.
Mr. HAPI
dwReserved parameter is NOT reserved!
MS Documentation Team: Please provide the FULL documentation of the URLDownloadToFile() function and stop the little "reserved; must be set to zero" trick just because you want to keep certain functionality as a secret.
As documented here, it's possible to ensure downloading the newest version of a file by passing the BINDS_GETNEWESTVERSION flag to the dwReserved parameter:
"Note that the function documentation states that the parameter named dwReserved is reserved and must be set to zero. However, BINDF_GETNEWESTVERSION is a flag value that can be passed into this function as a dwReserved parameter to provided the appropriate functionality."
Source: http://support.microsoft.com/kb/q196466/en-us
As documented here, it's possible to ensure downloading the newest version of a file by passing the BINDS_GETNEWESTVERSION flag to the dwReserved parameter:
"Note that the function documentation states that the parameter named dwReserved is reserved and must be set to zero. However, BINDF_GETNEWESTVERSION is a flag value that can be passed into this function as a dwReserved parameter to provided the appropriate functionality."
Source: http://support.microsoft.com/kb/q196466/en-us
Hasan849
Trouble in Firefox authenticated sessions
I have used this function for quite some time in firefox and it was working flawlessly. But in the past couple of months or so I am facing this issue in firefox.
I download zip files from web servers inside an ActiveX that runs in a browser. When I log in to a website and try to download the zip file through my ActiveX in firefox, it fails. This worked previously. I have the necessary cookies created on my machine but somehow firefox does not seem to use them anymore. This still works prefectly in IE which downloads the file without any issue.
If the web server does not require a login, the file downloads without any issue.
This function gets stuck during "Sending Request" phase as indicated by the status code in the Progress callback.
I suspect the issue is with some security update in windows XP which has updated urlmon.dll and wininet.dll. I think IE handles the new update but firefox has stopped working because of that. I may be wrong though. If anyone has faced a similar issue, please help me out.
I download zip files from web servers inside an ActiveX that runs in a browser. When I log in to a website and try to download the zip file through my ActiveX in firefox, it fails. This worked previously. I have the necessary cookies created on my machine but somehow firefox does not seem to use them anymore. This still works prefectly in IE which downloads the file without any issue.
If the web server does not require a login, the file downloads without any issue.
This function gets stuck during "Sending Request" phase as indicated by the status code in the Progress callback.
I suspect the issue is with some security update in windows XP which has updated urlmon.dll and wininet.dll. I think IE handles the new update but firefox has stopped working because of that. I may be wrong though. If anyone has faced a similar issue, please help me out.
Raghuram
If tearget file is in chinese then download fails?
I am dowloading the word file from the server and try to store in the local machine.So the local file name is in english then download success.But the local file name in chinese then it fails? is this accept chinese characters?
Thomas Lee
Return E_ABORT if canceled
This function returns E_ABORT when operation be canceled by returning E_ABORT from any callback.
Thomas Lee
This was not helpful at all.
How about a sample program showing the use of this function?
Thomas Lee
Should double check after getting S_OK
Note that this API returns S_OK if the file download succeeds but the file creation fails (e.g. because you specified a non-existent folder, drive, etc). Hence, you should ensure the file exists before attempting to operate on it.
BarnyJuno
Seems to hang when used under Vista and network connection is lost
I use this function in a program that has to run under both Vista and XP, and I have to know when a network connection is lost during a file download. Under XP, everything is fine: disconnect the network, URLDownloadToFile exits immediately and I can begin to pick up the pieces. Under Vista, the function just hangs.
I've got a callback defined, and I thought that something would get reported through there, but no.
Anybody know what's going on?
I've got a callback defined, and I thought that something would get reported through there, but no.
Anybody know what's going on?