HttpCreateRequestQueue 函式（http.h）

發行項
11/20/2024

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 版，宣告結構的實例，並將它設定為預先定義的值HTTPAPI_VERSION_2，然後再將它傳遞給 HttpCreateRequestQueue。

版本必須是 2.0;HttpCreateRequestQueue 不支援 1.0 版要求佇列。

[in, optional] Name

要求佇列的名稱。長度，以位元組為單位，不能超過MAX_PATH。

選擇性名稱參數可讓其他進程依名稱存取要求佇列。

[in, optional] SecurityAttributes

包含要求佇列訪問許可權之 SECURITY_ATTRIBUTES 結構的指標。

開啟現有的要求佇列時，此參數必須 NULL。

[in, optional] Flags

flags 參數會定義要求佇列的範圍。此參數可以是下列其中一或多個參數：

價值	意義
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 版要求佇列需要手動設定;應用程式必須建立 URL 群組，並藉由呼叫 HTTPSetUrlGroupProperty HttpSetUrlGroupProperty 與 HttpServerBindingProperty，建立一或多個 URL 群組與要求佇列的關聯。應用程式會呼叫 HttpSetRequestQueueProperty，並在 Property 參數中使用所需的組態來設定要求佇列。如需建立和設定 URL 群組的詳細資訊，請參閱 HttpCreateUrlGroup 和 HttpSetUrlGroupProperty。

只有在建立要求佇列時，pSecurityAttributes 中才會提供安全性屬性 參數。只有建立要求佇列的應用程式可以在要求佇列句柄上設定訪問控制清單（ACL），以允許進程（除了建立者應用程式外）許可權開啟、接收要求，以及在要求佇列句柄上傳送回應。根據預設，除非應用程式已在 ACL 中授與許可權，否則不允許開啟要求佇列。

建立者進程可以選擇性地使用 HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER 旗標來指出它不想接收 HTTP 要求。

HttpCreateRequestQueue 可讓應用程式開啟具有 HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING 旗標的現有要求佇列，並擷取要求佇列的句柄。非控制器應用程式可以使用此句柄來執行 HTTP I/O 作業。只有建立要求佇列的應用程式可以藉由呼叫 HTTPSetRequestQueueProperty來設定其屬性。

HttpCreateRequestQueue 所建立要求佇列的句柄，必須在應用程式終止或不再需要會話之前呼叫 HttpCloseRequestQueue 來關閉。

應用程式必須先呼叫 HttpInitialize，才能呼叫 HttpCreateRequestQueue。

要求

要求	價值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	http.h
連結庫	Httpapi.lib
DLL	Httpapi.dll