InternetReadFile

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function reads data from a handle opened by the FtpOpenFile, FtpFindFirstFile, or HttpOpenRequestfunction.

BOOL WINAPI InternetReadFile(
IN
HINTERNET
hFile, 
IN
LPVOID
lpBuffer, 
IN
DWORD
dwNumberOfBytesToRead, 
OUT
LPDWORD
lpdwNumberOfBytesRead
);

Parameters

hFile

Valid handle returned from a previous call to InternetOpenUrl, FtpOpenFile, or HttpOpenRequest.

lpBuffer

Long pointer to a buffer that receives the data read.

dwNumberOfBytesToRead

Specifies the number of bytes to read.

lpdwNumberOfBytesRead

Long pointer to a variable that receives the number of bytes read. InternetReadFilesets this value to zero before doing any work or error checking.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfowhen necessary.

Windows CE Remarks

Windows CE supports valid internet handles returned by HttpOpenRequest, FtpOpenFile, and FtpFindFirstFile.

The InternetReadFilefunction can be completed in either synchronous or asynchronous mode.

Remarks

The operation of InternetReadFileis the same as that of the base Win32 ReadFilewith a few caveats. Normally, data is read from an HINTERNEThandle as a sequential stream of bytes. The amount of data requested in the dwNumberOfBytesToReadparameter will be returned in lpBuffer. The only time during a normal read when less data than requested is returned, is when we have reached the end-of-file. In both cases, the number of bytes copied to lpBufferwill be returned in the lpdwNumberOfBytesReadparameter.

If the data just read is also being written to the cache (automatically by Wininet unless the original request was made with INTERNET_FLAG_NO_CACHE_WRITE set) then the application must read all the way to the end-of-file to ensure that the file is cached properly. This means that the application must call InternetReadFile()until it returns TRUE and *lpdwNumberOfBytesRead = 0. This is incontrovertably the end-of-file indication, and will ensure that the downloaded file is correctly committed to cache. If the application determines the amount of data to be read from the HTTP Content-Length header for example, and reads only that amount of data, then the cache will not be properly updated and the file just downloaded will not be committed to the cache.

InternetReadFile()may return an unexpected ERROR_INSUFFICIENT_BUFFER when reading HTML from a handle created with InternetOpenUrl. This will only happen when Wininet is creating the HTML from a structured data format, for example when reading an FTP or gopher directory listing. Internally, Wininet converts the structured data to a HTML stream, line-by-line. If Wininet determines that the application's buffer is not large enough to hold at least one line of the generated HTML then the above error is returned. In this case, the application needs to reissue the request to InternetReadFile()with a larger buffer.

If while reading generated HTML, Wininet determines that the buffer is not large enough to hold all the generated HTML, but at least some was copied to the buffer, then InternetReadFilecan return control to the application but with less data copied to the buffer than requested. This situation is indistinguishable from end-of-file but is not the end-of-file. As long as the application reads to the end-of-stream ( InternetReadFile()returns TRUE and *lpdwNumberOfBytesRead = 0) then it will receive all of the generated HTML.

(Background: to make reading from the Internet easy for applications, Wininet attempts to make all data look like a file download to an application when it uses InternetOpenUrl(). Use of this API signals to Wininet that the application wants a simplified interface. For some types of information read from the Internet in this manner, such as FTP file directory listings and gopher directory listings, Wininet will convert the output from the FTP ls or dir commands, or the gopher listing to a HTML stream. It does this on a line-by-line basis, converting the FTP directory listing e.g. to a line of HTML. Wininet then returns to the application this generated HTML. Instead of writing the result a byte at a time however, Wininet attempts to write the data a line at a time. So if the application's buffer is too small to fit a line of generated HTML then ERROR_INSUFFICIENT_BUFFER is returned as an indication to the application that it needs a larger buffer.)

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Wininet.h		Wininet.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.