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，请声明结构的实例，并将其设置为预定义值HTTPAPI_VERSION_2，然后再将其传递给 HttpCreateRequestQueue。

版本必须为 2.0; HttpCreateRequestQueue 不支持版本 1.0 请求队列。

[in, optional] Name

请求队列的名称。长度（以字节为单位）不能超过 MAX_PATH。

可选的 name 参数允许其他进程按名称访问请求队列。

[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 组，并通过调用 HttpServerBindingProperty 的 HttpSetUrlGroupProperty 将一个或多个 URL 组与请求队列相关联。应用程序通过使用 Property 参数中的所需配置调用 HttpSetRequestQueueProperty 来配置请求队列。有关创建和配置 URL 组的详细信息，请参阅 HttpCreateUrlGroup 和 HttpSetUrlGroupProperty。

只有在创建请求队列时，才能在 pSecurityAttributes 参数中提供安全属性。只有创建请求队列的应用程序才能在请求队列句柄上设置访问控制 Lists (ACL) ，以允许创建者应用程序以外的进程 () 权限打开、接收请求和发送请求队列句柄上的响应。默认情况下，除非应用程序在 ACL 中被授予权限，否则不允许应用程序打开请求队列。

创建者进程可以选择使用 HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER 标志来指示它不想接收 http 请求。

HttpCreateRequestQueue 允许应用程序使用 HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING 标志打开现有请求队列，并检索请求队列的句柄。非控制器应用程序可以使用此句柄来执行 HTTP I/O 操作。只有创建请求队列的应用程序可以通过调用 HttpSetRequestQueueProperty 来设置该队列的属性。

在应用程序终止之前或不再需要会话时，必须通过调用 HttpCloseRequestQueue 关闭由 HttpCreateRequestQueue 创建的请求队列的句柄。

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

要求

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