PFN_WSK_CONTROL_SOCKET función de devolución de llamada (wsk.h)

Artículo
03/05/2024

La función WskControlSocket realiza operaciones de control en un socket.

Sintaxis

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Parámetros

[in] Socket

Puntero a una estructura de WSK_SOCKET que especifica el objeto de socket para el socket en el que se realiza la operación de control.

[in] RequestType

Valor que especifica el tipo de operación de control que se está realizando. Una aplicación WSK establece este parámetro en uno de los valores siguientes:

WskSetOption

Establezca el estado o el valor de una opción de socket.

WskGetOption

Obtiene el estado o el valor de una opción de socket.

WskIoctl

Realice una operación de control de E/S.

[in] ControlCode

Si el parámetro RequestType se establece en WskSetOption o WskGetOption, el parámetro ControlCode especifica la opción de socket determinada cuyo valor se establece o recupera. Para obtener más información sobre las opciones de socket compatibles con el subsistema WSK, consulte Opciones de socket de WSK. El protocolo de red subyacente podría admitir opciones de socket adicionales.

Si el parámetro RequestType se establece en WskIoctl, el parámetro ControlCode especifica la operación de control de E/S determinada que se está realizando. Para obtener más información sobre las operaciones de control de E/S compatibles con el subsistema WSK, consulte Operaciones de IOCTL de socket de WSK. El protocolo de red subyacente podría admitir operaciones de control de E/S de socket adicionales.

[in] Level

Nivel de la pila de red en el que se establece o recupera el valor de una opción de socket. En el caso de las opciones de socket de nivel de subsistema de WSK, la aplicación WSK debe establecer este parámetro en SOL_SOCKET. En el caso de las opciones de socket de nivel de protocolo de transporte o protocolo de red, la aplicación WSK debe establecer este parámetro en el nivel adecuado para el transporte subyacente.

Si el parámetro RequestType se establece en WskIoctl, se omite el parámetro Level .

[in] InputSize

Número de bytes de datos en el búfer al que apunta el parámetro InputBuffer .

[in, optional] InputBuffer

Búfer asignado por el autor de la llamada que proporciona los datos de entrada necesarios para realizar la operación de control especificada. Si no se requieren datos de entrada para la operación de control especificada, la aplicación WSK debe establecer este parámetro en NULL y establecer el parámetro InputSize en cero.

[in] OutputSize

Tamaño del búfer al que apunta el parámetro OutputBuffer .

[out, optional] OutputBuffer

Búfer asignado por el autor de la llamada que recibe los datos de salida devueltos por la operación de control especificada. Si la operación de control especificada no devuelve ningún dato de salida, la aplicación WSK debe establecer este parámetro en NULL y establecer el parámetro OutputSize en cero.

[out, optional] OutputSizeReturned

Puntero a una variable con tipo ULONG que recibe el número de bytes de datos devueltos en el búfer al que apunta el parámetro OutputBuffer . Una aplicación WSK debe establecer el parámetro OutputSizeReturned enNULL , excepto cuando se cumplen todas las siguientes condiciones:

El parámetro Irp se establece en NULL.
La operación que se realiza devuelve datos de salida en el búfer al que apunta el parámetro OutputBuffer .
El número de bytes de datos de salida devueltos por la operación que se está realizando es desconocido.

[in, out] Irp

Puntero a un IRP asignado por el autor de la llamada que usa el subsistema WSK para completar la operación de control de forma asincrónica. Para obtener más información sobre el uso de IRP con funciones WSK, consulte Uso de IRP con funciones del kernel de Winsock.

Si el parámetro RequestType se establece en WskSetOption o WskGetOption, el parámetro Irp es obligatorio, es opcional o debe ser NULL en función de la opción de socket determinada que se establezca o recupere. Para obtener más información sobre los requisitos del parámetro Irp para cada una de las opciones de socket admitidas, consulte Opciones de socket WSK.

Si el parámetro RequestType se establece en WskIoctl, el parámetro Irp es obligatorio, es opcional o debe ser NULL en función de la operación de control de E/S determinada que se realiza. Para obtener más información sobre los requisitos del parámetro Irp para cada una de las operaciones de control de E/S admitidas, consulte Operaciones de IOCTL de socket de WSK.

Valor devuelto

WskControlSocket devuelve uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	La operación de control se completó correctamente. Si la aplicación WSK especificó un puntero a un IRP en el parámetro Irp , el IRP se completará con el estado correcto y el número de bytes devueltos en el búfer al que apunta el parámetro OutputBuffer se devolverá en el campo IoStatus.Information del IRP.
STATUS_PENDING	El subsistema WSK no pudo completar la operación de control inmediatamente. El subsistema WSK completará el IRP una vez que haya completado la operación de control. El estado de la operación de control se devolverá en el campo IoStatus.Status del IRP. Si la operación se realiza correctamente, el número de bytes devueltos en el búfer al que apunta el parámetro OutputBuffer se devolverá en el campo IoStatus.Information del IRP.
STATUS_EVENT_PENDING	El subsistema WSK no pudo completar la operación de control inmediatamente. Este valor solo se devuelve cuando una aplicación WSK deshabilita una función de devolución de llamada de eventos en un socket cuando hay llamadas actualmente en curso a esa función de devolución de llamada de eventos y cuando el parámetro Irp es NULL. Para obtener más información sobre cómo deshabilitar las funciones de devolución de llamada de eventos, consulte SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	El socket ya no es funcional. El IRP se completará con el estado de error. La aplicación WSK debe llamar a la función WskCloseSocket para cerrar el socket lo antes posible.
Otros códigos de estado	Se produjo un error. El IRP se completará con el estado de error.

Comentarios

Si una aplicación WSK especifica WskSetOption o WskGetOption en el parámetro RequestType , consulte Opciones de socket de WSK para obtener más información sobre cómo se usan los búferes de entrada y salida para cada opción de socket.

Si una aplicación WSK especifica WskIoctl en el parámetro RequestType , consulte Operaciones IOCTL de socket de WSK para obtener más información sobre cómo se usan los búferes de entrada y salida para cada operación de control de E/S.

Si la función WskControlSocket devuelve STATUS_PENDING, los búferes a los que apunta el parámetro InputBuffer o el parámetro OutputBuffer deben permanecer válidos hasta que se complete el IRP. Si la aplicación WSK asignó los búferes con una de las funciones ExAllocateXxx , no puede liberar la memoria con la función ExFreeXxx correspondiente hasta que se complete el IRP. Si la aplicación WSK asignó los búferes de la pila, no puede devolver desde la función que llama a la función WskControlSocket hasta después de que se complete el IRP.

Los autores de llamadas de la función WskControlSocket deben ejecutarse en IRQL <= DISPATCH_LEVEL excepto cuando el parámetro RequestType está establecido en WskIoctl y el parámetro ControlCode se establece en SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE o SIO_ADDRESS_LIST_SORT. En esta situación, los autores de llamadas deben ejecutarse en IRQL = PASSIVE_LEVEL.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de los sistemas operativos Windows.
Plataforma de destino	Universal
Encabezado	wsk.h (incluya Wsk.h)
IRQL	<= DISPATCH_LEVEL (consulte la sección Comentarios)