InternetReadFile

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

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. InternetReadFile sets 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 InternetGetLastResponseInfo when necessary.

Windows CE Remarks

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

The InternetReadFile function can be completed in either synchronous or asynchronous mode.

Remarks

The operation of InternetReadFile is the same as that of the base Win32 ReadFile with a few caveats. Normally, data is read from an HINTERNET handle as a sequential stream of bytes. The amount of data requested in the dwNumberOfBytesToRead parameter 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 lpBuffer will be returned in the lpdwNumberOfBytesRead parameter.

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 InternetReadFile can 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

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.

See Also

HINTERNET,FtpFindFirstFile, FtpOpenFile, GetLastError, HttpEndRequest, HttpOpenRequest, HttpSendRequestEx, InternetCloseHandle, InternetGetLastResponseInfo, InternetOpenUrl, InternetReadFile

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.