HttpReceiveHttpRequest 함수(http.h)

아티클
08/24/2023

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

다음 값 중 하나일 수 있는 매개 변수입니다.

값	의미
0(영)	요청 헤더만 검색됩니다. 엔터티 본문이 복사되지 않습니다.
HTTP_RECEIVE_REQUEST_FLAG_COPY_BODY	사용 가능한 엔터티 본문은 요청 헤더와 함께 복사됩니다. HTTP_REQUEST 구조체의 pEntityChunks 멤버는 엔터티 본문을 가리킵니다.
HTTP_RECEIVE_REQUEST_FLAG_FLUSH_BODY	모든 엔터티 본문은 요청 헤더와 함께 복사됩니다. 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 완료 메커니즘을 통해 나중에 검색됨을 나타냅니다.

함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.

값	의미
ERROR_INVALID_PARAMETER	제공된 매개 변수 중 하나 이상이 사용할 수 없는 형식입니다.
ERROR_NOACCESS	제공된 매개 변수 중 하나 이상이 잘못되었거나 정렬되지 않은 메모리 버퍼를 가리킵니다. pRequestBuffer 매개 변수는 메모리 맞춤이 HTTP_REQUEST 구조체에 대한 메모리 맞춤 요구 사항보다 크거나 같은 유효한 메모리 버퍼를 가리킵니다.
ERROR_MORE_DATA	RequestBufferLength 값은 수신된 요청 헤더의 크기보다 크거나 같지만 요청 구조 및 엔터티 본문의 결합된 크기만큼 크지는 않습니다. 엔터티 본문의 나머지 부분을 읽는 데 필요한 버퍼 크기는 NULL이 아닌 경우 및 호출이 동기인 경우 pBytesReceived 매개 변수에 반환됩니다. 모든 데이터를 검색할 수 있을 만큼 큰 버퍼를 사용하여 함수를 다시 호출합니다.
ERROR_HANDLE_EOF	지정된 요청이 이미 완전히 검색되었습니다. 이 경우 pBytesReceived 가 가리키는 값은 의미가 없으며 pRequestBuffer 를 검사하면 안 됩니다.
기타	WinError.h에 정의된 시스템 오류 코드 입니다.

설명

지정된 요청을 검색하려면 둘 이상의 호출이 필요할 수 있습니다. 예를 들어 Flags 매개 변수가 0으로 설정된 경우 HttpReceiveHttpRequest 는 요청 헤더 구조만 버퍼에 복사하고 엔터티 본문을 복사하지 않습니다. 이 경우 HttpReceiveRequestEntityBody 함수를 사용하여 엔터티 본문을 검색하거나 HttpReceiveHttpRequest에 대한 두 번째 호출을 수행할 수 있습니다.

또는 애플리케이션에서 제공하는 버퍼가 요청의 전체 또는 일부를 수신하기에 충분하지 않을 수 있습니다. 요청의 적어도 일부를 수신하려면 애플리케이션이 대부분의 HTTP 요청을 수용하는 4KB 이상의 버퍼를 제공하는 것이 좋습니다. 또는 알 수 없는 헤더로 구문 분석된 인증 헤더는 최대 12KB를 추가할 수 있으므로 인증/권한 부여를 사용하는 경우 버퍼 크기가 16KB 이상인 것이 좋습니다.

HttpReceiveHttpRequest가 ERROR_MORE_DATA 반환하는 경우 애플리케이션은 계속해서 추가 호출을 실행하여 HTTP_REQUEST 전달하여 각 추가 호출에서 요청을 식별합니다. ERROR_HANDLE_EOF 반환될 때까지 첫 번째 호출에서 반환된 RequestId 값입니다.

참고 애플리케이션은 사용된 경우 콘텐츠 협상 헤더를 포함하여 모든 관련 요청 헤더를 검사하고 헤더 콘텐츠에 따라 요청을 적절하게 실패해야 합니다. HttpReceiveHttpRequest 는 헤더 줄이 제대로 종료되고 잘못된 문자가 포함되지 않도록 합니다.

요구 사항


지원되는 최소 클라이언트	Windows Vista, WINDOWS XP SP2 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	http.h
라이브러리	Httpapi.lib
DLL	Httpapi.dll