WriteClient

The WriteClient function is a callback function supplied in the EXTENSION_CONTROL_BLOCK (ECB) for a request sent to the ISAPI application. This function sends data present in the given buffer to the client that made the request.

BOOL WriteClient(

Parameters

ConnID

[in] A logical connection identifier for identifying the client to whom the response data should be sent.

Buffer

[in] A pointer to the buffer containing the data to be sent.

lpdwBytes

[in/out] A pointer to a DWORD that contains the number of bytes in the buffer that need to be sent out when the call is made, and contains the number of bytes of data successfully sent out for synchronous write operations. For asynchronous write operations, the returned value has no meaning.

dwReserved

A DWORD containing flags indicating how the I/O operation should be handled. The following flags are supported:

Return Values

If the function is successful, a value of TRUE is returned. If an error occurs, a value of FALSE is returned. The GetLastError function can be called to determine the cause of the error.

Remarks

The WriteClient function attempts to write the data in the supplied buffer to the socket in which the client request came. For synchronous writes, it attempts to the write in the called thread and the I/O may block trying to send the data to the client. On completion, the WriteClient function returns the number of bytes sent in lpdwBytes.

For asynchronous writes, the WriteClient function submits the write operation to the asynchronous thread queue and returns from the call immediately. At this point, the ISAPI application can choose to do more background processing or return from the HttpExtensionProc function with a HSE_STATUS_PENDING. When the I/O operation is completed, the server calls the callback function submitted by the ISAPI application with the ECB, context value, number of bytes sent, and error codes (if there are any errors).

It is the responsibility of the ISAPI application to do further processing and to use the ServerSupportFunction(HSE_DONE_WITH_SESSION) function to notify the server when it is done processing the request.

Only one outstanding asynchronous I/O operation is permitted per request. This includes asynchronous WriteClient, asychronous TransmitFile, or a ServerSupportFunction call with HSE_REQ_SEND_URL.

Asynchronous I/O Support

Previous versions of this documentation have supported synchronous I/O operations using the callback functions, ReadClient and WriteClient. However, the ability to support asynchronous operations is important because it frees up a server pool thread from being blocked in completing the I/O operation. In addition, the Internet server engine already has built-in support to manage asynchronous I/O operations using the completion ports and server thread pool.

Support for asynchronous I/O operations were initially planned for a later version of this documentation. However, because of the need to support asynchronous I/O operations, a Microsoft-specific extension has been provided in this documentation. Thus, asynchronous write operations are supported in this documentation using the existing callback function WriteClient, with a special flag indicating that the operation has to be performed asynchronously. In addition, this documentation also provides a mechanism for requesting that the server transmit a file using the TransmitFile function. This function is a Win32 function that supports fast transmission of a file-from-file system over any stream sockets. It is supported in the Microsoft Windows Sockets implementation in Windows NT 3.51 and later.