HttpReceiveHttpRequest 함수(http.h)
HttpReceiveHttpRequest 함수는 지정된 요청 큐에서 동기 또는 비동기적으로 사용 가능한 다음 HTTP 요청을 검색합니다.
구문
HTTPAPI_LINKAGE ULONG HttpReceiveHttpRequest(
[in] HANDLE RequestQueueHandle,
[in] HTTP_REQUEST_ID RequestId,
[in] ULONG Flags,
[out] PHTTP_REQUEST RequestBuffer,
[in] ULONG RequestBufferLength,
[out, optional] PULONG BytesReturned,
[in, optional] LPOVERLAPPED Overlapped
);
매개 변수
[in] RequestQueueHandle
사용 가능한 다음 요청을 검색할 요청 큐에 대한 핸들입니다. 요청 큐가 생성되고 HttpCreateRequestQueue 함수에 대한 호출에서 해당 핸들이 반환됩니다.
Windows Server 2003 SP1 및 Windows XP SP2 사용: 요청 큐에 대한 핸들은 HttpCreateHttpHandle 함수에 의해 만들어집니다.
[in] RequestId
요청을 검색하는 첫 번째 호출에서 이 매개 변수는 HTTP_NULL_ID 합니다. 그런 다음, 전체 요청을 검색하는 데 둘 이상의 호출이 필요한 경우 pRequestBuffer가 가리키는 HTTP_REQUEST 구조체의 RequestId 멤버에 반환된 값으로 RequestID를 설정하여 HttpReceiveHttpRequest 또는 HttpReceiveRequestEntityBody를 호출할 수 있습니다.
[in] Flags
다음 값 중 하나일 수 있는 매개 변수입니다.
| 값 | 의미 |
|---|---|
|
요청 헤더만 검색됩니다. 엔터티 본문이 복사되지 않습니다. |
|
사용 가능한 엔터티 본문은 요청 헤더와 함께 복사됩니다. HTTP_REQUEST 구조체의 pEntityChunks 멤버는 엔터티 본문을 가리킵니다. |
|
모든 엔터티 본문은 요청 헤더와 함께 복사됩니다. HTTP_REQUEST 구조체의 pEntityChunks 멤버는 엔터티 본문을 가리킵니다. |
[out] RequestBuffer
함수가 HTTP 요청에 대한 HTTP_REQUEST 구조체 및 엔터티 본문을 복사하는 버퍼에 대한 포인터입니다. HTTP_REQUEST. RequestId 에는 애플리케이션이 후속 호출 HttpReceiveRequestEntityBody, HttpSendHttpResponse 또는 HttpSendResponseEntityBody 호출에 사용할 수 있는 이 HTTP 요청에 대한 식별자가 포함되어 있습니다.
[in] RequestBufferLength
pRequestBuffer 버퍼의 크기(바이트)입니다.
[out, optional] BytesReturned
(선택 사항) 엔터티 본문의 크기(바이트) 또는 엔터티 본문의 나머지 부분을 수신하는 변수에 대한 포인터입니다.
pOverlapped를 사용하여 비동기 호출을 할 때 pBytesReceived를NULL로 설정합니다. 그렇지 않으면 pOverlapped 가 NULL로 설정된 경우 pBytesReceived 는 유효한 메모리 주소를 포함해야 하며 NULL로 설정되지 않아야 합니다.
[in, optional] Overlapped
비동기 호출의 경우 pOverlapped 를 OVERLAPPED 구조를 가리키도록 설정합니다. 동기 호출의 경우 NULL로 설정합니다.
동기 호출은 요청이 지정된 큐에 도착하고 그 중 일부 또는 전부가 검색될 때까지 차단되는 반면, 비동기 호출은 즉시 ERROR_IO_PENDING 반환하고 호출 애플리케이션은 GetOverlappedResult 또는 I/O 완료 포트를 사용하여 작업이 완료되는 시기를 결정합니다. 동기화에 OVERLAPPED 구조를 사용하는 방법에 대한 자세한 내용은
동기화 및 겹치는 입력 및 출력.
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수를 비동기적으로 사용하는 경우 ERROR_IO_PENDING 반환 값은 다음 요청이 아직 준비되지 않았으며 일반적인 겹치는 I/O 완료 메커니즘을 통해 나중에 검색됨을 나타냅니다.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.
| 값 | 의미 |
|---|---|
|
제공된 매개 변수 중 하나 이상이 사용할 수 없는 형식입니다. |
|
제공된 매개 변수 중 하나 이상이 잘못되었거나 정렬되지 않은 메모리 버퍼를 가리킵니다. pRequestBuffer 매개 변수는 메모리 맞춤이 HTTP_REQUEST 구조체에 대한 메모리 맞춤 요구 사항보다 크거나 같은 유효한 메모리 버퍼를 가리킵니다. |
|
RequestBufferLength 값은 수신된 요청 헤더의 크기보다 크거나 같지만 요청 구조 및 엔터티 본문의 결합된 크기만큼 크지는 않습니다. 엔터티 본문의 나머지 부분을 읽는 데 필요한 버퍼 크기는 NULL이 아닌 경우 및 호출이 동기인 경우 pBytesReceived 매개 변수에 반환됩니다. 모든 데이터를 검색할 수 있을 만큼 큰 버퍼를 사용하여 함수를 다시 호출합니다. |
|
지정된 요청이 이미 완전히 검색되었습니다. 이 경우 pBytesReceived 가 가리키는 값은 의미가 없으며 pRequestBuffer 를 검사하면 안 됩니다. |
|
WinError.h에 정의된 시스템 오류 코드 입니다. |
설명
지정된 요청을 검색하려면 둘 이상의 호출이 필요할 수 있습니다. 예를 들어 Flags 매개 변수가 0으로 설정된 경우 HttpReceiveHttpRequest 는 요청 헤더 구조만 버퍼에 복사하고 엔터티 본문을 복사하지 않습니다. 이 경우 HttpReceiveRequestEntityBody 함수를 사용하여 엔터티 본문을 검색하거나 HttpReceiveHttpRequest에 대한 두 번째 호출을 수행할 수 있습니다.
또는 애플리케이션에서 제공하는 버퍼가 요청의 전체 또는 일부를 수신하기에 충분하지 않을 수 있습니다. 요청의 적어도 일부를 수신하려면 애플리케이션이 대부분의 HTTP 요청을 수용하는 4KB 이상의 버퍼를 제공하는 것이 좋습니다. 또는 알 수 없는 헤더로 구문 분석된 인증 헤더는 최대 12KB를 추가할 수 있으므로 인증/권한 부여를 사용하는 경우 버퍼 크기가 16KB 이상인 것이 좋습니다.
HttpReceiveHttpRequest가 ERROR_MORE_DATA 반환하는 경우 애플리케이션은 계속해서 추가 호출을 실행하여 HTTP_REQUEST 전달하여 각 추가 호출에서 요청을 식별합니다. ERROR_HANDLE_EOF 반환될 때까지 첫 번째 호출에서 반환된 RequestId 값입니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista, WINDOWS XP SP2 [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | http.h |
| 라이브러리 | Httpapi.lib |
| DLL | Httpapi.dll |