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 服务器 API 支持使用版本 1.0 请求队列的现有应用程序，但是，使用 HTTP 服务器 API 的新开发应使用 HttpCreateRequestQueue 来创建请求队列;不应使用 HttpCreateHttpHandle。版本 2.0 API 仅与由 HttpCreateRequestQueue创建的版本 2.0 请求队列兼容。

HTTP 版本 2 请求队列需要手动配置;应用程序必须创建 URL 组并将一个或多个 URL 组与请求队列相关联，方法是调用 HttpSetUrlGroupProperty 与 HttpServerBindingProperty。应用程序通过在 Property 参数中使用所需配置调用 HttpSetRequestQueueProperty 来配置请求队列。有关创建和配置 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，或者在不再需要会话之前关闭。

应用程序必须在调用 HttpCreateRequestQueue之前调用 HttpInitialize。

要求

要求	价值
最低支持的客户端	Windows Vista [仅限桌面应用]
支持的最低服务器	Windows Server 2008 [仅限桌面应用]
目标平台	窗户
标头	http.h
库	Httpapi.lib
DLL	Httpapi.dll