WPUCreateSocketHandle 函数 (ws2spi.h)

项目
08/28/2023

WPUCreateSocketHandle 函数创建新的套接字句柄。

语法

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

参数

[in] dwCatalogEntryId

标识调用服务提供程序的描述符。

[in] dwContext

要与新的套接字句柄关联的上下文值。

[out] lpErrno

指向错误代码的指针。

返回值

如果未发生错误， WPUCreateSocketHandle 将返回新的套接字句柄。否则，它将返回INVALID_SOCKET，并且 lpErrno 中提供了特定的错误代码。

错误代码	含义
WSAENOBUFS	没有足够的缓冲区可用于创建新的套接字句柄。

注解

WPUCreateSocketHandle 函数为指定的提供程序创建新的套接字句柄。 WPUCreateSocketHandle 创建的句柄与真正的文件系统句柄无法区分。这在两个方面都很重要。首先，Windows 套接字 2 体系结构负责将文件系统函数 ReadFile 和 WriteFile 分别重定向到此服务提供商的 LPWSPRecv 和 LPWSPSend 函数。其次，在支持完成端口的操作系统中，Windows 套接字 2 体系结构支持将完成端口与套接字句柄相关联，并使用它来报告重叠的 I/O 完成。

**注意** 重定向 ReadFile 和 WriteFile 的机制必须涉及用户到内核的转换以访问重定向程序，然后进行内核到用户的转换，以访问 [LPWSPRecv] (nc-ws2spi-lpwsprecv.md) 或 [LPWSPSend] (nc-ws2spi-lpwspsend.md) 。返回时，这些转换将反向回溯。这会对性能造成重大损失。任何使用 WPUCreateSocketHandle 创建其套接字句柄的服务提供程序都不应在其WSAProtocol_Info结构中设置 XP1_IFS_HANDLES 。客户端应将缺少XP1_IFS_HANDLES作为指导，以避免使用 ReadFile 和 WriteFile。

**注意** 将完成端口机制与使用 WPUCreateSocketHandle 创建的套接字句柄一起使用不会造成异常性能损失。服务提供商应使用 WPUCompleteOverlappedRequest 来宣布完成可能涉及完成端口的重叠 I/O 操作。客户端可以自由使用操作系统函数来创建、关联和使用完成通知的完成端口 (例如 CreateIoCompletionPort、 GetQueuedCompletionStatus，有关详细信息) ，请参阅相关操作系统文档。请注意，完成端口未与 Windows 套接字 2 提供的其他异步通知机制集成。也就是说，客户端可以执行包含多个事件和完成回调的多重等待，但是没有预定义的方式让多等待包括完成端口。

分层服务提供程序注意事项

此过程对分层服务提供商特别感兴趣。分层服务提供程序可以使用此过程而不是 WPUModifyIFSHandle 来创建它向客户端公开的套接字句柄。使用此过程的优点是可以保证涉及套接字的所有 I/O 请求都通过此服务提供程序。即使客户端假定套接字是文件系统句柄，并调用文件系统函数 ReadFile 和 WriteFile (也是如此，尽管它会为此假设) 付出性能损失。

保证所有 I/O 通过此层是需要在实际 I/O 操作之前或之后处理 I/O 流的层的要求。使用 WPUCreateSocketHandle 创建套接字句柄，并在 WSPStartup 时指定适当的服务提供程序接口过程调度表，可确保层有机会参与启动每个 I/O 操作。当客户端请求重叠的 I/O 操作时，此服务提供程序层通常必须安排进入 I/O 完成通知的路径。

若要了解为何如此，请考虑当客户端将完成端口与套接字句柄关联以实现重叠 I/O 完成通知时会发生什么情况。端口与此层公开的套接字句柄相关联，而不是与下一层的套接字句柄相关联。此层无法确定是否已关联完成端口或端口是什么。当此层调用下一层的 I/O 操作时，它将使用下一层的套接字句柄。下一层的套接字句柄将不具有相同的完成端口关联。如果没有一些额外的帮助，客户端的预期完成端口通知将不会发生。

分层服务提供商处理此问题的通常方式是，在下一层中调用 I/O 操作时，替换不同的重叠 I/O 结构和不同的重叠 I/O 参数。替换重叠 I/O 结构引用客户端存储的重叠结构和参数。下一层的调用将设置回调通知。发生回调通知时，此层执行所需的任何后处理，检索它代表客户端存储的重叠 I/O 信息，放弃替代结构，并将相应的完成通知转发给客户端。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	ws2spi.h