HttpCreateRequestQueue 函式 (http.h)

發行項
02/26/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 群組，並將一或多個 URL 群組與要求佇列建立關聯，方法是呼叫 HttpSetUrlGroupProperty 與 HttpServerBindingProperty。應用程式會呼叫 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 [僅限傳統型應用程式]
目標平台	Windows
標頭	http.h
程式庫	Httpapi.lib
Dll	Httpapi.dll