PFN_WSK_CONTROL_SOCKET función de devolución de llamada (wsk.h)
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 |
---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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) |
Consulte también
Operaciones de IOCTL de socket de WSK
WSK_PROVIDER_CONNECTION_DISPATCH WSK_PROVIDER_DATAGRAM_DISPATCH