SetAddrInfoExA 函数 (ws2tcpip.h)

项目
08/28/2023

SetAddrInfoEx 函数向特定命名空间提供程序注册或取消注册名称、服务名称和关联的地址。

语法

INT WSAAPI SetAddrInfoExA(
  [in]            PCSTR                              pName,
  [in]            PCSTR                              pServiceName,
  [in, out]       SOCKET_ADDRESS                     *pAddresses,
  [in]            DWORD                              dwAddressCount,
  [in, optional]  LPBLOB                             lpBlob,
  [in]            DWORD                              dwFlags,
  [in]            DWORD                              dwNameSpace,
  [in, optional]  LPGUID                             lpNspId,
  [in, optional]  timeval                            *timeout,
  [in, optional]  LPOVERLAPPED                       lpOverlapped,
  [in, optional]  LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  [out, optional] LPHANDLE                           lpNameHandle
);

参数

[in] pName

指向 以 NULL 结尾的字符串的指针，其中包含要在其中注册或取消注册地址的名称。特定于命名空间提供程序的此参数的解释。

[in] pServiceName

指向以 NULL 结尾的可选字符串的指针，该字符串包含与注册的名称关联的服务名称。此参数的解释特定于命名空间提供程序。

[in, out] pAddresses

指向要向命名空间提供程序注册的地址的可选列表的指针。

[in] dwAddressCount

pAddresses 参数中传递的地址数。如果此参数为零，则会从命名空间提供程序取消注册 pName 参数。

[in, optional] lpBlob

指向数据的可选指针，用于设置与地址列表之外的 pName 参数关联的特定于提供程序的命名空间信息。无法在 pAddresses 参数中传递的任何信息都可以在 lpBlob 参数中传递。此信息的格式特定于命名空间提供程序。

[in] dwFlags

一组标志，控制如何将 pName 和 pServiceName 参数注册到命名空间提供程序。此信息的解释特定于命名空间提供程序。

[in] dwNameSpace

一个命名空间标识符，用于确定要向哪个命名空间提供程序注册此信息。传递特定的命名空间标识符将导致仅向支持指定命名空间的命名空间提供程序注册此信息。指定NS_ALL将导致向所有已安装的和活动命名空间提供程序注册信息。

winsock2.h include 文件中列出了 dwNameSpace 参数的选项。 Windows Vista 及更高版本包含多个命名空间提供程序。可以安装其他命名空间提供程序，因此以下可能的值仅是通常可用的值。许多其他是可能的。

值	含义
NS_ALL	所有已安装的和活动命名空间。
NS_BTH	蓝牙命名空间。 Windows Vista 及更高版本支持此命名空间标识符。
NS_DNS	域名系统 (DNS) 命名空间。
NS_EMAIL	电子邮件命名空间。 Windows Vista 及更高版本支持此命名空间标识符。
NS_NLA	网络位置感知 (NLA) 命名空间。 Windows XP 及更高版本支持此命名空间标识符。
NS_PNRPNAME	特定对等名称的对等命名空间。 Windows Vista 及更高版本支持此命名空间标识符。
NS_PNRPCLOUD	对等名称集合的对等命名空间。 Windows Vista 及更高版本支持此命名空间标识符。

[in, optional] lpNspId

指向特定命名空间提供程序的可选 GUID 的指针，用于在多个命名空间提供程序在单个命名空间（如 NS_DNS）下注册此信息。为特定命名空间提供程序传递 GUID 将导致仅向指定的命名空间提供程序注册信息。可以调用 WSAEnumNameSpaceProviders 函数来检索命名空间提供程序的 GUID。

[in, optional] timeout

一个可选参数，指示在中止调用之前等待命名空间提供程序响应的时间（以毫秒为单位）。此参数当前是保留的，并且必须设置为 NULL ，因为不支持超时选项。

[in, optional] lpOverlapped

指向用于异步操作的重叠结构的可选指针。此参数当前是保留的，并且必须设置为 NULL ，因为不支持异步操作。

[in, optional] lpCompletionRoutine

指向异步操作成功完成后要调用的函数的可选指针。此参数当前是保留的，并且必须设置为 NULL ，因为不支持异步操作。

[out, optional] lpNameHandle

仅用于异步操作的可选指针。此参数当前是保留的，并且必须设置为 NULL ，因为不支持异步操作。

返回值

成功后， SetAddrInfoEx 返回NO_ERROR (0) 。失败将返回非零 Windows 套接字错误代码，如 Windows 套接字错误代码中所示。

错误代码	含义
WSANOTINITIALIZED	在使用此函数之前，必须成功调用 WSAStartup 。
WSATRY_AGAIN	名称解析暂时失败。
WSAEINVAL	提供的参数无效。如果任何保留参数不为 NULL，则返回此错误。
WSAENOBUFS	可用缓冲区空间不足。
WSANO_RECOVERY	名称解析中发生不可恢复的失败。
WSA_NOT_ENOUGH_MEMORY	内存分配失败。

注解

SetAddrInfoEx 函数提供与协议无关的方法，用于向命名空间提供程序注册或取消注册名称和一个或多个地址。 Windows Vista 和更高版本中NS_EMAIL命名空间提供程序支持地址的注册和注销。默认NS_DNS、NS_PNRPNAME和NS_PNRPNAME命名空间提供程序当前不支持名称注册。

如果调用 SetAddrInfoEx 函数时，NS_ALL设置为 dwNameSpace 参数且未指定 lpNspId 参数，则 SetAddrInfoEx 将尝试注册或取消注册所有已安装的和活动命名空间的名称和关联地址。如果任何命名空间提供程序成功注册或取消注册该名称， SetAddrInfoEx 函数将返回成功，但不会有任何指示哪个命名空间提供程序成功或哪些命名空间提供程序请求失败。

定义 UNICODE 或 _UNICODE 时， SetAddrInfoEx 将定义为 SetAddrInfoExW，即此函数的 Unicode 版本。字符串参数定义为 PWSTR 数据类型。

如果未定义 UNICODE 或 _UNICODE，SetAddrInfoEx 将定义为 SetAddrInfoExA，即此函数的 ANSI 版本。字符串参数属于 PCSTR 数据类型。

可以通过调用 GetAddrInfoEx、 getaddrinfo 或 GetAddrInfoW 函数来返回向命名空间提供程序注册的信息。 GetAddrInfoEx 函数是 getaddrinfo 和 GetAddrInfoW 函数的增强版本。

在 Windows Vista 及更高版本上，当从服务调用 SetAddrInfoEx 时，如果操作是用户进程调用该服务的结果，则服务应模拟用户。这是为了允许正确强制实施安全和路由隔离区。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持 SetAddrInfoExW 函数。

注意

ws2tcpip.h 标头将 SetAddrInfoEx 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 8.1、Windows Vista [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	ws2tcpip.h
Library	Ws2_32.lib
DLL	Ws2_32.dll