ReadClient (Compact 2013)
3/26/2014
This callback function is an application-defined function. ISAPI extensions call this function to read data from the body of the client's HTTP request. The ReadClient name for this function is a placeholder for the function name defined by the header.
Syntax
BOOL (WINAPI* ReadClient)(
HCONN ConnID,
LPVOID lpvBuffer,
LPDWORD lpdwSize
);
Parameters
- ConnID
[in] Connection handle.
- lpvBuffer
[out] Pointer to the buffer to receive the requested information.
- lpdwSize
[in, out] Pointer to the number of bytes available in the buffer specified by lpvBuffer. On completion, this parameter indicates the number of bytes actually transferred into the buffer.
Return Value
Returns TRUE if the function succeeds, and FALSE otherwise. To determine the cause of a failure, the extension should call GetLastError.
Remarks
This function reads information from the body of the Web client HTTP request into the buffer supplied by the extension. Therefore, the call can be used to read data from an HTML form that uses POST operations. The number of bytes that the Web Server reads when receiving POST data is specified in the HKEY_LOCAL_MACHINE\COMM\HTTPD\PostReadSize registry key. The Web Server will read in, at most, the number of bytes specified in this registry value before calling the ISAPI extension.
If the cbTotalBytes member of the EXTENSION_CONTROL_BLOCK structure is equal to the cbAvailable member, then the Web Server has read all the data from the client. If cbTotalBytes is greater than cbAvailable, then the ISAPI extension is responsible for making the Web Server read more data by way of ReadClient.
The ISAPI extension might need to make multiple calls to ReadClient to retrieve all the data. If the buffer size is less than the number of bytes available, then ReadClient will fill the available space.
The advantage of using multiple calls to ReadClient is related to Windows Embedded Compact memory constraints. For example, you might want your extension to use the Web Server to upload a 10MB file to a flash card. You have only 2 MB of RAM available on your device, but you have sufficient storage space available on the card. If the entire buffer from the client is read at once, the device will run out of physical memory. However, if your extension uses a 4KB buffer while calling ReadClient and then calls WriteFile immediately after each ReadClient call, the extension can minimize the amount of RAM required.
Note
ReadClient will time out after 60 seconds, regardless of any Web Server timeout settings. Your extension 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
Header |
httpext.h |
Library |
Developer Implemented |
See Also
Reference
Web Server Functions
ServerSupportFunction (ISAPI Extensions)
EXTENSION_CONTROL_BLOCK