Compartir a través de


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

Nota 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 comentarios.
 

Valor devuelto

Tras la finalización correcta, el 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
WSA_IO_PENDING
Una operación superpuesta se inició correctamente y la finalización se indicará más adelante.
WSAENETDOWN
Error en el subsistema de red.
WSAEFAULT
EllpvInBuffer , lpvOutBuffer, lpcbBytesReturned, lpOverlapped, o parámetro lpCompletionRoutine no está totalmente incluido en una parte válida del espacio de direcciones del usuario, o el cbInBuffer o parámetro cbOutBuffer es demasiado pequeño.
WSAEINVAL
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.
WSAEINPROGRESS
La función se invoca cuando hay una devolución de llamada en curso.
WSAENOTSOCK
El descriptor s no es un socket.
WSAEOPNOTSUPP
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).
WSAEWOULDBLOCK
El socket se marca como sin bloqueo y la operación solicitada se bloquearía.
WSAENOPROTOOPT
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 WSAIoctl se usa para establecer o recuperar parámetros operativos asociados con el socket, el protocolo de transporte o el subsistema de comunicaciones.

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, lpOverlapped y parámetros lpCompletionRoutine se omiten, lo que hace que la función se comporte como la estándar función, excepto que la función puede bloquear si el socket s 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 (por ejemplo, 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 evento (mediante WSAEventSelect)-based notification mecanismo.

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 se puede omitir. 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 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 especifica el estado de finalización de la operación superpuesta, como se indica en 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 conserve el ioctlsocket definido actualmente códigos de operación, a la vez que proporciona una manera cómoda de crear particiones del espacio de identificadores de código de operación en tanto el parámetro dwIoControlCode es ahora una entidad de 32 bits. El parámetro dwIoControlCode de 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.

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
 
Nota Los bits de dwIoControlCode parámetro mostrado en la tabla deben leerse verticalmente de arriba a abajo por columna. Por lo tanto, el bit más a la izquierda es el bit 31, el siguiente bit es 30 y el bit más a la derecha es 0.
 
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. 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 Vendor/Address. A continuación, el proveedor puede definir nuevos ICTLs específicos de ese proveedor sin tener que registrar el IOCTL con un centro de compensación, lo que proporciona flexibilidad y privacidad del proveedor.

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 lpOverlapped contiene la dirección de una estructura WSAOVERLAPPED.

Si el parámetro lpCompletionRoutine es NULL, el parámetro hEvent de lpOverlapped se indica 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.

Nota se cancela toda la E/S iniciada por un subproceso determinado 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.
 
Si lpCompletionRoutine no es NULL, se omite el parámetro hEvent y la aplicación puede usarla para pasar información de contexto a la rutina de finalización. Un autor de llamada que pasa un noNULLlpCompletionRoutine y llamadas posteriores WSAGetOverlappedRes ult 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 parámetro hEvent no está definido e intentar esperar en el parámetro hEvent produciría resultados impredecibles.

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 CompletionRoutine no devuelve un valor.

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.
Nota Algunos códigos IOCTL requieren archivos de encabezado adicionales. Por ejemplo, el uso del SIO_RCVALL IOCTL requiere el archivo de encabezado Mstcpip.h.
 
Windows Phone 8: Esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

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 SOL_SOCKET

WSASocket

funciones winsock

de referencia de Winsock

getockopt

ioctlsocket

setsockopt

de socket de