HttpCreateRequestQueue 함수(http.h)

아티클
08/24/2023

HttpCreateRequestQueue 함수는 새 요청 큐를 만들거나 기존 요청 큐를 엽니다.

이 함수는 HTTP 버전 1.0 HttpCreateHttpHandle 함수를 대체합니다.

구문

HTTPAPI_LINKAGE ULONG HttpCreateRequestQueue(
  [in]           HTTPAPI_VERSION      Version,
  [in, optional] PCWSTR               Name,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in, optional] ULONG                Flags,
  [out]          PHANDLE              RequestQueueHandle
);

매개 변수

[in] Version

요청 큐 버전을 나타내는 HTTPAPI_VERSION 구조체입니다. 버전 2.0의 경우 구조체의 instance 선언하고 httpCreateRequestQueue에 전달하기 전에 HTTPAPI_VERSION_2 미리 정의된 값으로 설정합니다.

버전은 2.0이어야 합니다. HttpCreateRequestQueue 는 버전 1.0 요청 큐를 지원하지 않습니다.

[in, optional] Name

요청 큐의 이름입니다. 길이(바이트)는 MAX_PATH 초과할 수 없습니다.

선택적 이름 매개 변수를 사용하면 다른 프로세스에서 이름으로 요청 큐에 액세스할 수 있습니다.

[in, optional] SecurityAttributes

요청 큐에 대한 액세스 권한이 포함된 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다.

이 매개 변수는 기존 요청 큐를 열 때 NULL 이어야 합니다.

[in, optional] Flags

flags 매개 변수는 요청 큐의 scope 정의합니다. 이 매개 변수는 다음 중 하나 이상일 수 있습니다.

값	의미
HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER	이 플래그를 사용하여 만든 요청 큐에 대한 핸들은 I/O 작업을 수행하는 데 사용할 수 없습니다. 이 플래그는 요청 큐 핸들을 만들 때만 설정할 수 있습니다.
HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING	HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING 플래그를 사용하면 애플리케이션이 이름으로 기존 요청 큐를 열고 요청 큐 핸들을 검색할 수 있습니다. pName 매개 변수에는 유효한 요청 큐 이름이 포함되어야 합니다. NULL일 수 없습니다.

[out] RequestQueueHandle

요청 큐에 대한 핸들을 수신하는 변수에 대한 포인터입니다. 이 매개 변수에는 유효한 포인터가 포함되어야 합니다. NULL일 수 없습니다.

반환 값

함수가 성공하면 NO_ERROR 반환됩니다.

함수가 실패하면 다음 오류 코드 중 하나를 반환합니다.

값	의미
ERROR_REVISION_MISMATCH	Version 매개 변수에 잘못된 버전이 포함되어 있습니다.
ERROR_INVALID_PARAMETER	요청 큐 이름의 길이(바이트)는 MAX_PATH 초과할 수 없습니다. 기존 요청 큐를 열 때 pSecurityAttributes 매개 변수는 NULL 이어야 합니다. HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER 요청 큐를 만들 때만 설정할 수 있습니다. HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING 애플리케이션에 기존 요청 큐를 열 수 있는 권한이 있는 경우에만 설정할 수 있습니다. 이 경우 pReqQueueHandle 매개 변수는 유효한 포인터여야 하며 pName 매개 변수에는 유효한 요청 큐 이름이 포함되어야 합니다. NULL일 수 없습니다. HttpCreateRequestQueue에서 반환된 pReqQueueHandle 매개 변수는 NULL입니다.
ERROR_ALREADY_EXISTS	pName 매개 변수는 동일한 이름을 포함하는 기존 요청 큐와 충돌합니다.
ERROR_ACCESS_DENIED	호출 프로세스에는 요청 큐를 열 수 있는 권한이 없습니다.
ERROR_DLL_INIT_FAILED	애플리케이션은 HttpCreateRequestQueue를 호출하기 전에 HttpInitialize를 호출하지 않았습니다.

설명

HTTP Server API는 버전 1.0 요청 큐를 사용하여 기존 애플리케이션을 지원합니다. 그러나 HTTP Server API를 사용한 새 개발에서는 HttpCreateRequestQueue 를 사용하여 요청 큐를 만들어야 합니다. HttpCreateHttpHandle을 사용하면 안 됩니다. 버전 2.0 API는 HttpCreateRequestQueue에서 만든 버전 2.0 요청 큐와만 호환됩니다.

HTTP 버전 2 요청 큐에는 수동 구성이 필요합니다. 애플리케이션은 HTTPServerBindingProperty와 HttpSetUrlGroupProperty를 호출하여 URL 그룹을 만들고 하나 이상의 URL 그룹을 요청 큐와 연결해야 합니다. 애플리케이션은 Property 매개 변수에서 원하는 구성을 사용하여 HttpSetRequestQueueProperty를 호출하여 요청 큐를 구성합니다. URL 그룹을 만들고 구성하는 방법에 대한 자세한 내용은 HttpCreateUrlGroup 및 HttpSetUrlGroupProperty를 참조하세요.

보안 특성은 요청 큐를 만들 때만 pSecurityAttributes 매개 변수로 제공할 수 있습니다. 요청 큐를 만드는 애플리케이션만 요청 큐 핸들에서 ACL(Access Control Lists)을 설정하여 프로세스(작성자 애플리케이션 이외의) 권한이 요청 큐 핸들에서 요청을 열고, 수신하고, 응답을 보낼 수 있도록 할 수 있습니다. 기본적으로 애플리케이션은 ACL에서 권한이 부여되지 않은 한 요청 큐를 열 수 없습니다.

작성자 프로세스는 필요에 따라 HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER 플래그를 사용하여 http 요청을 수신하지 않음을 나타낼 수 있습니다.

HttpCreateRequestQueue 를 사용하면 애플리케이션이 HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING 플래그를 사용하여 기존 요청 큐를 열고 요청 큐에 대한 핸들을 검색할 수 있습니다. 비 컨트롤러 애플리케이션은 이 핸들을 사용하여 HTTP I/O 작업을 수행할 수 있습니다. 요청 큐를 만드는 애플리케이션만 HttpSetRequestQueueProperty를 호출하여 해당 큐에 속성을 설정할 수 있습니다.

HttpCreateRequestQueue에서 만든 요청 큐에 대한 핸들은 애플리케이션이 종료되기 전에 또는 세션이 더 이상 필요하지 않은 경우 HttpCloseRequestQueue를 호출하여 닫아야 합니다.

애플리케이션은 HttpCreateRequestQueue를 호출하기 전에 HttpInitialize를 호출해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	http.h
라이브러리	Httpapi.lib
DLL	Httpapi.dll