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

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.

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.

void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags 
);