ThinBASIC Modules > INet > INET_Internet

Description

Reads data from a handle opened by the INET_Internet_OpenUrl.

Syntax

Result = INET_Internet_ReadFile(hFile, pBuffer , dwNumberOfBytesToRead, NumberOfBytesRead)

Returns

Returns %TRUE if successful, or %FALSE otherwise.

Parameters

Name	Type	Optional	Meaning
hFile	Number	No	Handle returned from a previous call to INET_Internet_OpenUrl,
pBuffer	Number	No	Pointer to a buffer that receives the data.
NumberOfBytesToRead	Number	No	Number of bytes to be read. Usually this is the size of the buffer pointed by pBuffer
NumberOfBytesRead	Variable	No	Numeric variable that will be filled with the number of bytes returned in pBuffer

Remarks

INET_Internet_ReadFile operates much like the base file read function, with a few exceptions. Typically, INET_Internet_ReadFile retrieves data from an hFile handle as a sequential stream of bytes. The amount of data to be read for each call to INET_Internet_ReadFile is specified by the NumberOfBytesToRead parameter and the data is returned in the pBuffer parameter. A normal read retrieves the specified NumberOfBytesToRead for each call to INET_Internet_ReadFile until the end of the file is reached. To ensure all data is retrieved, an application must continue to call the INET_Internet_ReadFile function until the function returns %TRUE and the NumberOfBytesRead parameter equals zero. This is especially important if the requested data is written to the cache, because otherwise the cache will not be properly updated and the file downloaded will not be committed to the cache. Note that caching happens automatically unless the original request to open the data stream set the %INTERNET_FLAG_NO_CACHE_WRITE flag.

When an application retrieves a handle using INET_Internet_OpenUrl, WinINet attempts to make all data look like a file download, in an effort to make reading from the Internet easier for the application. For some types of information, such as FTP file directory listings, it converts the data to be returned by INET_Internet_ReadFile to an HTML stream. It does this on a line-by-line basis. For example, it can convert an FTP directory listing to a line of HTML and return this HTML to the application.

WinINet attempts to write the HTML to the pBuffer buffer a line at a time. If the application's buffer is too small to fit at least one line of generated HTML, the error code ERROR_INSUFFICIENT_BUFFER is returned as an indication to the application that it needs a larger buffer. Also, converted lines might not completely fill the buffer, so INET_Internet_ReadFile can return with less data in pBuffer than requested. Subsequent reads will retrieve all the converted HTML. The application must again check that all data is retrieved as described previously.

Restrictions