| |
| 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 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 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:
| Value |
Description |
| HTTP_TRANSFER_DEFAULT |
The default transfer mode. The resource data is downloaded to
the local system exactly as it is stored on the server. If you
are requesting a text-based resource, the data may use a
different end-of-line character sequence. For example, the
end-of-line character may be a single linefeed character instead
of a carriage return and linefeed pair. |
| 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. |
| HTTP_TRANSFER_ERRORDATA |
This option causes the client to accept error data from the
server if the request fails. If this option is specified, an
error response from the server will not cause the function to
fail. Instead, the response is returned to the client and the
function will succeed. If this option is used, your application
should call HttpGetResultCode to obtain the
HTTP status code returned by the server. This will enable you to
determine if the operation was successful. |
- 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://sockettools.com/");
if (HttpGetFile(hClient, lpszLocalFile, lpszRemoteFile) == HTTP_ERROR)
{
dwError = HttpGetLastError();
_tprintf(stderr, "Unable to download %s, error 0x%lx\n", lpszRemoteFile, dwError);
}
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cshtpv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
HttpEnableEvents,
HttpGetData,
HttpGetFileEx,
HttpGetText,
HttpGetTransferStatus,
HttpPutFile,
HttpRegisterEvent
|
|