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 ioCTLs 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 de WSAOVERLAPPED (omitida para sockets no superpuestos).
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valor devuelto
Tras la finalización correcta, el
| Código de error | Significado |
|---|---|
| Una operación superpuesta se inició correctamente y la finalización se indicará más adelante. | |
| Error en el subsistema de red. | |
|
El |
|
| 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 hay una devolución de llamada 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 |
|
| El socket se marca como sin bloqueo y la operación solicitada se bloquearía. | |
| La opción de 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 datagram. |
Observaciones
La función
Si tanto lpOverlapped como lpCompletionRoutine son NULL, el socket de esta función se tratará como un socket no superpuesto. En el caso de un socket no superpuesto,
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
Cualquier IOCTL puede bloquearse indefinidamente, dependiendo de la implementación del proveedor de servicios. Si la aplicación no puede tolerar el bloqueo en una llamada de WSAIoctl, se recomienda la E/S superpuesta para las E/S superpuestas que son especialmente probables bloquear, entre las que se incluyen:
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 ICTL 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
Es posible adoptar un esquema de codificación que conserve el
| Yo | 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 siguientes valores:
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 solo se aplica a una familia de direcciones específica.
3 El IOCTL solo se aplica al proveedor de un proveedor específico, como con IOC_VENDOR. Este tipo permite que a las empresas se les asigne un número de proveedor que aparece en el parámetro
familia proveedor/dirección Una cantidad de 11 bits que define el 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, no se actualiza lpcbBytesReturned. 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 a través del parámetro lpcbTransfer en WSAGetOverlappedResult.
Cuando se llama a con un socket superpuesto, el parámetro lpOverlapped debe ser válido durante la operación superpuesta. El parámetro
Si el parámetro
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
);
Este 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 estado de alerta. Para colocar un subproceso en un estado de alerta, use el WSAWaitForMultipleEvents, WaitForSingleObjectExo función WaitForMultipleObjectsEx con el fAlertable o parámetro 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
La devolución de esta función permite invocar 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 de
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 | Valor |
|---|---|
| cliente mínimo admitido | Windows 8.1, Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP] |
| servidor mínimo admitido | Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP] |
| de la plataforma de destino de |
Windows |
| encabezado de |
winsock2.h |
| biblioteca de |
Ws2_32.lib |
| DLL de |
Ws2_32.dll |
Consulte también
opciones de socket de
de socket de