SIO_ADDRESS_LIST_QUERY控制代码

项目
06/13/2023

说明

SIO_ADDRESS_LIST_QUERY控制代码获取应用程序可以绑定到的套接字协议系列的本地传输地址列表。地址列表因地址系列而异，某些地址从列表中排除。

若要执行此操作，请使用以下参数调用 WSAIoctl 或 WSPIoctl 函数。

int WSAIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

parameters

S

标识套接字的描述符。

dwIoControlCode

操作的控制代码。对此操作使用 SIO_ADDRESS_LIST_QUERY 。

lpvInBuffer

指向输入缓冲区的指针。此参数未用于此操作。

cbInBuffer

输入缓冲区的大小（以字节为单位）。此参数未用于此操作。

lpvOutBuffer

指向输出缓冲区的指针。

cbOutBuffer

输出缓冲区的大小（以字节为单位）。

lhttpBytesReturned

指向变量的指针，该变量接收输出缓冲区中存储的数据的大小（以字节为单位）。

lpvOverlapped

指向 WSAOVERLAPPED 结构的指针。

如果 创建的套接字 没有重叠属性，则忽略 lpOverlapped 参数。

如果使用重叠属性打开了，并且 lpOverlapped 参数不为 NULL，则该操作将作为重叠 (异步) 操作执行。在这种情况下， lpOverlapped 参数必须指向有效的 WSAOVERLAPPED 结构。

对于重叠操作， WSAIoctl 或 WSPIoctl 函数将立即返回，并在操作完成时发出相应的完成方法信号。否则，在操作完成或发生错误之前，函数不会返回。

lpCompletionRoutine

类型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

指向完成操作时调用的完成例程的指针， (忽略非重叠套接字) 。

lpThreadId

指向 WSATHREADID 结构的指针，供提供程序在后续调用 WPUQueueApc 时使用。在 WPUQueueApc 函数返回之前，提供程序应存储引用的 WSATHREADID 结构 (而不是指向同一) 的指针。

注意此参数仅适用于 WSPIoctl 函数。

lpErrno

指向错误代码的指针。

注意此参数仅适用于 WSPIoctl 函数。

返回值

如果操作成功完成， WSAIoctl 或 WSPIoctl 函数将返回零。

如果操作失败或挂起， WSAIoctl 或 WSPIoctl 函数将返回 SOCKET_ERROR。若要获取扩展的错误信息，请调用 WSAGetLastError。

错误代码	含义
WSA_IO_PENDING	已成功启动重叠操作，稍后将指示完成。
WSA_OPERATION_ABORTED	由于套接字关闭或执行了 SIO_FLUSH IOCTL 命令，已取消重叠的操作。
WSAEFAULT	lpOverlapped 或 lpCompletionRoutine 参数并不完全包含在用户地址空间的有效部分。
WSAEINPROGRESS	当回调正在进行时，将调用函数。
WSAEINTR	阻止操作中断。
WSAEINVAL	dwIoControlCode 参数不是有效的命令，或者指定的输入参数不可接受，或者该命令不适用于指定的套接字类型。如果未将 cbInBuffer 参数设置为 NULL，则返回此错误。
WSAENETDOWN	网络子系统失败。
WSAENOBUFS	没有可用的缓冲区空间。
WSAENOPROTOOPT	指定协议不支持套接字选项。
WSAENOTSOCK	描述符不是套接字。
WSAEOPNOTSUPP	不支持指定的 IOCTL 命令。如果传输提供程序不支持 SIO_ADDRESS_LIST_QUERY IOCTL，则返回此错误。

备注

SIO_ADDRESS_LIST_QUERY IOCTL 在 Windows 2000 及更高版本的操作系统上受支持。

SIO_ADDRESS_LIST_QUERY控制代码获取应用程序可以绑定到的套接字协议系列的本地传输地址列表。地址列表因地址系列而异。

对于AF_INET6地址系列，除以下地址外，将返回所有地址：

重复地址检测 (DAD) 状态不是 IpDadStateP 引用的任何 IP 地址。
在接口类型为 IF_TYPE_SOFTWARE_LOOPBACK的接口上，作用域级别低于 ScopeLevelSubnet 的任何 IP 地址。这意味着将排除链接本地 (fe80：*) 和环回 (：：1 IF_TYPE_SOFTWARE_LOOPBACK 类型接口上的 ) 地址，但如果这些地址位于具有不同类型的接口上，则不会这样做。

对于 AF_INET 地址系列，除以下地址外，将返回所有地址：

重复地址检测 (DAD) 状态不是 IpDadStateP 引用的任何 IP 地址。
接口上的任何 IP 地址，其中接口类型 为IF_TYPE_SOFTWARE_LOOPBACK 且链接为本地。这意味着链接本地 (169.254。) 和环回 (127。 IF_TYPE_SOFTWARE_LOOPBACK 类型的接口上的 ) 地址将被排除，但如果这些地址位于具有不同类型的接口上，则不会。

有关 DAD 状态的详细信息，请参阅有关 IP_DAD_STATE 枚举和 IP_ADAPTER_UNICAST_ADDRESS 结构的 IP 帮助程序文档和有关 MIB_UNICASTIPADDRESS_ROW 结构的 MIB 文档。有关接口类型的详细信息，请参阅有关 IP_ADAPTER_ADDRESSES 结构和 GetAdaptersAddresses 函数的 IP 帮助程序文档以及有关 MIB_IF_ROW2 结构的 MIB 文档。有关范围级别的详细信息，请参阅有关 IP_ADAPTER_ADDRESSES 结构和 SCOPE_LEVEL 枚举的 IP 帮助程序文档。

lpvOutBuffer 参数指向的输出缓冲区中返回的列表采用SOCKET_ADDRESS_LIST结构的形式。

如果 lpvOutBuffer 参数中指定的输出缓冲区不够大，无法包含地址列表， SOCKET_ERROR 将作为此 IOCTL 的结果返回， WSAGetLastError 返回 WSAEFAULT。在本例中，输出缓冲区的所需大小（以字节为单位）在 lhttpBytesReturned 参数中返回。请注意，如果 lpvInBuffer、lpvOutBuffer 或 l的身份参数未完全包含在用户地址空间的有效部分中，也会返回 WSAEFAULT 错误代码。

SIO_ADDRESS_LIST_QUERY IOCTL 通常以同步方式调用，lpvOverlapped 参数设置为 NULL，因为地址列表会立即返回。

注意在 Windows 即插即用环境中，可以动态添加和删除地址。因此，应用程序不能依赖于 SIO_ADDRESS_LIST_QUERY 持久返回的信息。应用程序可以通过 SIO_ADDRESS_LIST_CHANGE IOCTL 注册地址更改通知，该 IOCTL 通过重叠 I/O 或 FD_ADDRESS_LIST_CHANGE 事件提供通知。以下操作序列可用于保证应用程序始终具有当前地址列表信息：

发出 SIO_ADDRESS_LIST_CHANGE IOCTL
发出 SIO_ADDRESS_LIST_QUERY IOCTL
每当 SIO_ADDRESS_LIST_CHANGE IOCTL 调用通过重叠 I/O 或通过) FD_ADDRESS_LIST_CHANGE事件发出 信号来通知应用程序地址列表更改 (时，应重复整个操作序列。

在为 Windows Vista 及更高版本发布的 Microsoft Windows 软件开发工具包 (SDK) 上，头文件的组织已更改， SIO_ADDRESS_LIST_QUERY 控制代码在 Ws2def.h 头文件中定义。请注意， Ws2def.h 头文件会自动包含在 Winsock2.h 中，永远不应直接使用。