Función de devolución de llamada LPWSPASYNCSELECT (ws2spi.h)
La función LPWSPAsyncSelect solicita una notificación de eventos basada en mensajes de Windows de eventos de red para un socket.
Sintaxis
LPWSPASYNCSELECT Lpwspasyncselect;
int Lpwspasyncselect(
[in] SOCKET s,
[in] HWND hWnd,
[in] unsigned int wMsg,
[in] long lEvent,
[out] LPINT lpErrno
)
{...}
Parámetros
[in] s
Descriptor que identifica el socket para el que se requiere la notificación de eventos.
[in] hWnd
Controle la identificación de la ventana que debe recibir un mensaje cuando se produce un evento de red.
[in] wMsg
Mensaje que se va a enviar cuando se produce un evento de red.
[in] lEvent
Máscara de bits que especifica una combinación de eventos de red en los que está interesado el cliente de interfaz del proveedor de servicios (SPI) de Windows Sockets. Construido mediante el operador OR bit a bit con cualquiera de estos valores.
| Valor | Significado |
|---|---|
|
Notificación de problemas de preparación para la lectura. |
|
Emite una notificación de preparación para escribir. |
|
Notificación de problemas de llegada de datos OOB. |
|
Emite la notificación de las conexiones entrantes. |
|
Notificación de problemas de conexiones completadas. |
|
Emite la notificación del cierre del socket. |
|
Problemas de notificación de la calidad del socket de los cambios del servicio (QoS). |
|
Reservado. |
|
Emite la notificación del cambio de interfaz de enrutamiento para el destino especificado. |
|
Emite la notificación del cambio de lista de direcciones local para la familia de protocolos del socket. |
[out] lpErrno
Puntero al código de error. Consulte la sección Valor devuelto para obtener más información.
Valor devuelto
El valor devuelto es cero si la declaración de interés del cliente SPI de Windows Sockets en el conjunto de eventos de red se realizó correctamente. De lo contrario, se devuelve el valor SOCKET_ERROR y hay disponible un código 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, como el identificador de ventana que no hace referencia a una ventana existente o que el socket especificado está en un estado no válido. | |
| Una llamada de Bloqueo de 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. |
Vea Comentarios para obtener información sobre códigos de error adicionales que se pueden establecer (en la palabra alta de lParam dentro del mensaje) cuando una ventana de la aplicación recibe un mensaje.
Comentarios
Esta función se usa para solicitar que el proveedor de servicios envíe un mensaje de Windows a la ventana del cliente hWnd siempre que el proveedor de servicios detecte cualquiera de los eventos de red especificados por el argumento lEvent . El proveedor de servicios debe usar la función WPUPostMessage para publicar el mensaje. El parámetro wMsg especifica el mensaje que se va a enviar. El socket para el que se requiere la notificación se identifica mediante s.
Esta función establece automáticamente sockets en modo de no bloqueo, independientemente del valor de lEvent. Consulte LPWSPIoctl sobre cómo establecer el socket en modo de bloqueo.
La invocación de LPWSPAsyncSelect para un socket cancela cualquier LPWSPAsyncSelect o LPWSPEventSelect para el mismo socket. Por ejemplo, para recibir notificaciones para leer y escribir, el cliente SPI de Windows Sockets debe llamar a LPWSPAsyncSelect con FD_READ y FD_WRITE, como este.
rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);
No es posible especificar mensajes diferentes para eventos diferentes. El código siguiente no funcionará; la segunda llamada cancela los efectos del primero y la única asociación será el evento FD_WRITE asociado a wMsg2.
// Incorrect example.
rc = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);
Para cancelar todas las notificaciones (es decir, para indicar que el proveedor de servicios no debe enviar más mensajes relacionados con los eventos de red en el socket), establezca lEvent en cero.
rc = WSPAsyncSelect(s, hWnd, 0, 0, &error);
Dado que un socket LPWSPAccept'ed tiene las mismas propiedades que el socket de escucha usado para aceptarlo, los eventos LPWSPAsyncSelect establecidos para el socket de escucha se aplican al socket aceptado. Por ejemplo, si un socket de escucha tiene eventos LPWSPAsyncSelect FD_ACCEPT, FD_READ y FD_WRITE, cualquier socket aceptado en ese socket de escucha también tendrá FD_ACCEPT, FD_READ y eventos FD_WRITE con el mismo valor wMsg usado para los mensajes. Si se desean otros eventos o wMsg , el cliente SPI de Windows Sockets debe llamar a LPWSPAsyncSelect, pasar el socket aceptado y la nueva información deseada.
Cuando se produce uno de los eventos de red designados en los sockets especificados, el proveedor de servicios usa WPUPostMessage para enviar mensajes wMsg a la ventana del cliente SPI de Windows Sockets hWnd. En el mensaje publicado, el argumento wParam identifica el socket en el que se ha producido un evento de red. La palabra baja de lParam especifica el evento de red que se ha producido. Los posibles códigos de evento de red que se pueden indicar son los siguientes.
| Valor | Significado |
|---|---|
| FD_READ | Sockets está listo para leer |
| FD_WRITE | Socket s está listo para escribir |
| FD_OOB | Los datos fuera de banda están listos para leer en sockets |
| FD_ACCEPT | Sockets está listo para aceptar una nueva conexión entrante |
| FD_CONNECT | Se ha completado la conexión que se inició en el socket s . |
| FD_CLOSE | Se ha cerrado la conexión identificada por sockets. |
| FD_QOS | La calidad del servicio asociado con sockets ha cambiado |
| FD_GROUP_QOS | Reservado para uso futuro con grupos de sockets: la calidad del servicio asociado al grupo de sockets al que pertenece el socket ha cambiado. |
| FD_ROUTING_INTERFACE_CHANGE | La interfaz local que se debe usar para enviar al destino especificado ha cambiado. |
| FD_ADDRESS_LIST_CHANGE | La lista de direcciones de la familia de protocolos del socket al que el cliente SPI de Windows Sockets puede enlazar ha cambiado. |
La palabra alta de lParam contiene cualquier código de error (se puede extraer mediante la macro WSAGETSELECTERROR ). El código de error es cualquier error tal y como se define en ws2spi.h. Los posibles códigos de error para cada evento de red se enumeran en la tabla siguiente.
Evento: FD_CONNECT
| Código de error | Significado |
|---|---|
| Las direcciones de la familia especificada no se pueden usar con este socket. | |
| El intento de conexión se rechazó. | |
| La red no se puede alcanzar desde este host en estos momentos. | |
| El parámetro namelen no es válido. | |
| El socket ya está enlazado a una dirección. | |
| El socket ya está conectado. | |
| No hay más descriptores de archivo disponibles. | |
| No hay espacio disponible en el búfer. El socket no se puede conectar. | |
| El socket no está conectado. | |
| Se ha agotado el tiempo de espera de la conexión sin poder establecer una conexión. |
Evento: FD_CLOSE
| Código de error | Significado |
|---|---|
| Error en el subsistema de red. | |
| El lado remoto ha restablecido la conexión. | |
| La conexión se finalizó debido a un tiempo de espera u otro error. |
Event...: FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE
| Código de error | Significado |
|---|---|
| Error en el subsistema de red. |
Evento: FD_ROUTING_INTERFACE_CHANGE
| Código de error | Significado |
|---|---|
| El destino especificado ya no es accesible. | |
| Error en el subsistema de red. |
Aunque se puede llamar a LPWSPAsyncSelect con interés en varios eventos, el proveedor de servicios emite el mismo mensaje de Windows para cada evento.
Un proveedor de Windows Sockets 2 no debe inundar continuamente un cliente SPI de Windows Sockets con mensajes para un evento de red determinado. Después de publicar correctamente una notificación de un evento determinado en una ventana de cliente SPI de Windows Sockets, no se publicarán más mensajes para ese evento de red en la ventana del cliente SPI de Windows Sockets hasta que el cliente SPI de Windows Sockets realice la llamada de función que vuelve a habilitar implícitamente la notificación de ese evento de red.
| 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 de condición 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 el comando SIO_ROUTING_INTERFACE_CHANGE |
| FD_ADDRESS_LIST_CHANGE | LPWSPIoctl con el comando SIO_ADDRESS_LIST_CHANGE |
Cualquier llamada a la rutina de volver a habilitar, incluso una que produzca un error, da como resultado volver a habilitar la publicación de mensajes para el evento pertinente.
Para eventos de FD_READ, FD_OOB y FD_ACCEPT, la publicación de mensajes se desencadena a nivel. Esto significa que si se llama a la rutina de volver a habilitar y la condición pertinente se sigue cumpliendo después de la llamada, se publica un mensaje LPWSPAsyncSelect en el cliente SPI de Windows Sockets.
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 QOS. No se publicarán más mensajes hasta que el proveedor 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 emitiendo WSAIoctl con SIO_ROUTING_INTERFACE_CHANGE o SIO_ADDRESS_LIST_CHANGE correspondientemente. No se publicarán más mensajes hasta que el cliente SPI de Windows Sockets vuelva a emitir el IOCTL y se detecte otro cambio, ya que se ha emitido el IOCTL.
Si ya se ha producido algún evento cuando el cliente SPI de Windows Sockets llama a LPWSPAsyncSelect, o cuando se llama a la función de nueva habilitación, se publica un mensaje 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 LPWSPAsyncSelect especificando que quiere recibir mensajes FD_ACCEPT para el socket. Debido a la persistencia de eventos, el proveedor de servicios winSock publica inmediatamente un mensaje de FD_ACCEPT.
El evento FD_WRITE se controla ligeramente de forma diferente. Un mensaje de FD_WRITE se publica cuando un socket se conecta por primera vez con LPWSPConnect (después de FD_CONNECT, si también está registrado) o aceptado con LPWSPAccept, y 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 del primer mensaje de FD_WRITE y duraderos hasta que un envío devuelve WSAEWOULDBLOCK. Después de este error, se notificará al cliente SPI de Windows Sockets que los envíos son posibles de nuevo con un mensaje de FD_WRITE.
El evento 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 en eventos de FD_READ, no FD_OOB eventos.
El código de error de un mensaje de FD_CLOSE indica si el cierre del socket fue correcto o abortivo. Si el código de error es 0, el cierre fue correcto; Si el código de error es WSAECONNRESET, se restablece el circuito virtual del socket. Esto solo se aplica a sockets orientados a la conexión, como SOCK_STREAM.
El mensaje de FD_CLOSE se publica 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 publica cuando la conexión entra en los estados TIME WAIT o CLOSE WAIT. Esto resulta del extremo remoto que realiza un LPWSPShutdown en el lado de envío o un LPWSPCloseSocket. Es correcto que FD_CLOSE se publiquen solo una vez leídos todos los datos de un socket.
En el caso de un cierre correcto, el proveedor de servicios debe enviar un mensaje de FD_CLOSE para indicar el cierre del circuito virtual solo una vez leídos todos los datos recibidos. No debe enviar un mensaje de FD_READ para indicar esta condición.
El FD_QOS o FD_GROUP_QOS mensaje se publica 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. El proveedor de servicios debe actualizar la información de QOS disponible para el cliente a través de LPWSPIoctl con SIO_GET_QOS o SIO_GET_GROUP_QOS.
El mensaje de FD_ROUTING_INTERFACE_CHANGE se publica cuando la interfaz local que se debe usar para llegar al destino especificado en LPWSPIoctl con SIO_ROUTING_INTERFACE_CHANGE cambios después de que se haya emitido dicho IOCTL.
El mensaje de FD_ADDRESS_LIST_CHANGE se publica cuando se publica la lista de direcciones a las que el cliente SPI de Windows Sockets puede enlazar los cambios después de que se haya emitido LPWSPIoctl con SIO_ADDRESS_LIST_CHANGE.
Este es un resumen de eventos y condiciones para cada mensaje de notificación asincrónico.
FD_READ
- Cuando se llama a LPWSPAsyncSelect , si hay datos disponibles actualmente para recibir.
- Cuando llegan los datos, si FD_READ aún no se han publicado.
- Después de llamar a LPWSPRecv o LPWSPRecvFrom (con o sin MSG_PEEK), si los datos siguen estando disponibles para recibirse.
Cuando se habilita lpWSPSetSockOpt SO_OOBINLINE, los datos incluyen datos normales y datos fuera de banda (OOB) en las instancias indicadas anteriormente.
FD_WRITE
- Cuando se llama a LPWSPAsyncSelect , si es posible un LPWSPSend o LPWSPSendTo .
- Después de llamar a LPWSPConnect o LPWSPAccept , cuando se establece la conexión.
- Después de que LPWSPSend o LPWSPSendTo produzca un error con WSAEWOULDBLOCK, cuando LPWSPSend o LPWSPSendTo son probables que se realicen correctamente.
- Después de LPWSPBind en un socket sin conexión. FD_WRITE pueden producirse o no en este momento (dependientes de la implementación). En cualquier caso, un socket sin conexión siempre se puede escribir inmediatamente después de LPWSPBind.
FD_OOB (válido solo cuando LPWSPSetSockOpt SO_OOBINLINE está deshabilitado (valor predeterminado))
- Cuando se llama a LPWSPAsyncSelect , si hay datos de OOB disponibles actualmente para recibir con la marca MSG_OOB.
- Cuando llegan los datos de OOB, si FD_OOB aún no se han publicado.
- Después de llamar a LPWSPRecv o LPWSPRecvFrom con o sin MSG_OOB marca, si los datos de OOB siguen estando disponibles para recibirse.
FD_ACCEPT
- Cuando se llama a LPWSPAsyncSelect , si actualmente hay una solicitud de conexión disponible para aceptar.
- Cuando llega una solicitud de conexión, si FD_ACCEPT aún no se ha publicado.
- Después de llamar a LPWSPAccept , si hay otra solicitud de conexión disponible para aceptar.
FD_CONNECT
- Cuando se llama a LPWSPAsyncSelect , si actualmente hay una conexión establecida.
- Después de llamar a LPWSPConnect , cuando se establece la conexión (incluso cuando LPWSPConnect se realiza inmediatamente, como es habitual con un socket de datagrama) e incluso cuando se produce un error inmediatamente).
- Después de llamar a WSPJoinLeaf , cuando se completa la operación de combinación.
- Después de conectarse, se llamó a WSAConnect o WSPJoinLeaf con un socket orientado a la conexión sin bloqueo. La operación inicial devolvió un error específico de WSAEWOULDBLOCK, pero la operación de red siguió adelante. Si la operación se realiza correctamente o no, cuando se ha determinado el resultado, FD_CONNECT se produce. El cliente debe comprobar el código de error para determinar si el resultado fue correcto o erróneo.
FD_CLOSE (válido solo en sockets orientados a la conexión (por ejemplo, SOCK_STREAM))
- Cuando se llama a LPWSPAsyncSelect , si se ha cerrado la conexión de socket.
- Después de que el sistema remoto haya iniciado un cierre correcto, cuando no haya datos disponibles actualmente para recibir (si se han recibido datos y está esperando que se lean cuando el sistema remoto inicia un cierre correcto, la FD_CLOSE no se entrega hasta que se hayan leído todos los datos pendientes).
- Una vez que el sistema local inicia un cierre correcto con LPWSPShutdown y el sistema remoto ha respondido con una notificación de fin de datos (como TCP FIN), cuando no hay datos disponibles actualmente para recibir.
- Cuando el sistema remoto anula la conexión (por ejemplo, TCP RST enviado) y lParam contendrá el valor de error WSAECONNRESET.
FD_CLOSE no se publica después de llamar a LPWSPCloseSocket .
FD_QOS
- Cuando se llama a LPWSPAsyncSelect , si se ha cambiado el QOS asociado al socket.
- Después de llamar a LPWSPIoctl con SIO_GET_QOS, cuando se cambia el QOS.
FD_GROUP_QOS
Reservado para uso futuro con grupos de sockets:
- Cuando se llama a LPWSPAsyncSelect , si se ha cambiado el grupo de QOS asociado al socket.
- Después de llamar a LPWSPIoctl con SIO_GET_GROUP_QOS, cuando se cambia el grupo QOS.
FD_ROUTING_INTERFACE_CHANGE
- después de llamar a LPWSPIoctl con SIO_ROUTING_INTERFACE_CHANGE, cuando cambia la interfaz local que se debe usar para llegar al destino especificado en el IOCTL.
FD_ADDRESS_LIST_CHANGE
- Después de llamar a LPWSPIoctl con SIO_ADDRESS_LIST_CHANGE, cuando se llama a la lista de direcciones locales a las que el cliente SPI de Windows Sockets puede enlazar los cambios.
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
LPWSPAsyncSelect callback (Función de devolución de llamada)
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