LPNSPV2SETSERVICEEX回调函数 (ws2spi.h)

项目
08/28/2023

NSPv2SetServiceEx 函数在命名空间服务提供程序版本 2 的命名空间中注册或取消注册名称或服务实例， (NSPv2) 提供程序。

语法

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

参数

[in] hAsyncCall

从上一次调用 NSPv2LookupServiceBegin 返回的句柄，用于异步调用。

[in] lpProviderId

指向在其中注册名称或服务的特定命名空间提供程序的 GUID 的指针。

[in] lpqsRegInfo

注册时要更新的属性信息。

[in] essOperation

请求的操作类型。

此参数可以是 Winsock2.h 头文件中定义的 WSAESETSERVICEOP 枚举类型的值之一。

值	含义
RNRSERVICE_REGISTER 0	注册服务。对于 NetWare 环境中使用的服务广告协议 (SAP) 命名空间，这意味着发送定期广播。这是域名系统 (DNS) 命名空间的 NOP。对于永久性数据存储，这意味着要更新地址信息。
RNRSERVICE_DEREGISTER 1	取消注册服务。对于 SAP 命名空间，这意味着停止发送定期广播。这是 DNS 命名空间的 NOP。对于永久性数据存储，这意味着要删除地址信息。
RNRSERVICE_DELETE 2	从动态名称和永久性空格中删除服务。对于使用 SERVICE_MULTIPLE 标志) (多个CSADDR_INFO结构表示的服务，将仅删除提供的地址，这必须与注册服务时提供的相应 “CSADDR_INFO” 结构完全匹配。

[in] dwControlFlags

控制所请求的操作的一组标志。

此参数的可能值在 Winsock2.h 头文件中定义。

值	含义
SERVICE_MULTIPLE 0x00000001	控制操作的范围。设置此值时，仅对给定地址集执行操作。注册操作不会使现有地址失效，而取消注册操作只会使给定的地址集失效。如果此值不存在，服务地址将作为一个组进行管理。在添加给定地址集之前，注册或取消注册会使所有现有地址失效。

值

含义

SERVICE_MULTIPLE

0x00000001

控制操作的范围。

设置此值时，仅对给定地址集执行操作。注册操作不会使现有地址失效，而取消注册操作只会使给定的地址集失效。

如果此值不存在，服务地址将作为一个组进行管理。在添加给定地址集之前，注册或取消注册会使所有现有地址失效。

[in] lpvClientSessionArg

指向客户端会话的指针。

返回值

如果例程成功，函数应返回NO_ERROR (零) 。如果例程失败，它应返回 SOCKET_ERROR (即 1) ，并且必须使用 WSASetLastError 设置相应的错误代码。

错误代码	含义
WSA_NOT_ENOUGH_MEMORY	没有足够的内存可用于执行此操作。
WSAEACCES	调用例程没有足够的权限来安装服务。
WSAEINVAL	此提供程序的一个或多个参数无效或缺失。
WSAEOPNOTSUPP	此操作不受支持。如果命名空间提供程序未实现此函数，则返回此错误。如果指定的 dwControlCode 是无法识别的命令，则也可能返回此错误。
WSASERVICE_NOT_FOUND	服务未知。在指定的命名空间中找不到该服务。

注解

NSPv2SetServiceEx 函数用作命名空间服务提供程序版本 2 的一部分， (Windows Vista 及更高版本上提供的 NSPv2) 体系结构。

在 Windows Vista 和 Windows Server 2008 上， NSPv2SetServiceEx 函数只能用于NS_EMAIL命名空间提供程序上的操作。

每次新客户端进程开始使用命名空间提供程序时，都会调用 NSPv2Startup 函数。提供程序可以使用 ppvClientSessionArg 参数指向的客户端会话参数来存储有关此会话的信息。此客户端会话参数可以传递到 lpvClientSessionArg 参数中的 NSPv2SetServiceEx 函数。

NSPv2SetServiceEx 函数是可选的，具体取决于 NSPv2 提供程序的要求。如果未实现 NSPv2SetServiceEx 函数，则 NSPv2 函数指针可以是指向始终返回 NO_ERROR的存根函数。

下表列出了 essOperation 和 dwControlFlags 参数的值可能组合。

essOperation	dwControlFlags	服务已存在	服务不存在
RNRSERVICE_REGISTER	无	覆盖对象。仅使用指定的地址。对象为 REGISTERED。	创建新对象。仅使用指定的地址。对象为 REGISTERED。
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	汇报对象。将新地址添加到现有集。对象为 REGISTERED。	创建新对象。使用指定的所有地址。对象为 REGISTERED。
RNRSERVICE_DEREGISTER	无	删除所有地址，但不从命名空间中删除对象。对象为 DEREGISTERED。	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	汇报对象。仅删除指定的地址。仅当不存在地址时，将对象标记为 DEREGISTERED。不从命名空间中删除。	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	无	从命名空间中删除对象。	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	仅删除指定的地址。仅当未保留任何地址时，才会从命名空间中删除对象。	WSASERVICE_NOT_FOUND

当 dwControlFlags 参数设置为 SERVICE_MULTIPLE 时，这使应用程序能够独立管理其地址。当应用程序必须单独管理其协议或服务驻留在多台计算机上时，这非常有用。例如，当一个服务使用多个协议时，一个侦听套接字可能会中止，但其他套接字仍可正常运行。在此示例中，服务可以取消注册已中止的地址，而不会影响其他地址。

使用 SERVICE_MULTIPLE 时，应用程序不得让旧地址保留在对象中。如果应用程序在未发出 RNRSERVICE_DEREGISTER 请求的情况下中止，则可能会发生这种情况。当服务注册时，它应存储其地址。下一次调用时，服务应在注册新地址之前显式取消注册这些旧地址。

如果未实现 NSPv2SetServiceEx 函数，则返回 WSAEOPNOTSUPP 的存根函数应截获对该函数的调用。指向 NSPV2_ROUTINE 结构中未实现的 NSPv2SetServiceEx 函数的 NSPv2 函数指针应指向存根函数。

服务属性

下表列出了 WSAQUERYSET2 成员名称，并介绍了如何表示服务属性数据。当命名空间提供程序未使用时，标记为可选且依赖于 NSPv2 提供程序要求的成员可以作为 NULL 指针提供。

WSAQUERYSET2成员名称	服务属性说明
dwSize	将设置为 (WSAQUERYSET2) 的大小。这是一种版本控制机制。
lpszServiceInstanceName	包含服务实例名称的字符串。
lpVersion	服务实例版本号。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
lpszComment	注释字符串。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
dwNameSpace	命名空间标识符。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
lpNSProviderId	提供程序标识符。请注意，命名空间提供程序标识符也在 lpProviderId 参数中传递。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
lpszContext	分层命名空间中查询的起点。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
dwNumberOfProtocols	协议约束数组中条目数的大小（以字节为单位）。此成员可以为零。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
lpafpProtocols	AFPROTOCOLS 结构的数组。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
lpszQueryString	某些 (命名空间（如 whois++) ）支持包含在简单文本字符串中的类似 SQL 的丰富查询。此参数用于指定该字符串。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
dwNumberOfCsAddrs	lpcsaBuffer 引用的CSADDR_INFO结构数组中的元素数。
lpcsaBuffer	指向 CSADDR_INFO 结构的数组的指针，这些结构包含服务正在侦听的一个或多个地址。
dwOutputFlags	此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
lpBlob	指向提供程序特定的实体的指针。 NS_EMAIL命名空间需要此成员。此成员是可选的，具体取决于其他 NSPv2 服务提供商的要求。

**注意** CSADDR_INFO 结构的 **iProtocol** 成员可以包含清单常量 **IPROTOCOL_ANY**，指示通配符值。命名空间提供程序应将可接受的值替换为给定的地址系列和套接字类型。

要求

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