Код элемента управления SIO_ADDRESS_LIST_QUERY

Статья
06/12/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.
);

Параметры

s

Дескриптор, определяющий сокет.

dwIoControlCode

Код элемента управления для операции. Используйте SIO_ADDRESS_LIST_QUERY для этой операции.

lpvInBuffer

Указатель на входной буфер. Этот параметр не используется для данной операции.

cbInBuffer

Размер входного буфера в байтах. Этот параметр не используется для данной операции.

lpvOutBuffer

Указатель на выходной буфер.

cbOutBuffer

Размер выходного буфера в байтах.

lpcbBytesReturned

Указатель на переменную, которая получает размер в байтах данных, хранящихся в выходном буфере.

lpvOverlapped

Указатель на структуру WSAOVERLAPPED .

Если сокеты были созданы без перекрываемого атрибута, параметр lpOverlapped игнорируется.

Если объект был открыт с перекрывающимся атрибутом, а параметр lpOverlapped не равен NULL, операция выполняется как перекрываемая (асинхронная) операция. В этом случае параметр lpOverlapped должен указывать на допустимую структуру WSAOVERLAPPED .

Для перекрывающихся операций функция WSAIoctl или WSPIoctl возвращается немедленно, а соответствующий метод завершения получает сигнал о завершении операции. В противном случае функция не возвращается, пока операция не будет завершена или не возникнет ошибка.

lpCompletionRoutine

Тип: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Указатель на подпрограмму завершения, вызываемую при завершении операции (игнорируется для неперекрывающихся сокетов).

lpThreadId

Указатель на структуру WSATHREADID , которая будет использоваться поставщиком в последующем вызове WPUQueueApc. Поставщик должен хранить указанную структуру WSATHREADID (не указатель на нее), пока не будет возвращена функция WPUQueueApc .

Примечание Этот параметр применяется только к функции WSPIoctl .

lpErrno

Указатель на код ошибки.

Примечание Этот параметр применяется только к функции WSPIoctl .

Возвращаемое значение

Если операция завершается успешно, функция WSAIoctl или WSPIoctl возвращает ноль.

Если операция завершается сбоем или находится в состоянии ожидания, функция WSAIoctl или WSPIoctl возвращает SOCKET_ERROR. Чтобы получить расширенные сведения об ошибке, вызовите WSAGetLastError.

Код ошибки	Значение
WSA_IO_PENDING	Перекрываемая операция была успешно инициирована, и ее завершение будет указано позже.
WSA_OPERATION_ABORTED	Перекрываемая операция была отменена из-за закрытия сокета или выполнения команды IOCTL SIO_FLUSH .
WSAEFAULT	Параметр lpOverlapped или lpCompletionRoutine не полностью содержится в допустимой части адресного пространства пользователя.
WSAEINPROGRESS	Функция вызывается при выполнении обратного вызова.
WSAEINTR	Блокирующая операция была прервана.
WSAEINVAL	Параметр dwIoControlCode не является допустимой командой, или указанный входной параметр недопустим, либо команда не применима к указанному типу сокета. Эта ошибка возвращается, если для параметра cbInBuffer не задано значение NULL.
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOBUFS	Свободное буферное пространство отсутствует.
WSAENOPROTOOPT	Параметр сокета не поддерживается в указанном протоколе.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Указанная команда IOCTL не поддерживается. Эта ошибка возвращается, если поставщик транспорта не поддерживает SIO_ADDRESS_LIST_QUERY IOCTL.

Любой IP-адрес, где состояние обнаружения повторяющихся адресов (DAD) не ipDadStatePreferred.
Любой IP-адрес с уровнем область ниже ScopeLevelSubnet в интерфейсе, где тип интерфейса IF_TYPE_SOFTWARE_LOOPBACK. Это означает, что локальные адреса ссылок (fe80:*) и замыкания на себя (::1) в интерфейсах IF_TYPE_SOFTWARE_LOOPBACK типа исключаются, но не в том случае, если эти адреса находятся в интерфейсе с другим типом.

Для семейства адресов AF_INET возвращаются все адреса, за исключением следующих:

Любой IP-адрес, где состояние обнаружения повторяющихся адресов (DAD) не ipDadStatePreferred.
Любой IP-адрес в интерфейсе, где тип интерфейса IF_TYPE_SOFTWARE_LOOPBACK и ссылка является локальной. Это означает, что локальные (169.254.) и замыкания на себя (127.) адреса в интерфейсах IF_TYPE_SOFTWARE_LOOPBACK типа исключаются, но не в том случае, если эти адреса находятся в интерфейсе с другим типом.

Дополнительные сведения о состоянии DAD см. в документации по IP-помощнику по перечислению IP_DAD_STATE и структуре IP_ADAPTER_UNICAST_ADDRESS , а также в документации по MIB по структуре MIB_UNICASTIPADDRESS_ROW . Дополнительные сведения о типе интерфейса см. в документации по вспомогательному ip-адресу по структуре IP_ADAPTER_ADDRESSES и функции GetAdaptersAddresses и документации по MIB по структуре MIB_IF_ROW2 . Дополнительные сведения об уровне область см. в документации по вспомогательному ip-адресу по структуре IP_ADAPTER_ADDRESSES и перечислению SCOPE_LEVEL.

Список, возвращаемый в выходном буфере, на который указывает параметр lpvOutBuffer , имеет форму структуры SOCKET_ADDRESS_LIST .

Если выходной буфер, указанный в параметре lpvOutBuffer , недостаточно велик, чтобы содержать список адресов, SOCKET_ERROR возвращается в результате этого IOCTL, а WSAGetLastError возвращает WSAEFAULT. Требуемый размер в байтах для выходного буфера возвращается в параметре lpcbBytesReturned в этом случае. Обратите внимание, что код ошибки WSAEFAULT также возвращается, если параметр lpvInBuffer, lpvOutBuffer или lpcbBytesReturned не полностью содержится в допустимой части адресного пространства пользователя.

Обычно SIO_ADDRESS_LIST_QUERY IOCTL вызывается синхронно с параметром lpvOverlapped со значением NULL, так как список адресов возвращается немедленно.

Примечание В средах Windows Plug-n-Play адреса можно добавлять и удалять динамически. Поэтому приложения не могут полагаться на сведения, возвращаемые SIO_ADDRESS_LIST_QUERY , быть постоянными. Приложения могут регистрироваться для получения уведомлений об изменении адреса через SIO_ADDRESS_LIST_CHANGE IOCTL, который предоставляет уведомления через перекрывающиеся операции ввода-вывода или события FD_ADDRESS_LIST_CHANGE . Следующую последовательность действий можно использовать, чтобы гарантировать, что приложение всегда имеет текущие сведения о списке адресов:

Выдача SIO_ADDRESS_LIST_CHANGE IOCTL
Выдача SIO_ADDRESS_LIST_QUERY IOCTL
Каждый раз, когда вызов IOCTL SIO_ADDRESS_LIST_CHANGE уведомляет об изменении списка адресов (путем перекрытия операций ввода-вывода или сигнала FD_ADDRESS_LIST_CHANGE события), следует повторять всю последовательность действий.

В пакете sdk microsoft Windows, выпущенном для Windows Vista и более поздних версий, организация файлов заголовков изменилась, а код SIO_ADDRESS_LIST_QUERY управления определен в файле заголовка Ws2def.h . Обратите внимание, что файл заголовка Ws2def.h автоматически включается в Winsock2.h и никогда не должен использоваться напрямую.