Navigation:  thinBasic Modules > INet >

INET_Internet_ReadFile

Previous pageReturn to chapter overviewNext page

 

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

 

See also

 

Examples