SIO_ADDRESS_LIST_QUERY Control Code

Article
01/07/2021

Description

The SIO_ADDRESS_LIST_QUERY control code obtains a list of local transport addresses of the socket's protocol family to which the application can bind. The list of addresses varies based on address family and some addresses are excluded from the list.

To perform this operation, call the WSAIoctl or WSPIoctl function with the following parameters.

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

A descriptor identifying a socket.

dwIoControlCode

The control code for the operation. Use SIO_ADDRESS_LIST_QUERY for this operation.

lpvInBuffer

A pointer to the input buffer. This parameter is unused for this operation.

cbInBuffer

The size, in bytes, of the input buffer. This parameter is unused for this operation.

lpvOutBuffer

A pointer to the output buffer.

cbOutBuffer

The size, in bytes, of the output buffer.

lpcbBytesReturned

A pointer to a variable that receives the size, in bytes, of the data stored in the output buffer.

lpvOverlapped

A pointer to a WSAOVERLAPPED structure.

If socket s was created without the overlapped attribute, the lpOverlapped parameter is ignored.

If s was opened with the overlapped attribute and the lpOverlapped parameter is not NULL, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped parameter must point to a valid WSAOVERLAPPED structure.

For overlapped operations, the WSAIoctl or WSPIoctl function returns immediately, and the appropriate completion method is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.

lpCompletionRoutine

Type: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

A pointer to the completion routine called when the operation has been completed (ignored for non-overlapped sockets).

lpThreadId

A pointer to a WSATHREADID structure to be used by the provider in a subsequent call to WPUQueueApc. The provider should store the referenced WSATHREADID structure (not the pointer to same) until after the WPUQueueApc function returns.

Note This parameter applies only to the WSPIoctl function.

lpErrno

A pointer to the error code.

Note This parameter applies only to the WSPIoctl function.

Return value

If the operation completes successfully, the WSAIoctl or WSPIoctl function returns zero.

If the operation fails or is pending, the WSAIoctl or WSPIoctl function returns SOCKET_ERROR. To get extended error information, call WSAGetLastError.

Error code	Meaning
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSA_OPERATION_ABORTED	An overlapped operation was canceled due to the closure of the socket or the execution of the SIO_FLUSH IOCTL command.
WSAEFAULT	The lpOverlapped or lpCompletionRoutine parameter is not totally contained in a valid part of the user address space.
WSAEINPROGRESS	The function is invoked when a callback is in progress.
WSAEINTR	A blocking operation was interrupted.
WSAEINVAL	The dwIoControlCode parameter is not a valid command, or a specified input parameter is not acceptable, or the command is not applicable to the type of socket specified. This error is returned if the cbInBuffer parameter is not set to NULL.
WSAENETDOWN	The network subsystem has failed.
WSAENOBUFS	No buffer space available.
WSAENOPROTOOPT	The socket option is not supported on the specified protocol.
WSAENOTSOCK	The descriptor s is not a socket.
WSAEOPNOTSUPP	The specified IOCTL command is not supported. This error is returned if the SIO_ADDRESS_LIST_QUERY IOCTL is not supported by the transport provider.

Remarks

The SIO_ADDRESS_LIST_QUERY IOCTL is supported on Windows 2000 and later versions of the operating system.

For the AF_INET6 address family, all addresses are returned except for the following:

Any IP address where the duplicate address detection (DAD) state is not IpDadStatePreferred.
Any IP address with a scope level lower than ScopeLevelSubnet on an interface where the interface type is IF_TYPE_SOFTWARE_LOOPBACK. This means link-local (fe80:*) and loopback (::1) addresses on interfaces of IF_TYPE_SOFTWARE_LOOPBACK type are excluded, but not if these addresses are on an interface with a different type.

For the AF_INET address family, all addresses are returned except for the following:

Any IP address where the duplicate address detection (DAD) state is not IpDadStatePreferred.
Any IP address on an interface where the interface type is IF_TYPE_SOFTWARE_LOOPBACK and link is local. This means link-local (169.254.) and loopback (127.) addresses on interfaces of IF_TYPE_SOFTWARE_LOOPBACK type are excluded, but not if these addresses are on an interface with a different type.

For more information on DAD state, see the IP Helper documentation on the IP_DAD_STATE enumeration and IP_ADAPTER_UNICAST_ADDRESS structure and the MIB documentation on the MIB_UNICASTIPADDRESS_ROW structure. For more information on interface type, see the IP Helper documentation on the IP_ADAPTER_ADDRESSES structure and the GetAdaptersAddresses function and the MIB documentation on MIB_IF_ROW2 structure. For more information on the scope level, see the IP Helper documentation on the IP_ADAPTER_ADDRESSES structure and the SCOPE_LEVEL enumeration.

The list returned in the output buffer pointed to by the lpvOutBuffer parameter is in the form of a SOCKET_ADDRESS_LIST structure.

If the output buffer specified in the lpvOutBuffer parameter is not large enough to contain the address list, SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT. The required size, in bytes, for the output buffer is returned in the lpcbBytesReturned parameter in this case. Note the WSAEFAULT error code is also returned if the lpvInBuffer, lpvOutBuffer, or lpcbBytesReturned parameter is not completely contained in a valid part of the user address space.

The SIO_ADDRESS_LIST_QUERY IOCTL is normally called synchronously with the lpvOverlapped parameter set to NULL, since the list of addresses is returned immediately.

Note In Windows Plug-n-Play environments, addresses can be added and removed dynamically. Therefore, applications cannot rely on the information returned by SIO_ADDRESS_LIST_QUERY to be persistent. Applications may register for address change notifications through the SIO_ADDRESS_LIST_CHANGE IOCTL which provides for notification through either overlapped I/O or FD_ADDRESS_LIST_CHANGE event. The following sequence of actions can be used to guarantee that the application always has current address list information:

Issue the SIO_ADDRESS_LIST_CHANGE IOCTL
Issue the SIO_ADDRESS_LIST_QUERY IOCTL
Whenever the SIO_ADDRESS_LIST_CHANGE IOCTL call notifies the application of an address list change (either through overlapped I/O or by signaling FD_ADDRESS_LIST_CHANGE event), the whole sequence of actions should be repeated.

On the Microsoft Windows Software Development Kit (SDK) released for Windows Vista and later, the organization of header files has changed and the SIO_ADDRESS_LIST_QUERY control code is defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.