código de control de SIO_ADDRESS_LIST_QUERY

Artículo
06/12/2023

Descripción

El código de control SIO_ADDRESS_LIST_QUERY obtiene una lista de direcciones de transporte locales de la familia de protocolos del socket al que se puede enlazar la aplicación. La lista de direcciones varía en función de la familia de direcciones y algunas direcciones se excluyen de la lista.

Para realizar esta operación, llame a la función WSAIoctl o WSPIoctl con los parámetros siguientes.

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.
);

Parámetros

s

Descriptor que identifica un socket.

dwIoControlCode

Código de control para la operación. Use SIO_ADDRESS_LIST_QUERY para esta operación.

lpvInBuffer

Puntero al búfer de entrada. Este parámetro no se usa para esta operación.

cbInBuffer

Tamaño, en bytes, del búfer de entrada. Este parámetro no se usa para esta operación.

lpvOutBuffer

Puntero al búfer de salida.

cbOutBuffer

Tamaño, en bytes, del búfer de salida.

lpcbBytesReturned

Puntero a una variable que recibe el tamaño, en bytes, de los datos almacenados en el búfer de salida.

lpvOverlapped

Puntero a una estructura WSAOVERLAPPED .

Si el socket se creó sin el atributo superpuesto, se omite el parámetro lpOverlapped .

Si se abrió con el atributo superpuesto y el parámetro lpOverlapped no es NULL, la operación se realiza como una operación superpuesta (asincrónica). En este caso, el parámetro lpOverlapped debe apuntar a una estructura WSAOVERLAPPED válida.

En el caso de las operaciones superpuestas, la función WSAIoctl o WSPIoctl devuelve inmediatamente y el método de finalización adecuado se señala cuando se ha completado la operación. De lo contrario, la función no devuelve hasta que se haya completado la operación o se produzca un error.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntero a la rutina de finalización a la que se llama cuando se ha completado la operación (se omite para sockets no superpuestos).

lpThreadId

Puntero a una estructura WSATHREADID que va a usar el proveedor en una llamada posterior a WPUQueueApc. El proveedor debe almacenar la estructura WSATHREADID a la que se hace referencia (no el puntero a la misma) hasta que se devuelva la función WPUQueueApc .

Nota Este parámetro solo se aplica a la función WSPIoctl .

lpErrno

Puntero al código de error.

Nota Este parámetro solo se aplica a la función WSPIoctl .

Valor devuelto

Si la operación se completa correctamente, la función WSAIoctl o WSPIoctl devuelve cero.

Si se produce un error en la operación o está pendiente, la función WSAIoctl o WSPIoctl devuelve SOCKET_ERROR. Para obtener información de error extendida, llame a WSAGetLastError.

Código de error	Significado
WSA_IO_PENDING	Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior.
WSA_OPERATION_ABORTED	Se canceló una operación superpuesta debido al cierre del socket o a la ejecución del comando SIO_FLUSH IOCTL.
WSAEFAULT	El parámetro lpOverlapped o lpCompletionRoutine no está totalmente incluido en una parte válida del espacio de direcciones del usuario.
WSAEINPROGRESS	La función se invoca cuando hay una devolución de llamada en curso.
WSAEINTR	Se interrumpió una operación de bloqueo.
WSAEINVAL	El parámetro dwIoControlCode no es un comando válido o un parámetro de entrada especificado no es aceptable o el comando no es aplicable al tipo de socket especificado. Este error se devuelve si el parámetro cbInBuffer no está establecido en NULL.
WSAENETDOWN	Error en el subsistema de red.
WSAENOBUFS	No hay espacio de búfer disponible.
WSAENOPROTOOPT	La opción de socket no se admite en el protocolo especificado.
WSAENOTSOCK	El descriptor s no es un socket.
WSAEOPNOTSUPP	No se admite el comando IOCTL especificado. Este error se devuelve si el proveedor de transporte no admite el SIO_ADDRESS_LIST_QUERY IOCTL.

Comentarios

El SIO_ADDRESS_LIST_QUERY IOCTL es compatible con Windows 2000 y versiones posteriores del sistema operativo.

Para la familia de direcciones de AF_INET6, se devuelven todas las direcciones excepto las siguientes:

Cualquier dirección IP en la que el estado de detección de direcciones duplicadas (DAD) no sea IpDadStatePreferred.
Cualquier dirección IP con un nivel de ámbito inferior a ScopeLevelSubnet en una interfaz donde se IF_TYPE_SOFTWARE_LOOPBACK el tipo de interfaz. Esto significa que las direcciones locales de vínculo (fe80:*) y bucle invertido (::1) en interfaces de IF_TYPE_SOFTWARE_LOOPBACK tipo se excluyen, pero no si estas direcciones están en una interfaz con un tipo diferente.

Para la familia de direcciones de AF_INET , se devuelven todas las direcciones excepto las siguientes:

Cualquier dirección IP en la que el estado de detección de direcciones duplicadas (DAD) no sea IpDadStatePreferred.
Cualquier dirección IP de una interfaz en la que el tipo de interfaz es IF_TYPE_SOFTWARE_LOOPBACK y el vínculo es local. Esto significa que se excluyen las direcciones locales de vínculo (169.254) y bucle invertido (127).) en interfaces de IF_TYPE_SOFTWARE_LOOPBACK tipo, pero no si estas direcciones están en una interfaz con un tipo diferente.

Para obtener más información sobre el estado DAD, consulte la documentación del asistente de IP sobre la enumeración IP_DAD_STATE y la estructura de IP_ADAPTER_UNICAST_ADDRESS y la documentación de MIB sobre la estructura de MIB_UNICASTIPADDRESS_ROW . Para obtener más información sobre el tipo de interfaz, consulte la documentación del asistente de IP sobre la estructura de IP_ADAPTER_ADDRESSES y la función GetAdaptersAddresses y la documentación de MIB sobre MIB_IF_ROW2 estructura. Para obtener más información sobre el nivel de ámbito, consulte la documentación del asistente de IP sobre la estructura de IP_ADAPTER_ADDRESSES y la enumeración SCOPE_LEVEL .

La lista devuelta en el búfer de salida al que apunta el parámetro lpvOutBuffer tiene la forma de una estructura SOCKET_ADDRESS_LIST .

Si el búfer de salida especificado en el parámetro lpvOutBuffer no es lo suficientemente grande como para contener la lista de direcciones, SOCKET_ERROR se devuelve como resultado de este IOCTL y WSAGetLastError devuelve WSAEFAULT. El tamaño necesario, en bytes, para el búfer de salida se devuelve en el parámetro lpcbBytesReturned en este caso. Tenga en cuenta que el código de error WSAEFAULT también se devuelve si el parámetro lpvInBuffer, lpvOutBuffer o lpcbBytesReturned no está completamente incluido en una parte válida del espacio de direcciones del usuario.

Normalmente, el SIO_ADDRESS_LIST_QUERY IOCTL se denomina sincrónicamente con el parámetro lpvOverlapped establecido en NULL, ya que la lista de direcciones se devuelve inmediatamente.

Nota En entornos de Windows Plug-n-Play, las direcciones se pueden agregar y quitar dinámicamente. Por lo tanto, las aplicaciones no pueden confiar en la información devuelta por SIO_ADDRESS_LIST_QUERY que sean persistentes. Las aplicaciones pueden registrarse para las notificaciones de cambio de dirección a través del SIO_ADDRESS_LIST_CHANGE IOCTL, que proporciona notificaciones a través de E/S superpuesta o FD_ADDRESS_LIST_CHANGE evento. La siguiente secuencia de acciones se puede usar para garantizar que la aplicación siempre tenga información de la lista de direcciones actual:

Emisión del SIO_ADDRESS_LIST_CHANGE IOCTL
Emisión del IOCTL de SIO_ADDRESS_LIST_QUERY
Cada vez que la llamada SIO_ADDRESS_LIST_CHANGE IOCTL notifica a la aplicación de un cambio de lista de direcciones (ya sea a través de E/S superpuesta o mediante la señalización FD_ADDRESS_LIST_CHANGE evento), se debe repetir toda la secuencia de acciones.

En el Kit de desarrollo de software (SDK) de Microsoft Windows publicado para Windows Vista y versiones posteriores, la organización de los archivos de encabezado ha cambiado y el código de control de SIO_ADDRESS_LIST_QUERY se define en el archivo de encabezado Ws2def.h . Tenga en cuenta que el archivo de encabezado Ws2def.h se incluye automáticamente en Winsock2.h y nunca se debe usar directamente.