| |
| BOOL ReceiveRequest( |
| |
UINT nClientId, |
|
| |
DWORD dwOptions, |
|
| |
LPHTTPREQUEST lpRequest, |
|
| |
LPVOID lpvBuffer, |
|
| |
LPDWORD lpdwLength |
|
| ); |
Receive the request that was sent by the client to the server.
Parameters
- nClientId
- An unsigned integer which uniquely identifies the client
session.
- dwOptions
- An unsigned integer which specifies how the client request data
will be copied. It may be one of the following values:
| Value |
Description |
| HTTP_REQUEST_DEFAULT |
If the lpdwLength parameter points to a integer with
a non-zero value, the lpvBuffer parameter is considered
to be a pointer to a block of memory that has been allocated to
store the request data. This is the same as specifying the
HTTP_REQUEST_MEMORY option. If the lpdwLength parameter
points to an integer with a value of zero, the lpvBuffer
parameter is considered to be a pointer to an HGLOBAL memory
handle. This is the same as specifying the HTTP_REQUEST_HGLOBAL
option. |
| HTTP_REQUEST_MEMORY |
The lpvBuffer parameter is a pointer
to a block of memory that has been allocated to store the
request data. The maximum number of bytes of data that can
stored is determined by the value of the integer that the
lpdwLength parameter points to. When the method returns,
that value will updated with with actual number of bytes copied
into the buffer. |
| HTTP_REQUEST_STRING |
The lpvBuffer parameter is a pointer
to a string buffer that has been allocated to store the request data.
The maximum number of bytes of data that can stored is
determined by the value of the integer that the lpdwLength
parameter points to. When the method returns, that value will
updated with with actual number of bytes copied into the buffer. |
| HTTP_REQUEST_HGLOBAL |
The lpvBuffer parameter is a pointer
to an HGLOBAL memory handle. When the method returns, the
handle will reference a block of memory that contains the
request data submitted by the client. The lpdwLength
parameter will contain the number of bytes copied to the buffer. |
| HTTP_REQUEST_FILE |
The lpvBuffer parameter is a pointer to a
string which specifies the name of a file that
will contain the request data. If the file does not exist, it
will be created. If it does exist, the contents will be
replaced. This option is typically used in conjunction with the
PUT command. If the lpdwLength parameter is not NULL, the
value it points to will be updated with the actual number of
bytes stored in the file. |
| HTTP_REQUEST_HANDLE |
The lpvBuffer parameter is a handle to an open file.
This option is typically used in conjunction with the POST or
PUT commands. If the lpdwLength parameter is not NULL,
the value it points to will be updated with the actual number of
bytes written to the file. If this option is specified, the
request data will be written from the current position in the
file and will advance the file pointer by the number of bytes
received from the client. |
- lpRequest
- A pointer to a HTTPREQUEST structure which contains
information about the request from the client. This parameter
cannot be NULL. The structure that is passed to this method
must have all members set to a value of zero except the
dwSize member, which must be initialized to the size of
the structure.
- lpvBuffer
- A pointer to the buffer that will contain any request data that
was submitted by the client. The dwOptions parameter
determines if this pointer references a block of memory, a
null-terminated string buffer, a global memory handle or a file
name. If this parameter is NULL, any data submitted by the client
will not be copied.
- lpdwLength
- A pointer to an unsigned integer that will contain the number of
bytes of data submitted by the client when the method returns. If
the lpvBuffer parameter specifies a memory or string buffer,
this value must be initialized to the maximum size of the buffer
before the method is called. If the lpvBuffer parameter
points to a global memory handle, this value must be initialized to
zero. If lpvBuffer is NULL or specifies a file name, this
parameter may be NULL.
Return Value
If the method succeeds, the return value is non-zero. If the
method fails, the return value is zero. To get extended error
information, call the GetLastError method.
Remarks
The ReceiveRequest method is called within an
OnCommand event handler to process the command issued by the
client and return information about the request to the server
application. It is only necessary for the application to call
this method if it wants to implement its own custom handling for a
command. It is recommended that most applications use the
default command processing for standard commands such as GET and POST
to ensure that the appropriate security checks are performed and the
response conforms to the protocol standard.
This method may only be called once per command issued by the
client and the data referenced in the HTTPREQUEST structure
only remains valid while the client is connected to the server. You
should never attempt to directly modify the data referenced by any of
the structure members. If you wish to store or modify any of the
string values returned in the structure, you should allocate a buffer
large enough to store the contents of the string, including the
terminating null character, and copy the string into that buffer.
If the HTTP_REQUEST_HGLOBAL option is used to return a copy of the
request data in a global memory buffer, the HGLOBAL handle must be
freed by the application when the data is no longer needed. Failure to
free this handle will result in a memory leak.
If the HTTP_REQUEST_HANDLE option is used to write a copy of the
request data to an open file, the handle must reference a disk file
that was opened or created using the CreateFile function with
GENERIC_WRITE access. It cannot be a handle to a device or named pipe.
If the method succeeds, the file pointer is advanced by the number
of bytes of request data submitted by the client. If the method
fails, the file pointer is returned to its original position prior to
the method being called.
Example
// Initialize the HTTPREQUEST structure
HTTPREQUEST httpRequest;
ZeroMemory(&httpRequest, sizeof(httpRequest));
httpRequest.dwSize = sizeof(httpRequest);
// Return the data in a global memory buffer
HGLOBAL hgblBuffer = NULL;
DWORD dwLength = 0;
bSuccess = pServer->ReceiveRequest(nClientId,
HTTP_REQUEST_HGLOBAL,
&httpRequest,
&hgblBuffer,
&dwLength);
if (bSuccess && hgblBuffer != NULL)
{
LPBYTE lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
if (lpBuffer != NULL)
{
// Process dwLength bytes of data submitted by the client
}
GlobalUnlock(hgblBuffer);
GlobalFree(hgblBuffer);
}
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cshtsv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
SendResponse,
HTTPREQUEST
|
|