Función WSAIoctl (winsock2.h)
La función WSAIoctl controla el modo de un socket.
Sintaxis
int WSAAPI WSAIoctl(
[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
);
Parámetros
[in] s
Descriptor que identifica un socket.
[in] dwIoControlCode
Código de control de la operación que se va a realizar. Consulte ICTLs de Winsock.
[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
Valor devuelto
Una vez finalizada correctamente, WSAIoctl devuelve cero. De lo contrario, se devuelve un valor de SOCKET_ERROR y se puede recuperar un código de error específico llamando a WSAGetLastError.
| Código de error | Significado |
|---|---|
| Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior. | |
| Error en el subsistema de red. | |
| El parámetro lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine 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. | |
| 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. | |
| La función se invoca cuando una devolución de llamada está en curso. | |
| El descriptor s no es un socket. | |
| No se puede realizar el comando IOCTL especificado. (Por ejemplo, no se pueden satisfacer las estructuras FLOWSPEC especificadas en SIO_SET_QOS o SIO_SET_GROUP_QOS ). | |
| El socket se marca como sin bloqueo y la operación solicitada se bloquearía. | |
| La opción socket no se admite en el protocolo especificado. Por ejemplo, se intentó usar el SIO_GET_BROADCAST_ADDRESS IOCTL en un socket IPv6 o se intentó usar el IOCTL de TCP SIO_KEEPALIVE_VALS en un socket de datagrama. |
Comentarios
La función WSAIoctl se usa para establecer o recuperar parámetros operativos asociados con el socket, el protocolo de transporte o el 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 un socket no superpuesto, se omiten los parámetros lpOverlapped y lpCompletionRoutine , lo que hace que la función se comporte como la función ioctlsocket estándar, excepto que la función puede bloquearse si sockets está en modo de bloqueo. Si el socket s está en modo de no bloqueo, esta función puede devolver WSAEWOULDBLOCK cuando la operación especificada no se pueda finalizar inmediatamente. En este caso, la aplicación 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 el caso de SIO_ROUTING_INTERFACE_CHANGE o SIO_ADDRESS_LIST_CHANGE) mediante un mensaje de Windows (mediante WSAAsyncSelect) o un evento basado en WSAEventSelect.
En el caso de los 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, en función de la implementación del proveedor de servicios. Si la aplicación no puede tolerar el bloqueo en una llamada WSAIoctl , se recomienda que las E/S superpuestas se bloqueen especialmente para las E/S superpuestas que son especialmente probables 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 IOCTL específicos del protocolo también pueden ser especialmente probables bloquear. Compruebe el anexo específico del protocolo correspondiente para obtener información disponible.
El prototipo de la rutina de finalización a la que apunta el parámetro lpCompletionRoutine es el siguiente:
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
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.
Es posible adoptar un esquema de codificación que conserva los códigos de operación ioctlsocket definidos actualmente, al tiempo que proporciona una manera cómoda de particionar el espacio del identificador de código de operación en tanto el parámetro dwIoControlCode es ahora una entidad de 32 bits. El parámetro dwIoControlCode se crea para permitir la independencia del protocolo y del proveedor al agregar nuevos códigos de control mientras 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.
| I | O | V | T | Familia de proveedores y direcciones | Código |
|---|---|---|---|---|---|
| 3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
| 1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
O se establece si el búfer de salida es válido para el código, como con IOC_OUT. Los códigos de control que usan los búferes de entrada y salida establecen E y O.
V se establece si no hay parámetros para el código, como con IOC_VOID.
T es una cantidad de 2 bits que define el tipo del IOCTL. Se definen los valores siguientes:
0 El IOCTL es un código IOCTL de Unix estándar, como con FIONREAD y FIONBIO.
1 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 El IOCTL se aplica únicamente a una familia de direcciones específica.
3 El IOCTL se aplica únicamente al proveedor de un proveedor específico, como con IOC_VENDOR. Este tipo permite asignar a las empresas un número de proveedor que aparece en el parámetro 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.
Familia de proveedores y direcciones Cantidad de 11 bits que define al proveedor que posee el código (si T == 3) 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 parámetro 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 parámetro se puede usar como extensión del parámetro de código para proporcionar valores de código adicionales.
Código Cantidad de 16 bits que contiene el código IOCTL específico para la operación.
Se admiten los siguientes códigos IOCTL de Unix (comandos).
Se admiten los siguientes comandos de Windows Sockets 2.
Si una operación superpuesta se completa inmediatamente, WSAIoctl 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 la operación superpuesta completa 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 WSAGetOverlappedResult.
Cuando se llama con un socket superpuesto, el parámetro lpOverlapped debe ser válido durante la operación superpuesta. El parámetro lpOverlapped contiene la dirección de una estructura WSAOVERLAPPED .
Si el parámetro lpCompletionRoutine es NULL, el parámetro hEvent de lpOverlapped se señala cuando se completa la operación superpuesta si contiene un identificador de objeto de evento válido. Una aplicación puede usar WSAWaitForMultipleEvents o WSAGetOverlappedResult para esperar o sondear en el objeto de evento.
El prototipo de la rutina de finalización es el siguiente:
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Esta CompletionRoutine es un marcador de posición para una función definida por la aplicación o definida por la biblioteca. La rutina de finalización solo se invoca si el subproceso está en un estado de alerta. Para colocar un subproceso en un estado de alerta, use la función WSAWaitForMultipleEvents, WaitForSingleObjectEx o WaitForMultipleObjectsEx con el parámetro fAlertable o bAlertable establecido en TRUE.
El parámetro dwError de CompletionRoutine especifica el estado de finalización de la operación superpuesta, como se indica en lpOverlapped. El parámetro cbTransferred especifica el número de bytes devueltos. Actualmente, no se definen valores de marca y dwFlags será cero. La función CompletionRoutine no devuelve un 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, 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.Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 8.1, Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | winsock2.h |
| Library | Ws2_32.lib |
| Archivo DLL | Ws2_32.dll |
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