| |
| INT WINAPI HttpGetFile(
|
| |
HCLIENT hClient, |
|
| |
LPCTSTR lpszLocalFile, |
|
| |
LPCTSTR lpszRemoteFile, |
|
| |
DWORD dwOptions, |
|
| |
DWORD dwOffset |
|
| );
|
The HttpGetFile function transfers the specified file on
the server to the local system.
Parameters
- hClient
- Handle to the client session.
- lpszLocalFile
- A pointer to a null-terminated string that specifies the file
on the local system that will be created, overwritten or appended
to. The file pathing and name conventions must be that of the local
system.
- lpszRemoteFile
- A pointer to a null-terminated string that specifies the
resource on the server. This may be the name of a file on the
server, or it may specify the name of a script that will be
executed and the output returned to the caller. This string may
specify a valid URL for the current server that the client is
connected to.
- dwOptions
- An unsigned integer that specifies one or more options. This
parameter is constructed by using a bitwise operator with any of
the following values:
| Constant |
Description |
| HTTP_TRANSFER_DEFAULT |
The default transfer mode. The resource data is copied to the
local system exactly as it is stored on the server. |
| HTTP_TRANSFER_CONVERT |
If the resource being downloaded from the server is textual,
the data is automatically converted so that the end of line
character sequence is compatible with the Windows platform.
Individual carriage return or linefeed characters are converted to
carriage return/linefeed character sequences. |
| HTTP_TRANSFER_COMPRESS |
This option informs the server that the client is willing to
accept compressed data. If the server supports compression for the
specified resource, then the data will be automatically expanded
before being returned to the caller. This option is selected by
default if compression has been enabled using the
HttpEnableCompression function. This option is ignored if
the dwOffset parameter is non-zero. |
- dwOffset
- Specifies a byte offset into the file. If this value is greater
than zero, the server must support the ability to specify a byte
range with the request to download the file, otherwise this
function will fail.
Return Value
If the function succeeds, the return value is the server result
code. If the function fails, the return value is HTTP_ERROR. To get
extended error information, call HttpGetLastError.
Remarks
Enabling compression does not guarantee that the data returned
by the server will actually be compressed, it only informs the
server that the client is willing to accept compressed data.
Whether or not a particular resource is compressed depends on the
server configuration, and the server may decide to only compress
certain types of resources, such as text files. To determine if the
server compressed the data returned to the client, use the
HttpGetResponseHeader function to get the value of the
Content-Encoding header after this function returns. If the
header is defined, the value specifies the compression method used,
otherwise the data was not compressed.
To download large files that are over 4GB, use the
HttpGetFileEx function.
This function will cause the current thread to block until the
file transfer completes, a timeout occurs or the transfer is
canceled. During the transfer, the HTTP_EVENT_PROGRESS event will
be periodically fired, enabling the application to update any user
interface controls. Event notification must be enabled, either by
calling HttpEnableEvents, or by registering a callback
function using the HttpRegisterEvent function.
To determine the current status of a file transfer while it is
in progress, use the HttpGetTransferStatus function.
Example
LPCTSTR lpszLocalFile = _T("index.html");
LPCTSTR lpszRemoteFile = _T("http://www.catalyst.com/");
if (HttpGetFile(hClient, lpszLocalFile, lpszRemoteFile) == HTTP_ERROR)
{
dwError = HttpGetLastError();
_tprintf(stderr, "Unable to download %s, error 0x%lx\n", lpszRemoteFile, dwError);
}
Requirements
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use cshtpav7.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
HttpEnableEvents, HttpGetData, HttpGetFileEx, HttpGetText, HttpGetTransferStatus, HttpPutFile, HttpRegisterEvent
|
|