Función de devolución de llamada LPWSPIOCTL (ws2spi.h)

Artículo
08/28/2023

La función LPWSPIoctl controla el modo de un socket.

Sintaxis

LPWSPIOCTL Lpwspioctl;

int Lpwspioctl(
  [in]  SOCKET s,
  [in]  DWORD dwIoControlCode,
  [in]  LPVOID lpvInBuffer,
  [in]  DWORD cbInBuffer,
  [out] LPVOID lpvOutBuffer,
  [in]  DWORD cbOutBuffer,
  [out] LPDWORD lpcbBytesReturned,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPINT lpErrno
)
{...}

Parámetros

[in] s

Descriptor que identifica un socket.

[in] dwIoControlCode

Código de control de la operación que se va a realizar.

[in] lpvInBuffer

Puntero al búfer de entrada.

[in] cbInBuffer

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

[out] lpvOutBuffer

Puntero al búfer de salida.

[in] cbOutBuffer

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

[out] lpcbBytesReturned

Puntero al número real de bytes de salida.

[in] lpOverlapped

Puntero a una estructura WSAOverlapped (omitida para sockets no superpuestos).

[in] 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). Vea la sección Comentarios.

[in] 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) hasta que se devuelva la función WPUQueueApc .

[in] lpErrno

Puntero al código de error.

Valor devuelto

Si no se produce ningún error y la operación se ha completado inmediatamente, LPWSPIoctl devuelve cero. Tenga en cuenta que, en este caso, la rutina de finalización, si se especifica, ya se habrá puesto en cola. De lo contrario, se devuelve un valor de SOCKET_ERROR y hay disponible un código de error específico en lpErrno. El código de error WSA_IO_PENDING indica que se ha iniciado correctamente una operación superpuesta y que la finalización se indicará más adelante. Cualquier otro código de error indica que no se inició ninguna operación superpuesta y no se producirá ninguna indicación de finalización.

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.
WSAEFAULT	El parámetro lpvInBuffer, lpvOutBuffer o lpcbBytesReturned no está totalmente incluido en una parte válida del espacio de direcciones del usuario, o el parámetro cbInBuffer o cbOutBuffer es demasiado pequeño.
WSAEINVAL	DwIoControlCode no es un comando válido o un parámetro de entrada proporcionado no es aceptable o el comando no es aplicable al tipo de socket proporcionado.
WSAEINPROGRESS	La función se invoca cuando hay una devolución de llamada en curso.
WSAENETDOWN	Error en el subsistema de red.
WSAENOTSOCK	El descriptor s no es un socket.
WSAEOPNOTSUPP	No se puede realizar el comando IOCTL especificado. Por ejemplo, no se pueden satisfacer las especificaciones de flujo especificadas en SIO_SET_QOS .
WSAEWOULDBLOCK	El socket está marcado como de no bloqueo y la operación solicitada supondría un bloqueo.

Observaciones

Esta rutina se usa para establecer o recuperar parámetros operativos asociados al socket, al protocolo de transporte o al subsistema de comunicaciones. Si lpOverlapped y lpCompletionRoutine son NULL, el socket de esta función se tratará como un socket no superpuesto.

En el caso de sockets no superpuestos, se omiten los parámetros lpOverlapped y lpCompletionRoutine y esta función puede bloquearse si el socket s está en modo de bloqueo. Tenga en cuenta que si el socket s está en modo sin bloqueo, esta función puede devolver WSAEWOULDBLOCK si la operación especificada no se puede finalizar inmediatamente. En este caso, el cliente SPI de Windows Sockets puede cambiar el socket al modo de bloqueo y volver a emitir la solicitud o esperar al evento de red correspondiente (como FD_ROUTING_INTERFACE_CHANGE o FD_ADDRESS_LIST_CHANGE en caso de SIO_ROUTING_INTERFACE_CHANGE o SIO_ADDRESS_LIST_CHANGE) mediante el mensaje de Windows (a través de LPWSPAsyncSelect o evento (mediante LPWSPEventSelect).

En el caso de sockets superpuestos, las operaciones que no se pueden completar inmediatamente se iniciarán y la finalización se indicará más adelante. El valor DWORD al que apunta el parámetro lpcbBytesReturned que se devuelve puede omitirse. El estado de finalización final y los bytes devueltos se pueden recuperar cuando se señala el método de finalización adecuado cuando se ha completado la operación.

Cualquier IOCTL puede bloquearse indefinidamente, dependiendo de la implementación del proveedor de servicios. Si el cliente SPI de Windows Sockets no puede tolerar el bloqueo en una llamada LPWSPIoctl , se recomienda que las E/S superpuestas se bloqueen con mayor probabilidad de bloquear:

SIO_ADDRESS_LIST_CHANGE
SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_SET_QOS
SIO_SET_GROUP_QOS

Algunos IOCTLs específicos del protocolo también pueden ser especialmente propensos a bloquearse. Compruebe el anexo específico del protocolo pertinente para obtener información disponible.

El prototipo de la rutina de finalización a la que apunta el parámetro lpCompletionRoutine es el siguiente.

void CALLBACK 
CompletionRoutine(  
  IN DWORD           dwError, 
  IN DWORD           cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD           dwFlags 
);

CompletionRoutine es un marcador de posición para un nombre de función proporcionado por la aplicación. El parámetro dwError especifica el estado de finalización de la operación superpuesta como se indica en el parámetro lpOverlapped . El parámetro cbTransferred especifica el número de bytes recibidos. El parámetro dwFlags no se usa para este IOCTL. La rutina de finalización no devuelve un valor.

En la medida en que el parámetro dwIoControlCode es ahora una entidad de 32 bits, es posible adoptar un esquema de codificación que proporcione una manera cómoda de particionar el espacio de identificadores de código de operación. El parámetro dwIoControlCode se construye para permitir la independencia del protocolo y del proveedor al agregar nuevos códigos de control, a la vez que se conserva la compatibilidad con versiones anteriores con los códigos de control de Windows Sockets 1.1 y UNIX. El parámetro dwIoControlCode tiene el siguiente formato.

bit 31	bit 30	bit 29	bits 28 y 27	bits 26 a 16	bits 15 a 0
I	O	V	T	Familia de proveedores y direcciones	Código

Se establece si el búfer de entrada es válido para el código, como con IOC_IN.

O se establece si el búfer de salida es válido para el código, como con IOC_OUT. Tenga en cuenta que para los códigos con parámetros de entrada y salida, se establecerá la E y la E .

V se establece si no hay parámetros para el código, como con IOC_VOID.

T es una cantidad de dos bits que define el tipo de IOCTL. Se definen los valores siguientes.

0 indica que el IOCTL es un código IOCTL de UNIX estándar, como con FIONREAD, FIONBIO, etc.
1 indica que el IOCTL es un código IOCTL genérico de Windows Sockets 2. Los nuevos códigos IOCTL definidos para Windows Sockets 2 tendrán T == 1.
2 indica que el IOCTL solo se aplica a una familia de direcciones específica.
3 El IOCTL se aplica solo al proveedor de un proveedor específico. Este tipo permite que a las empresas se les asigne un número de proveedor que aparezca en el miembro de la familia Vendor/Address . A continuación, el proveedor puede definir nuevas ICTLs específicas de ese proveedor sin tener que registrar el IOCTL con un centro de compensación, lo que proporciona flexibilidad y privacidad del proveedor.

La familia proveedor/dirección es una cantidad de 11 bits que define el proveedor que posee el código (si T3) o que contiene la familia de direcciones a la que se aplica el código (si T == == 2). Si se trata de un código IOCTL de UNIX (T == 0), este miembro tiene el mismo valor que el código en UNIX. Si se trata de un IOCTL genérico de Windows Sockets 2 (T == 1), este miembro se puede usar como extensión del miembro de código para proporcionar valores de código adicionales.

El código es el código IOCTL específico para la operación.

Se admiten los siguientes comandos unix:

FIONBIO

Habilita o deshabilita el modo de no bloqueo en los sockets. El parámetro lpvInBuffer apunta a un long sin signo, que es distinto de cero si se va a habilitar el modo de desbloqueo y cero si se va a deshabilitar. Cuando se crea un socket, funciona en modo de bloqueo (es decir, el modo de no bloqueo está deshabilitado). Esto es coherente con los sockets de distribución de software de Berkeley (BSD).

La rutina LPWSPAsyncSelect o LPWSPEventSelect establece automáticamente un socket en modo sin bloqueo. Si LPWSPAsyncSelect o LPWSPEventSelect se ha emitido en un socket, cualquier intento de usar LPWSPIoctl para establecer el socket en modo de bloqueo producirá un error con WSAEINVAL. Para volver al modo de bloqueo del socket, un cliente SPI de Windows Sockets primero debe deshabilitar LPWSPAsyncSelect llamando a LPWSPAsyncSelect con el parámetro lEvent igual a cero o deshabilitar LPWSPEventSelect llamando a LPWSPEventSelect con el parámetro lNetworkEvents igual a cero.

FIONREAD

Determine la cantidad de datos que se pueden leer de forma atómica desde los sockets. El parámetro lpvOutBuffer apunta a un long sin signo en el que WSAIoctl almacena el resultado.

Si el socket pasado en el parámetro s está orientado a secuencias (por ejemplo, tipo SOCK_STREAM), FIONREAD devuelve la cantidad total de datos que se pueden leer en una sola operación de recepción; normalmente es igual que la cantidad total de datos en cola en el socket (ya que un flujo de datos está orientado a bytes, esto no está garantizado).

Si el socket pasado en el parámetro s está orientado a mensajes (por ejemplo, tipo SOCK_DGRAM), FIONREAD devuelve el número total de bytes disponibles para leer, no el tamaño del primer datagrama (mensaje) en cola en el socket.

SIOCATMARK

Determina si se han leído o no todos los datos de OOB. Esto solo se aplica a un socket de estilo de flujo (por ejemplo, tipo SOCK_STREAM) que se ha configurado para la recepción insertada de cualquier dato OOB (SO_OOBINLINE). Si no hay datos de OOB a la espera de leerse, la operación devuelve TRUE. De lo contrario, devuelve FALSE y la siguiente operación de recepción realizada en el socket recuperará algunos o todos los datos anteriores a la marca; El cliente SPI de Windows Sockets debe usar la operación SIOCATMARK para determinar si queda alguno. Si hay datos normales anteriores a los datos urgentes (OOB), se recibirán en orden. (Tenga en cuenta que las operaciones de recepción nunca combinarán OOB y los datos normales en la misma llamada). lpvOutBuffer apunta a un BOOL en el que LPWSPIoctl almacena el resultado.

Se admiten los siguientes comandos de Windows Sockets 2:

SIO_ACQUIRE_PORT_RESERVATION (configuración de opcode: I, T==3)

Solicite una reserva en tiempo de ejecución para un bloque de puertos TCP o UDP. Para las reservas de puertos en tiempo de ejecución, el grupo de puertos requiere que las reservas se consuman desde el proceso en cuyo socket se concedió la reserva. Las reservas de puertos en tiempo de ejecución solo duran mientras dure el socket en el que se llamó al SIO_ACQUIRE_PORT_RESERVATION IOCTL. En cambio, las reservas de puertos persistentes creadas mediante la función CreatePersistentTcpPortReservation o CreatePersistentUdpPortReservation pueden consumirse por cualquier proceso con la capacidad de obtener reservas persistentes.

Para obtener información más detallada, consulte la referencia de SIO_ACQUIRE_PORT_RESERVATION .

SIO_ACQUIRE_PORT_RESERVATION se admite en Windows Vista y versiones posteriores del sistema operativo.

SIO_ADDRESS_LIST_CHANGE (configuración de opcode: T==1)

Para recibir notificaciones de cambios en la lista de direcciones de transporte locales de la familia de protocolos del socket al que puede enlazar el cliente SPI de Windows Sockets. No se proporcionará información de salida tras la finalización de este IOCTL; la finalización simplemente indica que la lista de direcciones locales disponibles ha cambiado y se debe consultar de nuevo a través de SIO_ADDRESS_LIST_QUERY.

Se supone (aunque no es necesario) que el cliente SPI de Windows Sockets usa E/S superpuesta para recibir notificaciones de cambio al completar SIO_ADDRESS_LIST_CHANGE solicitud. Como alternativa, si el SIO_ADDRESS_LIST_CHANGE IOCTL se emite en un socket sin bloqueo y sin parámetros superpuestos (lpOverlapped y lpCompletionRoutine se establecen en NULL), se completará inmediatamente con el error WSAEWOULDBLOCK. Después, el cliente SPI de Windows Sockets puede esperar eventos de cambio de lista de direcciones a través de una llamada a LPWSPEventSelect o LPWSPAsyncSelect con el bit de FD_ADDRESS_LIST_CHANGE establecido en la máscara de bits del evento de red.

SIO_ADDRESS_LIST_QUERY (configuración de opcode: O, T==1)

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.

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 superpuestas 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:

Problema SIO_ADDRESS_LIST_CHANGE IOCTL
Problema SIO_ADDRESS_LIST_QUERY IOCTL
Siempre que SIO_ADDRESS_LIST_CHANGE IOCTL notifica al cambio de la 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.

Para obtener información más detallada, consulte la referencia de SIO_ADDRESS_LIST_QUERY . SIO_ADDRESS_LIST_QUERY se admite en Windows 2000 y versiones posteriores.

SIO_ASSOCIATE_HANDLE (configuración de código de operación: I, T==1)

Asocia este socket con el identificador especificado de una interfaz complementaria. El búfer de entrada contiene el valor entero correspondiente a la constante de manifiesto de la interfaz complementaria (por ejemplo, TH_NETDEV y TH_TAPI), seguido de un valor que es un identificador de la interfaz complementaria especificada, junto con cualquier otra información necesaria. Consulte la sección correspondiente en el anexo de Windows Sockets 2 Protocol-Specific o la documentación de la interfaz complementaria concreta para obtener más detalles. (Estos recursos solo pueden estar disponibles en inglés). El tamaño total se refleja en la longitud del búfer de entrada. No se requiere ningún búfer de salida. El código de error WSAENOPROTOOPT se indica para los proveedores de servicios que no admiten este IOCTL. El identificador asociado a este IOCTL se puede recuperar mediante SIO_TRANSLATE_HANDLE.

Se puede usar una interfaz complementaria, por ejemplo, si un proveedor determinado proporciona:

Una gran cantidad de control adicional sobre el comportamiento de un socket.
Controles específicos del proveedor que no se asignan a las funciones de Windows Socket existentes (o que probablemente sean para el futuro).

Se recomienda utilizar el Modelo de objetos componentes (COM) en lugar de este comando IOCTL para detectar y realizar un seguimiento del resto de interfaces que puede admitir un socket. Este IOCTL está presente para la compatibilidad con versiones anteriores con sistemas en los que COM no está disponible o no se puede usar por alguna otra razón.

SIO_ASSOCIATE_PORT_RESERVATION (configuración de código de operación: I, T==3)

Asocie un socket a una reserva persistente o en tiempo de ejecución para un bloque de puertos TCP o UDP identificados por el token de reserva de puerto. El SIO_ASSOCIATE_PORT_RESERVATION IOCTL debe emitirse antes de que el socket esté enlazado. Si y cuando el socket está enlazado, el puerto asignado a él se seleccionará de la reserva de puertos identificada por el token especificado. Si no hay ningún puerto disponible en la reserva especificada, se producirá un error en la llamada a la función Bind .

Para obtener información más detallada, consulte la referencia de SIO_ASSOCIATE_PORT_RESERVATION .

SIO_ASSOCIATE_PORT_RESERVATION se admite en Windows Vista y versiones posteriores del sistema operativo.

SIO_BASE_HANDLE (configuración de código de operación: O, T==1)

Recupera el identificador del proveedor de servicios base para un socket determinado. El valor devuelto es un SOCKET.

Un proveedor de servicios en capas nunca debe interceptar este IOCTL, ya que el valor devuelto debe ser el identificador de socket del proveedor de servicios base.

Si el búfer de salida no es lo suficientemente grande para un identificador de socket ( cbOutBuffer es menor que el tamaño de un SOCKET) o el parámetro lpvOutBuffer es un puntero NULL , SOCKET_ERROR se devuelve como resultado de este IOCTL y WSAGetLastError devuelve WSAEFAULT.

SIO_BASE_HANDLE se define en el archivo de encabezado Mswsock.h y se admite en Windows Vista y versiones posteriores.

SIO_BSP_HANDLE (configuración de código de operación: O, T==1)

Recupera el identificador del proveedor de servicios base para un socket usado por la función WSASendMsg . El valor devuelto es un SOCKET.

Este Ioctl lo usa un proveedor de servicios en capas para garantizar que el proveedor intercepte la función WSASendMsg .

SIO_BSP_HANDLE se define en el archivo de encabezado Mswsock.h y se admite en Windows Vista y versiones posteriores.

SIO_BSP_HANDLE_SELECT (configuración de código de operación: O, T==1)

Recupera el identificador del proveedor de servicios base para un socket usado por la función select . El valor devuelto es un SOCKET.

Este Ioctl lo usa un proveedor de servicios en capas para asegurarse de que el proveedor intercepte la función select .

SIO_BSP_HANDLE_SELECT se define en el archivo de encabezado Mswsock.h y se admite en Windows Vista y versiones posteriores.

SIO_BSP_HANDLE_POLL (configuración de opcode: O, T==1)

Recupera el identificador del proveedor de servicios base para un socket utilizado por la función WSAPoll . El parámetro lpOverlapped debe ser un puntero NULL . El valor devuelto es un SOCKET.

Este Ioctl lo usa un proveedor de servicios en capas para asegurarse de que el proveedor intercepte la función WSAPoll .

Si el búfer de salida no es lo suficientemente grande para un identificador de socket ( cbOutBuffer es menor que el tamaño de un SOCKET), el parámetro lpvOutBuffer es un puntero NULL o el parámetro lpOverlapped no es un puntero NULL , SOCKET_ERROR se devuelve como resultado de este IOCTL y WSAGetLastError devuelve WSAEFAULT.

SIO_BSP_HANDLE_POLL se define en el archivo de encabezado Mswsock.h y se admite en Windows Vista y versiones posteriores.

SIO_CHK_QOS (configuración de código de operación: I, O, T==3)

Recupera información sobre las características del tráfico de QoS. Durante la fase de transición en el sistema de envío entre la configuración del flujo y la recepción de un mensaje RESV (vea How the RSVP Service Invokes TC for more information on the transitional phase), el tráfico asociado a un flujo RSVP se forma en función del tipo de servicio ( BEST EFFORT, CONTROLLED LOAD o GUARANTEED). Para obtener más información, consulte Uso de SIO_CHK_QOS en la sección Calidad de servicio del Kit de desarrollo de software de plataforma (SDK).

SIO_ENABLE_CIRCULAR_QUEUEING (configuración de código de operación: V, T==1)

Indica a un proveedor de servicios orientado a mensajes que nunca se debe quitar un mensaje recién llegado debido a un desbordamiento de cola de búfer. En su lugar, el mensaje más antiguo de la cola debe eliminarse para dar cabida al mensaje recién llegado. No se requieren búferes de entrada y salida. Tenga en cuenta que este IOCTL solo es válido para los sockets asociados a protocolos no confiables orientados a mensajes. El código de error WSAENOPROTOOPT se indica para los proveedores de servicios que no admiten este IOCTL.

SIO_FIND_ROUTE (configuración de código de operación: O, T==1)

Cuando se emite, este IOCTL solicita que se detecte la ruta a la dirección remota especificada como sockaddr en el búfer de entrada. Si la dirección ya existe en la memoria caché local, su entrada se invalida. En el caso de La IPX de Novell, esta llamada inicia un IPX GetLocalTarget (GLT), que consulta la red para la dirección remota especificada.

SIO_FLUSH (configuración de código de operación: V, T==1)

Descarta el contenido actual de la cola de envío asociada a este socket. No se requieren búferes de entrada y salida. El código de error WSAENOPROTOOPT se indica para los proveedores de servicios que no admiten este IOCTL.

SIO_GET_BROADCAST_ADDRESS (configuración de código de operación: O, T==1)

Este IOCTL rellena el búfer de salida con una estructura de sockaddr que contiene una dirección de difusión adecuada para su uso con LPWSPSendTo.

SIO_GET_EXTENSION_FUNCTION_POINTER (configuración de código de operación: O, I, T==1)

Recupere un puntero a la función de extensión especificada compatible con el proveedor de servicios asociado. El búfer de entrada contiene un identificador único global (GUID) cuyo valor identifica la función de extensión en cuestión. El puntero a la función deseada se devuelve en el búfer de salida. Los proveedores de proveedores de servicios establecen identificadores de función de extensión y deben incluirse en la documentación del proveedor que describe las funciones de extensión y la semántica.

Los valores GUID de las funciones de extensión compatibles con el proveedor de servicios TCP/IP de Windows se definen en el archivo de encabezado Mswsock.h . El valor posible para estos GUID es el siguiente:

Término	Descripción
WSAID_ACCEPTEX	Función de extensión AcceptEx .
WSAID_CONNECTEX	Función de extensión ConnectEx .
WSAID_DISCONNECTEX	Función de extensión DisconnectEx .
WSAID_GETACCEPTEXSOCKADDRS	Función de extensión GetAcceptExSockaddrs .
WSAID_TRANSMITFILE	Función de extensión TransmitFile .
WSAID_TRANSMITPACKETS	Función de extensión TransmitPackets .
WSAID_WSARECVMSG	Función de extensión LPFN_WSARECVMSG (WSARecvMsg ).
WSAID_WSASENDMSG	Función de extensión WSASendMsg .

SIO_GET_GROUP_QOS (configuración de código de operación: O, T==1)

Reservado.

SIO_GET_INTERFACE_LIST (configuración de código de operación: O, T==0)

Devuelve una lista de interfaces IP configuradas y sus parámetros como una matriz de estructuras de INTERFACE_INFO .

Nota

La compatibilidad con este comando es obligatoria para los proveedores de servicios TCP/IP compatibles con Windows Sockets 2.

El parámetro lpvOutBuffer apunta al búfer en el que se almacenará la información sobre las interfaces como una matriz de estructuras de INTERFACE_INFO para las direcciones IP de unidifusión en las interfaces. El parámetro cbOutBuffer especifica la longitud del búfer de salida. El número de interfaces devueltas (número de estructuras devueltas en el búfer a las que apunta el parámetro lpvOutBuffer ) se puede determinar en función de la longitud real del búfer de salida devuelto en el parámetro lpcbBytesReturned .

Si se llama a la función WSAIoctl con SIO_GET_INTERFACE_LIST y el miembro de nivel del parámetro socket s no se define como IPPROTO_IP, se devuelve WSAEINVAL . Una llamada a la función WSAIoctl con SIO_GET_INTERFACE_LIST devuelve WSAEFAULT si el parámetro cbOutBuffer que especifica la longitud del búfer de salida es demasiado pequeño recibir la lista de interfaces configuradas.

SIO_GET_INTERFACE_LIST_EX (configuración de código de operación: O, T==0)

Reservado para uso futuro con sockets.

Devuelve una lista de interfaces IP configuradas y sus parámetros como una matriz de estructuras de INTERFACE_INFO_EX .

El parámetro lpvOutBuffer apunta al búfer en el que almacenar la información sobre las interfaces como una matriz de estructuras de INTERFACE_INFO_EX para las direcciones IP de unidifusión en la interfaz. El parámetro cbOutBuffer especifica la longitud del búfer de salida. El número de interfaces devueltas (número de estructuras devueltas en lpvOutBuffer) se puede determinar en función de la longitud real del búfer de salida devuelto en el parámetro lpcbBytesReturned .

SIO_GET_INTERFACE_LIST_EX no se admite actualmente en Windows.

SIO_GET_QOS (configuración de código de operación: O, T==1)

Recupera la estructura QOS asociada al socket. El búfer de entrada es opcional. Algunos protocolos (por ejemplo, RSVP) permiten usar el búfer de entrada para calificar una solicitud de QOS . La estructura QOS se copiará en el búfer de salida. El búfer de salida debe tener un tamaño lo suficientemente grande como para poder contener la estructura completa de QOS . El código de error WSAENOPROTOOPT se indica para los proveedores de servicios que no admiten la calidad del servicio.

SIO_IDEAL_SEND_BACKLOG_CHANGE (configuración de código de operación: V, T==0)

Notifica a una aplicación cuando cambia el valor ideal de trabajo pendiente de envío (ISB) para la conexión subyacente.

Al enviar datos a través de una conexión TCP mediante sockets de Windows, es importante mantener una cantidad suficiente de datos pendientes (enviados pero no confirmados todavía) en TCP para lograr el mayor rendimiento. El valor ideal para la cantidad de datos pendientes para lograr el mejor rendimiento para la conexión TCP se denomina tamaño ideal de trabajo pendiente de envío (ISB). El valor ISB es una función del producto de retraso de ancho de banda de la conexión TCP y la ventana de recepción anunciada del receptor (y en parte la cantidad de congestión en la red).

El valor de ISB por conexión está disponible en la implementación del protocolo TCP en Windows Server 2008, Windows Vista con Service Pack 1 (SP1) y versiones posteriores del sistema operativo. Una aplicación puede usar el SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL para recibir notificaciones cuando el valor de ISB cambia dinámicamente para una conexión.

Para obtener información más detallada, consulte la referencia de SIO_IDEAL_SEND_BACKLOG_CHANGE .

SIO_IDEAL_SEND_BACKLOG_CHANGE se admite en Windows Server 2008, Windows Vista con SP1 y versiones posteriores del sistema operativo.

SIO_IDEAL_SEND_BACKLOG_QUERY (configuración de código de operación: O, T==0)

Recupera el valor ideal de trabajo pendiente de envío (ISB) para la conexión subyacente.

El valor de ISB por conexión está disponible en la implementación del protocolo TCP en Windows Server 2008 y versiones posteriores. Una aplicación puede usar el SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL para consultar el valor de ISB de una conexión.

Para obtener información más detallada, consulte la referencia de SIO_IDEAL_SEND_BACKLOG_QUERY .

SIO_IDEAL_SEND_BACKLOG_QUERY se admite en Windows Server 2008, Windows Vista con SP1 y versiones posteriores del sistema operativo.

SIO_KEEPALIVE_VALS (configuración de código de operación: I, T==3)

Habilita o deshabilita la configuración por conexión de la opción keep-alive de TCP que especifica el tiempo de espera y el intervalo de mantenimiento de TCP. Para obtener más información sobre la opción keep-alive, consulte la sección 4.2.3.6 en requisitos para hosts de Internet: capas de comunicación especificadas en RFC 1122 disponible en el sitio web de IETF.

SIO_KEEPALIVE_VALS se puede usar para habilitar o deshabilitar sondeos keep-alive y establecer el tiempo de espera y el intervalo de mantenimiento activo. El tiempo de espera de mantenimiento especifica el tiempo de espera, en milisegundos, sin actividad hasta que se envíe el primer paquete keep-alive. El intervalo keep-alive especifica el intervalo, en milisegundos, entre cuando se envían paquetes de mantenimiento activo sucesivos si no se recibe ninguna confirmación.

La opción SO_KEEPALIVE , que es una de las opciones de socket de SOL_SOCKET, también se puede usar para habilitar o deshabilitar el mantenimiento de TCP en una conexión, así como consultar el estado actual de esta opción. Para consultar si TCP keep-alive está habilitado en un socket, se puede llamar a la función getsockopt con la opción SO_KEEPALIVE . Para habilitar o deshabilitar tcp keep-alive, se puede llamar a la función setsockopt con la opción SO_KEEPALIVE . Si tcp keep-alive está habilitado con SO_KEEPALIVE, la configuración de TCP predeterminada se usa para el tiempo de espera y el intervalo de mantenimiento activo, a menos que estos valores se hayan cambiado mediante SIO_KEEPALIVE_VALS.

Para obtener información más detallada, consulte la referencia de SIO_KEEPALIVE_VALS . SIO_KEEPALIVE_VALS se admite en Windows 2000 y versiones posteriores.

SIO_MULTIPOINT_LOOPBACK (configuración de código de operación: I, T==1)

Controla si los datos enviados por una aplicación en el equipo local (no necesariamente por el mismo socket) en una sesión de multidifusión serán recibidos por un socket unido al grupo de destino de multidifusión en la interfaz de bucle invertido. Un valor true hace que los datos de multidifusión enviados por una aplicación en el equipo local se entreguen a un socket de escucha en la interfaz de bucle invertido. Un valor false impide que los datos de multidifusión enviados por una aplicación en el equipo local se entreguen a un socket de escucha en la interfaz de bucle invertido. De forma predeterminada, SIO_MULTIPOINT_LOOPBACK está habilitado.

SIO_MULTICAST_SCOPE (configuración de opcode: I, T==1)

Especifica el ámbito en el que se producirán las transmisiones de multidifusión. El ámbito se define como el número de segmentos de red enrutados que se van a cubrir. Un ámbito de cero indicaría que la transmisión de multidifusión no se colocaría en el cable, pero se podría difundir entre sockets dentro del host local. Un valor de ámbito de 1 (el valor predeterminado) indica que la transmisión se colocará en el cable, pero no cruzará ningún enrutador. Los valores de ámbito más altos determinan el número de enrutadores que se pueden cruzar. Tenga en cuenta que esto corresponde al parámetro de período de vida (TTL) en multidifusión IP.

SIO_QUERY_RSS_SCALABILITY_INFO (configuración de opcode: O, T==3)

Consulta las interfaces de descarga para la funcionalidad de escalado en el lado de recepción (RSS). La estructura de argumentos devuelta para SIO_QUERY_RSS_SCALABILITY_INFO se especifica en la estructura RSS_SCALABILITY_INFO definida en el archivo de encabezado Mstcpip.h . Esta estructura se define de la siguiente manera.

void CALLBACK 
CompletionRoutine(  
  IN DWORD           dwError, 
  IN DWORD           cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD           dwFlags 
);

El valor devuelto en el miembro RssEnabled indica si RSS está habilitado en al menos una interfaz.

Si el búfer de salida no es lo suficientemente grande para la estructura de RSS_SCALABILITY_INFO ( cbOutBuffer es menor que el tamaño de un RSS_SCALABILITY_INFO) o el parámetro lpvOutBuffer es un puntero NULL , SOCKET_ERROR se devuelve como resultado de este IOCTL y WSAGetLastError devuelve WSAEINVAL.

En las redes de alta velocidad en las que residen varias CPU dentro de un único sistema, la capacidad de la pila de protocolos de red para escalar bien en un sistema de varias CPU se impide porque la arquitectura de NDIS 5.1 y versiones anteriores limita el procesamiento del protocolo a una sola CPU. El escalado en el lado de recepción (RSS) resuelve este problema al permitir que la carga de red desde un adaptador de red se equilibre entre varias CPU.

SIO_QUERY_RSS_SCALABILITY_INFO se admite en Windows Vista y versiones posteriores.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE (configuración de código de operación: O, T==3)

Consulta el identificador de punto de conexión de cumplimiento de la capa de aplicación (ALE).

La Plataforma de filtrado de Windows (PMA) admite la inspección y modificación del tráfico de red. En Windows Vista, EL PMA se centra en escenarios en los que la máquina host es el punto de conexión de comunicación. Sin embargo, en Windows Server 2008 hay implementaciones de firewall perimetrales que desean aprovechar la plataforma PMA para inspeccionar y proxy el tráfico de paso a través. El servidor de seguridad y aceleración de Internet (ISA) es un ejemplo de este tipo de dispositivo perimetral.

Hay algunos escenarios de firewall que pueden requerir la capacidad de insertar un paquete entrante en la ruta de acceso de envío asociada a un punto de conexión existente. Debe haber un mecanismo para detectar el identificador de punto de conexión de la capa de transporte asociado al punto de conexión de destino. La aplicación que creó el punto de conexión posee estos puntos de conexión de capa de transporte. Este IOCTL se usa para proporcionar el identificador de socket para la asignación de identificadores de punto de conexión de capa de transporte.

Si el búfer de salida no es lo suficientemente grande como para el identificador del punto de conexión ( cbOutBuffer es menor que el tamaño de un UINT64) o el parámetro lpvOutBuffer es un puntero NULL , SOCKET_ERROR se devuelve como resultado de este IOCTL y WSAGetLastError devuelve WSAEINVAL.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE se admite en Windows Vista y versiones posteriores.

SIO_QUERY_PNP_TARGET_HANDLE (configuración de código de operación: O, T==1)

Para obtener el descriptor de socket del siguiente proveedor de la cadena en la que depende el socket actual en el sentido de PnP. El archivo DLL de Windows Sockets 2 invoca este IOCTL solo en sockets de proveedores de servicios que no son IFS creados a través de la llamada WPUCreateSocketHandle . El proveedor debe devolver en el búfer de salida el identificador de socket del siguiente proveedor de la cadena en la que depende un identificador de socket determinado en el sentido PnP (por ejemplo, la eliminación del dispositivo que admite el identificador subyacente dará como resultado la invalidación del identificador encima de él en la cadena).

Si una operación superpuesta se completa inmediatamente, esta función devuelve un valor de cero y el parámetro lpcbBytesReturned se actualiza con el número de bytes en el búfer de salida. Si la operación superpuesta se inicia correctamente y se completará más adelante, esta función devuelve SOCKET_ERROR e indica el código de error WSA_IO_PENDING. En este caso, lpcbBytesReturned no se actualiza. Cuando se completa la operación superpuesta, la cantidad de datos del búfer de salida se indica a través del parámetro cbTransferred en la rutina de finalización (si se especifica) o mediante el parámetro lpcbTransfer en LPWSPGetOverlappedResult.

SIO_RCVALL (configuración de opcode: I, T==3)

Permite que un socket reciba todos los paquetes IPv4 o IPv6 que pasan a través de una interfaz de red. El identificador de socket pasado a la función WSAIoctl debe ser uno de los siguientes:

Un socket IPv4 que se creó con la familia de direcciones establecida en AF_INET, el tipo de socket establecido en SOCK_RAW y el protocolo establecido en IPPROTO_IP.
Un socket IPv6 que se creó con la familia de direcciones establecida en AF_INET6, el tipo de socket establecido en SOCK_RAW y el protocolo establecido en IPPROTO_IPV6.

El socket también debe estar enlazado a una interfaz IPv4 o IPv6 local explícita, lo que significa que no se puede enlazar a INADDR_ANY o in6addr_any.

En Windows Server 2008 y versiones anteriores, la configuración de SIO_RCVALL IOCTL no capturaría los paquetes locales enviados fuera de una interfaz de red. Esto incluía los paquetes recibidos en otra interfaz y reenviaron la interfaz de red especificada para el SIO_RCVALL IOCTL.

En Windows 7 y Windows Server 2008 R2 , esto se cambió para que los paquetes locales enviados fuera de una interfaz de red también se capturen. Esto incluye los paquetes recibidos en otra interfaz y, a continuación, reenvía la interfaz de red enlazada al socket con SIO_RCVALL IOCTL.

Establecer este IOCTL requiere privilegios de administrador en el equipo local.

Esta característica se conoce a veces como modo promiscuo.

Los valores posibles para la opción SIO_RCVALL IOCTL se especifican en la enumeración RCVALL_VALUE definida en el archivo de encabezado Mstcpip.h . Los valores posibles para SIO_RCVALL son los siguientes:

Término	Descripción
RCVALL_OFF	Deshabilite esta opción para que un socket no reciba todos los paquetes IPv4 o IPv6 de la red.
RCVALL_ON	Habilite esta opción para que un socket reciba todos los paquetes IPv4 o IPv6 de la red. Esta opción habilita el modo promiscuo en la tarjeta de interfaz de red (NIC), si la NIC admite el modo promiscuo. En un segmento LAN con un centro de red, una NIC que admita el modo promiscuo capturará todo el tráfico IPv4 o IPv6 en la LAN, incluido el tráfico entre otros equipos del mismo segmento LAN. Todos los paquetes capturados (IPv4 o IPv6, según el socket) se entregarán al socket sin procesar. Esta opción no capturará otros paquetes (paquetes ARP, IPX y NetBEUI, por ejemplo) en la interfaz. Netmon usa el mismo modo para la interfaz de red, pero no usa esta opción para capturar el tráfico.
RCVALL_SOCKETLEVELONLY	Esta característica no está implementada actualmente, por lo que establecer esta opción no tiene ningún efecto.
RCVALL_IPLEVEL	Habilite esta opción para que un socket IPv4 o IPv6 reciba todos los paquetes en el nivel ip de la red. Esta opción no habilita el modo promiscuo en la tarjeta de interfaz de red. Esta opción solo afecta al procesamiento de paquetes en el nivel de IP. La NIC sigue recibiendo solo paquetes dirigidos a sus direcciones de unidifusión y multidifusión configuradas. Sin embargo, un socket con esta opción habilitada no solo recibirá paquetes dirigidos a direcciones IP específicas, sino que recibirá todos los paquetes IPv4 o IPv6 que recibe la NIC. Esta opción no capturará otros paquetes (paquetes ARP, IPX y NetBEUI, por ejemplo) recibidos en la interfaz.

Para obtener información más detallada, consulte la referencia de SIO_RCVALL .

SIO_RCVALL se admite en Windows 2000 y versiones posteriores.

SIO_RELEASE_PORT_RESERVATION (configuración de opcode: I, T==3)

Libera una reserva en tiempo de ejecución para un bloque de puertos TCP o UDP. La reserva en tiempo de ejecución que se va a liberar debe haberse obtenido del proceso de emisión mediante el SIO_ACQUIRE_PORT_RESERVATION IOCTL.

Para obtener información más detallada, consulte la referencia de SIO_RELEASE_PORT_RESERVATION .

SIO_RELEASE_PORT_RESERVATION se admite en Windows Vista y versiones posteriores del sistema operativo.

SIO_ROUTING_INTERFACE_CHANGE (configuración de opcode: I, T==1)

Para recibir una notificación de un cambio de interfaz de enrutamiento que se debe usar para llegar a la dirección remota en el búfer de entrada (especificado como una estructura sockaddr ). No se proporcionará información de salida sobre la nueva interfaz de enrutamiento tras la finalización de este IOCTL; la finalización simplemente indica que la interfaz de enrutamiento de un destino determinado ha cambiado y se debe consultar mediante el SIO_ROUTING_INTERFACE_QUERY IOCTL .

Se supone (aunque no es necesario) que la aplicación usa E/S superpuesta para recibir una notificación del cambio de interfaz de enrutamiento a través de la finalización de SIO_ROUTING_INTERFACE_CHANGE solicitud. Como alternativa, si el SIO_ROUTING_INTERFACE_CHANGE IOCTL se emite en un socket sin bloqueo con los parámetros lpOverlapped y lpCompletionRoutine establecidos en NULL), se completará inmediatamente con el error WSAEWOULDBLOCK y el cliente SPI de Windows Socket puede esperar a que los eventos de cambio de enrutamiento usen una llamada a LPWSPEventSelect o LPWSPAsyncSelect con el FD_ROUTING_INTERFACE_CHANGE bit establecido en la máscara de bits del evento de red.

Se reconoce que la información de enrutamiento permanece estable en la mayoría de los casos para que la aplicación mantenga varias ICTL pendientes para obtener notificaciones sobre todos los destinos en los que está interesado, así como que el proveedor de servicios realice un seguimiento de estas solicitudes de notificación usará una cantidad significativa de recursos del sistema. Esta situación se puede evitar mediante la extensión del significado de los parámetros de entrada y la relajación de los requisitos del proveedor de servicios de la siguiente manera:

El cliente SPI de Windows Sockets puede especificar una dirección comodín específica de la familia de protocolos (igual que la que se usa en la llamada binding a cualquier dirección disponible) para solicitar notificaciones de cualquier cambio de enrutamiento. Esto permite al cliente SPI de Windows Sockets mantener solo una SIO_ROUTING_INTERFACE_CHANGE pendiente para todos los sockets y destinos que tiene y, a continuación, usar SIO_ROUTING_INTERFACE_QUERY para obtener la información de enrutamiento real.

El proveedor de servicios puede optar por omitir la información proporcionada por el cliente SPI de Windows Sockets en el búfer de entrada del SIO_ROUTING_INTERFACE_CHANGE (como si el cliente SPI de Windows Sockets especificara una dirección comodín) y completar el SIO_ROUTING_INTERFACE_CHANGE IOCTL o señal FD_ROUTING_INTERFACE_CHANGE evento en caso de cualquier cambio de información de enrutamiento (no solo la ruta al destino especificado en el búfer de entrada).

SIO_ROUTING_INTERFACE_QUERY (configuración de opcode: I, O, T==1)

Para obtener la dirección de la interfaz local (representada como estructura sockaddr ) que se debe usar para enviar a la dirección remota especificada en el búfer de entrada (como sockaddr). Las direcciones de multidifusión remota se pueden enviar en el búfer de entrada para obtener la dirección de la interfaz preferida para la transmisión de multidifusión. En cualquier caso, la aplicación puede usar la dirección de interfaz devuelta en una solicitud Bind posterior.

Tenga en cuenta que las rutas están sujetas a cambios. Por lo tanto, los clientes SPI de Windows Socket no pueden confiar en la información devuelta por SIO_ROUTING_INTERFACE_QUERY ser persistente. Los clientes SPI pueden registrarse para enrutar las notificaciones de cambio mediante el SIO_ROUTING_INTERFACE_CHANGE IOCTL, que proporciona notificaciones a través de E/S superpuestas o un evento de FD_ROUTING_INTERFACE_CHANGE. La siguiente secuencia de acciones se puede usar para garantizar que el cliente SPI de Windows Socket siempre tiene información de interfaz de enrutamiento actual para un destino determinado:

Problema SIO_ROUTING_INTERFACE_CHANGE IOCTL.
Problema SIO_ROUTING_INTERFACE_QUERY IOCTL.
Siempre que SIO_ROUTING_INTERFACE_CHANGE IOCTL notifica al cliente SPI de WinSock el cambio de enrutamiento (ya sea a través de E/S superpuesta o mediante la señalización FD_ROUTING_INTERFACE_CHANGE evento), se debe repetir toda la secuencia de acciones.

Si el búfer de salida no es lo suficientemente grande como para contener la dirección de la interfaz, se devuelve SOCKET_ERROR como resultado de este IOCTL y WSAGetLastError devuelve WSAEFAULT. El tamaño necesario del búfer de salida se devolverá en 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á totalmente incluido en una parte válida del espacio de direcciones del usuario.

Si no se puede acceder a la dirección de destino especificada en el búfer de entrada a través de ninguna de las interfaces disponibles, SOCKET_ERROR se devuelve como resultado de este IOCTL y WSAGetLastError devuelve WSAENETUNREACH o incluso WSAENETDOWN si se pierde toda la conectividad de red.

SIO_SET_COMPATIBILITY_MODE (configuración de código de operación: I, T==3)

Solicita cómo la pila de redes debe controlar determinados comportamientos para los que la forma predeterminada de controlar el comportamiento puede diferir en todas las versiones de Windows. La estructura de argumentos para SIO_SET_COMPATIBILITY_MODE se especifica en la estructura de WSA_COMPATIBILITY_MODE definida en el archivo de encabezado Mswsockdef.h . Esta estructura se define de la siguiente manera:

} WSA_COMPATIBILITY_MODE, *PWSA_COMPATIBILITY_MODE;

El valor especificado en el miembro BehaviorId indica el comportamiento solicitado. El valor especificado en el miembro TargetOsVersion indica la versión de Windows que se solicita para el comportamiento.

El miembro BehaviorId puede ser uno de los valores del tipo de enumeración WSA_COMPATIBILITY_BEHAVIOR_ID definido en el archivo de encabezado Mswsockdef.h . Los valores posibles para el miembro BehaviorId son los siguientes:

Término	Descripción
WsaBehaviorAll	Esto equivale a solicitar todos los posibles comportamientos compatibles definidos para WSA_COMPATIBILITY_BEHAVIOR_ID.
WsaBehaviorReceiveBuffering	Cuando el miembro TargetOsVersion se establece en un valor para Windows Vista o posterior, se permiten reducciones en el tamaño del búfer de recepción TCP en este socket mediante la opción de socket SO_RCVBUF incluso después de que se haya establecido una conexión TCP. Cuando el miembro TargetOsVersion se establece en un valor anterior a Windows Vista, no se permiten reducciones en el tamaño del búfer de recepción TCP en este socket mediante la opción de socket SO_RCVBUF después del establecimiento de la conexión.
WsaBehaviorAutoTuning	Cuando el miembro TargetOsVersion se establece en un valor para Windows Vista o posterior, se habilita el ajuste automático de la ventana de recepción y el factor de escala de ventanas TCP se reduce a 2 del valor predeterminado de 8. Cuando TargetOsVersion se establece en un valor anterior a Windows Vista, se deshabilita el ajuste automático de la ventana de recepción. La opción de escalado de ventanas TCP también está deshabilitada y el tamaño máximo real de la ventana de recepción está limitado a 65 535 bytes. La opción de escalado de ventanas TCP no se puede negociar en la conexión incluso si se llamó a la opción de socket SO_RCVBUF en este socket especificando un valor superior a 65 535 bytes antes de establecer la conexión.

Para obtener información más detallada, consulte la referencia de SIO_SET_COMPATIBILITY_MODE .

SIO_SET_COMPATIBILITY_MODE se admite en Windows Vista y versiones posteriores.

SIO_SET_GROUP_QOS (configuración de código de operación: I, T==1)

Reservado.

SIO_SET_QOS (configuración de opcode: I, T==1)

Asocie la estructura QOS proporcionada al socket. No se requiere ningún búfer de salida, la estructura de QOS se obtendrá del búfer de entrada. El código de error WSAENOPROTOOPT se indica para los proveedores de servicios que no admiten la calidad del servicio.

SIO_TRANSLATE_HANDLE (configuración de opcode: I, O, T==1)

Para obtener un identificador correspondiente para los sockets que son válidos en el contexto de una interfaz complementaria (por ejemplo, TH_NETDEV y TH_TAPI). Una constante de manifiesto que identifica la interfaz complementaria junto con cualquier otro parámetro necesario se especifica en el búfer de entrada. El identificador correspondiente estará disponible en el búfer de salida tras la finalización de esta función. Consulte la sección correspondiente en el anexo de Windows Sockets 2 Protocol-Specific o la documentación de la interfaz complementaria concreta para obtener más detalles. El código de error WSAENOPROTOOPT se indica para los proveedores de servicios que no admiten este IOCTL para la interfaz complementaria especificada. Este IOCTL recupera el identificador asociado mediante SIO_TRANSLATE_HANDLE.

Se recomienda usar COM en lugar de este IOCTL para detectar y realizar un seguimiento de otras interfaces compatibles con un socket. Este IOCTL está presente para la compatibilidad con versiones anteriores con sistemas en los que COM no está disponible o no se puede usar por alguna otra razón.

SIO_UDP_CONNRESET (configuración de código de operación: I, T==3)

Windows XP: Controla si se notifican mensajes de PORT_UNREACHABLE UDP. Establézcalo en TRUE para habilitar los informes. Establézcalo en FALSE para deshabilitar los informes.

Cuando se llama con un socket superpuesto, el parámetro lpOverlapped debe ser válido durante la operación superpuesta.

Si el parámetro lpCompletionRoutine es NULL, el proveedor de servicios señala al miembro hEvent de lpOverlapped cuando se completa la operación superpuesta si contiene un identificador de objeto de evento válido. El cliente SPI de Windows Sockets puede usar LPWSPGetOverlappedResult para sondear o esperar en el objeto de evento.

Si lpCompletionRoutine no es NULL, el miembro hEvent se omite y el cliente SPI de Windows Sockets puede usarse para pasar información de contexto a la rutina de finalización. Un cliente que pasa un lpCompletionRoutine no NULL y, posteriormente, llama a WSAGetOverlappedResult para la misma solicitud de E/S superpuesta no puede establecer el parámetro fWait para esa invocación de WSAGetOverlappedResult en TRUE. En este caso, el uso del miembro hEvent no está definido y el intento de esperar en el miembro hEvent produciría resultados imprevisibles.

Es responsabilidad del proveedor de servicios organizar la invocación de la rutina de finalización especificada por el cliente cuando se completa la operación superpuesta. Puesto que la rutina de finalización debe ejecutarse en el contexto del mismo subproceso que inició la operación superpuesta, no se puede invocar directamente desde el proveedor de servicios. El WS2_32.DLL ofrece un mecanismo de llamada a procedimiento asincrónico (APC) para facilitar la invocación de rutinas de finalización.

Un proveedor de servicios organiza una función que se va a ejecutar en el subproceso y el contexto de proceso adecuados mediante una llamada a WPUQueueApc. Se puede llamar a esta función desde cualquier contexto de proceso y subproceso, incluso un contexto diferente del subproceso y el proceso que se usó para iniciar la operación superpuesta.

WPUQueueApc toma como parámetros de entrada un puntero a una estructura WSATHREADID (proporcionada al proveedor a través del parámetro de entrada lpThreadId ), un puntero a una función de APC que se va a invocar y un valor de contexto de 32 bits que se pasa posteriormente a la función APC. Dado que solo hay disponible un único valor de contexto de 32 bits, la propia función de APC no puede ser la rutina de finalización especificada por el cliente. En su lugar, el proveedor de servicios debe proporcionar un puntero a su propia función de APC que usa el valor de contexto proporcionado para tener acceso a la información de resultado necesaria para la operación superpuesta y, a continuación, invoca la rutina de finalización especificada por el cliente.

El prototipo de la rutina de finalización proporcionada por el cliente es el siguiente:

);

CompletionRoutine es un marcador de posición para una función proporcionada por el cliente. DwError especifica el estado de finalización de la operación superpuesta, como se indica en lpOverlapped. CbTransferred especifica el número de bytes devueltos. Actualmente, no hay valores de marca definidos y dwFlags será cero. Esta función no devuelve ningún valor.

La devolución de esta función permite la invocación de otra rutina de finalización pendiente para este socket. Se puede llamar a las rutinas de finalización en cualquier orden, aunque no necesariamente en el mismo orden en que se completan las operaciones superpuestas.

Compatibilidad

Los códigos IOCTL con T == 0 son un subconjunto de los códigos IOCTL usados en sockets de Berkeley. En concreto, no hay ningún comando equivalente a FIOASYNC.

Nota

Todas las E/S iniciadas por un subproceso determinado se cancelan cuando se cierra ese subproceso. En el caso de los sockets superpuestos, las operaciones asincrónicas pendientes pueden producir un error si el subproceso está cerrado antes de que se completen las operaciones. Consulte ExitThread para obtener más información.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	ws2spi.h

Consulte también

Función de devolución de llamada LPWSPIOCTL (ws2spi.h)

Sintaxis

Parámetros

Valor devuelto

Observaciones

Compatibilidad

Requisitos

Consulte también

Comentarios

Comentarios

Recursos adicionales