SetAddrInfoExA 函数（ws2tcpip.h）

项目
11/20/2024

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将导致向所有已安装和活动的命名空间提供程序注册信息。

dwNameSpace 参数的选项列在 Winsock2.h include 文件中。 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 应用]
目标平台	窗户
标头	ws2tcpip.h
库	Ws2_32.lib
DLL	Ws2_32.dll