Función de devolución de llamada LPWSPEVENTSELECT (ws2spi.h)
La función LPWSPEventSelect especifica un objeto de evento que se va a asociar al conjunto proporcionado de eventos de red.
Sintaxis
LPWSPEVENTSELECT Lpwspeventselect;
int Lpwspeventselect(
[in] SOCKET s,
[in] WSAEVENT hEventObject,
[in] long lNetworkEvents,
[out] LPINT lpErrno
)
{...}
Parámetros
[in] s
Descriptor que identifica el socket.
[in] hEventObject
Identificador que identifica el objeto de evento que se va a asociar al conjunto proporcionado de eventos de red.
[in] lNetworkEvents
Máscara de bits que especifica la combinación de eventos de red en los que el cliente SPI de Windows Sockets tiene interés. Construido mediante el operador OR bit a bit con cualquiera de estos valores.
| Valor | Significado |
|---|---|
|
Emite la notificación de preparación para la lectura. |
|
Emite la notificación de preparación para escribir. |
|
Notificación de problemas de la llegada de datos de OOB. |
|
Emite la notificación de las conexiones entrantes. |
|
Notificación de problemas de conexión completada. |
|
Emite la notificación del cierre del socket. |
|
Problemas de notificación de cambios de socket (QoS). |
|
Reservado. |
|
Emite la notificación de los cambios de la interfaz de enrutamiento para los destinos especificados. |
|
Emite la notificación de cambios en la lista de direcciones locales para la familia de direcciones del socket. |
[out] lpErrno
Puntero al código de error. Consulta la sección Valor devuelto para obtener más información.
Valor devuelto
El valor devuelto es cero si la especificación del cliente SPI de Windows Sockets de los eventos de red y el objeto de evento asociado se realizó correctamente. De lo contrario, se devuelve el valor SOCKET_ERROR y hay disponible un número de error específico en lpErrno.
| Código de error | Significado |
|---|---|
| Error en el subsistema de red. | |
| Indica que uno de los parámetros especificados no era válido o que el socket especificado está en un estado no válido. | |
| El bloqueo de la llamada a Windows Sockets está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada. | |
| El descriptor no es un socket. |
Comentarios
Esta función se usa para especificar un objeto de evento, hEventObject, que se asociará a los eventos de red seleccionados, lNetworkEvents. El socket para el que se especifica un objeto de evento se identifica mediante s. El objeto de evento se establece cuando se produce cualquiera de los eventos de red designados.
LPWSPEventSelect funciona de forma muy similar a LPWSPAsyncSelect, la diferencia en las acciones realizadas cuando se produce un evento de red designado. Mientras que WSPAsyncSelect hace que se publique un mensaje de Windows Especificado por el cliente SPI de Windows Sockets, LPWSPEventSelect establece el objeto de evento asociado y registra la aparición de este evento en un registro de eventos de red interno. Un cliente SPI de Windows Sockets puede usar LPWSPEnumNetworkEvents para recuperar el contenido del registro de eventos de red interno y, por tanto, determinar cuál de los eventos de red designados se ha producido.
LPWSPEventSelect es la única función que hace que la actividad de red y los errores se registren y recuperen a través de LPWSPEnumNetworkEvents. Consulte las descripciones de LPWSPSelect y LPWSPAsyncSelect para averiguar cómo estas funciones notifican la actividad de red y los errores.
Esta función establece automáticamente sockets en modo sin bloqueo, independientemente del valor de lNetworkEvents.
La emisión de un LPWSPEventSelect para un socket cancela cualquier LPWSPAsyncSelect o LPWSPEventSelect para el mismo socket y borra el registro de eventos de red interno. Por ejemplo, para asociar un objeto de evento con eventos de red de lectura y escritura, el cliente SPI de Windows Sockets debe llamar a LPWSPEventSelect con FD_READ y FD_WRITE, como este.
rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);
No es posible especificar objetos de evento diferentes para eventos de red diferentes. El código siguiente no funcionará; la segunda llamada cancela los efectos del primero y la única asociación será el evento de red FD_WRITE asociado a hEventObject2.
// Incorrect example.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE);
Para cancelar la asociación y selección de eventos de red en un socket, debe establecer lNetworkEvents en cero, en cuyo caso se omite el parámetro hEventObject .
rc = WSPEventSelect(s, hEventObject, 0);
Al cerrar un socket con LPWSPCloseSocket también se cancela la asociación y selección de eventos de red especificados en LPWSPEventSelect para el socket. Sin embargo, el cliente SPI de Windows Sockets debe llamar a WSACloseEvent para cerrar explícitamente el objeto de evento y liberar los recursos.
Dado que un socket LPWSPAccept'ed tiene las mismas propiedades que el socket de escucha usado para aceptarlo, cualquier selección de eventos de red y asociación LPWSPEventSelect establecida para el socket de escucha se aplica al socket aceptado. Por ejemplo, si un socket de escucha tiene la asociación LPWSPEventSelect de hEventObject con FD_ACCEPT, FD_READ y FD_WRITE, cualquier socket aceptado en ese socket de escucha también tendrá FD_ACCEPT, FD_READ y FD_WRITE eventos de red asociados con el mismo hEventObject. Si se desea otro hEventObject o eventos de red, el cliente SPI de Windows Sockets debe llamar a LPWSPEventSelect, pasar el socket aceptado y la nueva información deseada.
Después de registrar correctamente la aparición del evento de red y señalar el objeto de evento asociado, no se realizan más acciones para ese evento de red hasta que el cliente SPI de Windows Sockets realiza la llamada de función que vuelve a habilitar implícitamente la configuración de ese evento de red y la señalización del objeto de evento asociado.
| Evento de red | Volver a habilitar la función |
|---|---|
| FD_READ | LPWSPRecv o LPWSPRecvFrom |
| FD_WRITE | LPWSPSend o LPWSPSendTo |
| FD_OOB | LPWSPRecv o LPWSPRecvFrom |
| FD_ACCEPT | LPWSPAccept, a menos que el código de error devuelto sea WSATRY_AGAIN que indique que la función condition devolvió CF_DEFER |
| FD_CONNECT | Ninguno |
| FD_CLOSE | Ninguno |
| FD_QOS | LPWSPIoctl con SIO_GET_QOS |
| FD_GROUP_QOS | Reservado para uso futuro con grupos de sockets: LPWSPIoctl con SIO_GET_GROUP_QOS |
| FD_ROUTING_INTERFACE_CHANGE | LPWSPIoctl con SIO_ROUTING_INTERFACE_CHANGE de comandos |
| FD_ADDRESS_LIST_CHANGE | LPWSPIoctl con SIO_ADDRESS_LIST_CHANGE de comandos |
Cualquier llamada a la rutina de volver a habilitar, incluso una que produce un error, da como resultado volver a habilitar la grabación y la señalización para el evento de red y el objeto de evento pertinentes, respectivamente.
Para FD_READ, FD_OOB y eventos de red FD_ACCEPT, la grabación de eventos de red y la señalización de objetos de evento se desencadenan a nivel. Esto significa que si se llama a la rutina de volver a habilitar y la condición de red pertinente sigue siendo válida después de la llamada, se registra el evento de red y se señala el objeto de evento asociado. Esto permite que un cliente SPI de Windows Sockets esté controlado por eventos y, al mismo tiempo, no tenga en cuenta la cantidad de datos que llegan en cualquier momento. Considere la siguiente secuencia.
- El proveedor de servicios recibe 100 bytes de datos en sockets s, registra el evento de red FD_READ y señala el objeto de evento asociado.
- El cliente SPI de Windows Sockets tiene problemas
WSPRecv(s, buffptr, 50, 0)para leer 50 bytes. - El proveedor de servicios registra el evento de red FD_READ y señala de nuevo el objeto de evento asociado, ya que todavía hay datos que se van a leer.
Con esta semántica, un cliente SPI de Windows Sockets no necesita leer todos los datos disponibles en respuesta a un evento de red de FD_READ. En su lugar, un único LPWSPRecv en respuesta a cada evento de red FD_READ es adecuado.
Los eventos FD_QOS y FD_GROUP_QOS se consideran desencadenados de forma perimetral. Un mensaje se publicará exactamente una vez cuando se produzca un cambio de calidad de servicio (QOS). No se emitirán indicaciones adicionales hasta que el proveedor de servicios detecte un cambio adicional en QOS o el cliente SPI de Windows Sockets renegocia el QOS para el socket.
Los eventos FD_ROUTING_INTERFACE_CHANGE y FD_ADDRESS_LIST_CHANGE también se consideran desencadenados de forma perimetral . Un mensaje se publicará exactamente una vez cuando se produzca un cambio después de que el cliente SPI de Windows Sockets haya solicitado la notificación mediante la emisión de WSAIoctl con SIO_ROUTING_INTERFACE_CHANGE o SIO_ADDRESS_LIST_CHANGE correspondiente. No habrá más mensajes hasta que el cliente SPI de Windows Sockets vuelva a emitir el IOCTL y se detecte otro cambio desde que se emitió el IOCTL.
Si ya se ha producido un evento de red cuando el cliente SPI de Windows Sockets llama a LPWSPEventSelect, o cuando se llama a la función de nueva habilitación, se registra un evento de red y se señala el objeto de evento asociado, según corresponda. Por ejemplo, considere la siguiente secuencia.
- Un cliente SPI de Windows Sockets llama a LPWSPListen.
- Se recibe una solicitud de conexión, pero aún no se acepta.
- El cliente SPI de Windows Sockets llama a LPWSPEventSelect especificando que está interesado en el evento de red FD_ACCEPT para el socket. El proveedor de servicios registra el evento de red FD_ACCEPT y señala inmediatamente el objeto de evento asociado.
El evento de red FD_WRITE se controla ligeramente de forma diferente. Un evento de red de FD_WRITE se registra cuando un socket se conecta por primera vez con LPWSPConnect o se acepta con LPWSPAccept y, a continuación, después de que un LPWSPSend o LPWSPSendTo produzca un error con WSAEWOULDBLOCK y el espacio de búfer esté disponible. Por lo tanto, un cliente SPI de Windows Sockets puede suponer que los envíos son posibles a partir de la primera configuración de evento de red FD_WRITE y duradera hasta que un envío devuelve WSAEWOULDBLOCK. Después de este error, el cliente SPI de Windows Sockets encontrará que los envíos vuelven a ser posibles cuando se registra un evento de red de FD_WRITE y se señala el objeto de evento asociado.
El evento de red FD_OOB solo se usa cuando un socket está configurado para recibir datos fuera de banda por separado. Si el socket está configurado para recibir datos fuera de banda en línea, los datos fuera de banda (acelerados) se tratan como datos normales, y el cliente SPI de Windows Sockets debe registrar un interés y obtendrá, FD_READ evento de red, no FD_OOB evento de red. Un cliente SPI de Windows Sockets puede establecer o inspeccionar la forma en que se van a controlar los datos fuera de banda mediante LPWSPSetSockOpt o LPWSPGetSockOpt para la opción de SO_OOBINLINE.
El código de error de un evento de red de FD_CLOSE indica si el cierre del socket era correcto o anulativo. Si el código de error es 0, el cierre fue correcto; Si el código de error es WSAECONNRESET, se restableció el circuito virtual del socket. Esto solo se aplica a sockets orientados a la conexión, como SOCK_STREAM.
El evento de red FD_CLOSE se registra cuando se recibe una indicación de cierre para el circuito virtual correspondiente al socket. En términos TCP, esto significa que el FD_CLOSE se registra cuando la conexión entra en los estados FIN WAIT o CLOSE WAIT. Esto resulta del extremo remoto que realiza un LPWSPShutdown en el lado de envío o un LPWSPCloseSocket.
Los proveedores de servicios solo deben registrar un evento de red FD_CLOSE para indicar el cierre de un circuito virtual; no debe registrar un evento de red FD_READ para indicar esa condición.
El evento de red FD_QOS o FD_GROUP_QOS se registra cuando se ha producido un cambio en cualquier campo de la especificación de flujo asociada a sockets o al grupo de sockets al que pertenece , respectivamente. Este cambio debe estar disponible para los clientes SPI de Windows Sockets a través de la función LPWSPIoctl con SIO_GET_QOS o SIO_GET_GROUP_QOS para recuperar el QOS actual para sockets, o para los grupos de sockets, respectivamente.
El evento de red FD_ROUTING_INTERFACE_CHANGE se registra cuando la interfaz local que se debe usar para llegar al destino especificado en WSAIoctl con SIO_ROUTING_INTERFACE_CHANGE cambios después de que se haya emitido dicho IOCTL.
El evento de red FD_ADDRESS_LIST_CHANGE se registra cuando se ha emitido la lista de direcciones de la familia de protocolos de sockets al que el cliente SPI de Windows Sockets puede enlazar los cambios después de que se haya emitido WSAIoctl con SIO_ADDRESS_LIST_CHANGE.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | compilación 20348 de Windows 10 |
| Servidor mínimo compatible | compilación 20348 de Windows 10 |
| Encabezado | ws2spi.h |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de