ReadClient Function

  • Article

The ReadClient function reads data from the body of the client's HTTP request.

BOOL ReadClient(
      HCONN hConn,
      LPVOID lpvBuffer,
      LPDWORD lpdwSize
);

Parameters

  • hConn
    A connection handle.

  • lpvBuffer
    Points to the buffer area to receive the requested information.

  • lpdwSize
    Points to a DWORD that indicates the number of bytes available in the buffer specified by lpvBuffer. On return, lpdwSize will point to a DWORD that contains the number of bytes actually transferred into the buffer.

Return Values

If the function succeeds, the return value is TRUE. If an error occurs, the return value is FALSE. The Win32 GetLastError function can be called to determine the error.

Remarks

The ReadClient function reads information from the body of the Web client's HTTP request into the buffer supplied by the caller. Thus, the call can be used to read data from an HTML form that uses the POST method.

It is not necessary to call ReadClient unless the EXTENSION_CONTROL_BLOCK Structure member cbTotalBytes is larger than cbAvailable (also in EXTENSION_CONTROL_BLOCK). If the buffer size that your extension has allocated, specified by lpdwSize, is less than the number of bytes available, as specified by the EXTENSION_CONTROL_BLOCK member cbAvailable, then your ReadClient call will return immediately with the requested amount of data. Your extension will need to call ReadClient multiple times to retrieve all the data. If the buffer size is greater than the number of bytes available, ReadClient will fill the available space.

Note

ReadClient will time out after 60 seconds, regardless of any IIS server time-out settings. If you expect that the client of your ISAPI extension will regularly take more than 60 seconds to respond to a read, then you should perform asynchronous reads through the HSE_REQ_ASYNC_READ_CLIENT function of ServerSupportFunction Function, instead of synchronous ReadClient calls. Asynchronous read requests make better use of the IIS I/O thread pool, and can have time-out values regulated using the connection time-out value, accessible in the MMC.

Alternatively, if you are unable to use asynchronous reads, you can loop by initiating another synchronous ReadClient call after the 60-second timeout period has elapsed.

If the socket on which the server is listening to the client is closed, ReadClient will return TRUE, but with zero bytes read.

Requirements

Client: Requires Windows XP Professional, Windows 2000 Professional, or Windows NT Workstation 4.0.

Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0.

Product: IIS

Header: Declared in httpext.h.