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

Artículo
03/05/2024

La función WskAccept acepta una conexión entrante en un socket de escucha.

Sintaxis

PFN_WSK_ACCEPT PfnWskAccept;

NTSTATUS PfnWskAccept(
  [in]            PWSK_SOCKET ListenSocket,
                  ULONG Flags,
  [in, optional]  PVOID AcceptSocketContext,
  [in, optional]  const WSK_CLIENT_CONNECTION_DISPATCH *AcceptSocketDispatch,
  [out, optional] PSOCKADDR LocalAddress,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PIRP Irp
)
{...}

Parámetros

[in] ListenSocket

Puntero a una estructura de WSK_SOCKET que especifica el objeto de socket para el socket de escucha o secuencia que se está comprobando para una conexión entrante.

Flags

Este parámetro está reservado para uso del sistema. Una aplicación WSK debe establecer este parámetro en cero.

[in, optional] AcceptSocketContext

Puntero a un contexto proporcionado por el autor de la llamada para el socket que se acepta. El subsistema WSK pasa este puntero a las funciones de devolución de llamada de eventos del socket aceptado. La información de contexto es opaca para el subsistema WSK. La información de contexto debe almacenarse en memoria no paginada. Si la aplicación WSK no habilitará ninguna función de devolución de llamada de eventos en el socket aceptado, debe establecer este puntero en NULL.

[in, optional] AcceptSocketDispatch

Puntero a una constante WSK_CLIENT_CONNECTION_DISPATCH estructura. Esta estructura es una tabla de distribución que contiene punteros a las funciones de devolución de llamada de eventos para el socket aceptado. Si la aplicación WSK no habilitará todas las funciones de devolución de llamada de eventos para el socket aceptado, debe establecer los punteros de la tabla de distribución en NULL para esas funciones de devolución de llamada de eventos que no habilite. Si la aplicación WSK no habilitará ninguna función de devolución de llamada de eventos en el socket aceptado, debe establecer este puntero en NULL.

[out, optional] LocalAddress

Puntero a un búfer asignado por el autor de la llamada que recibe la dirección de transporte local en la que llegó la conexión entrante. El búfer debe encontrarse en memoria no paginada. El búfer también debe ser lo suficientemente grande como para contener el tipo de estructura SOCKADDR específico que corresponde a la familia de direcciones que la aplicación WSK especificó al crear el socket de escucha. Este puntero es opcional y puede ser NULL.

[out, optional] RemoteAddress

Puntero a un búfer asignado por el autor de la llamada que recibe la dirección de transporte remota desde la que se originó la conexión entrante. El búfer debe encontrarse en memoria no paginada. El búfer también debe ser lo suficientemente grande como para contener el tipo de estructura SOCKADDR específico que corresponde a la familia de direcciones que la aplicación WSK especificó al crear el socket de escucha. Este puntero es opcional y puede ser NULL.

[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 aceptación 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.

Valor devuelto

WskAccept devuelve uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	Se aceptó correctamente una conexión entrante. El IRP se completará con el estado correcto.
STATUS_PENDING	El SUBSISTEMA WSK ha puesto en cola el IRP, que está esperando una conexión entrante en el socket de escucha.
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

Una aplicación WSK puede llamar a la función WskAccept en un socket de escucha o un socket de flujo que anteriormente enlazaba a una dirección de transporte local llamando a la función WskBind .

El comportamiento de la función WskAccept depende de si una conexión entrante está esperando que se acepte en el socket de escucha:

Si ya ha llegado una conexión entrante en el socket de escucha y está esperando que se acepte, la función WskAccept devuelve STATUS_SUCCESS. En esta situación, el IRP se completa con el estado correcto y el campo IoStatus.Information del IRP contiene un puntero al objeto socket para el socket aceptado.
Si una conexión entrante no está esperando que se acepte en el socket de escucha, WskAccept devuelve STATUS_PENDING y el subsistema de WSK pone en cola el IRP hasta que se recibe una conexión entrante. Cuando se recibe una conexión entrante, el subsistema WSK completa de forma asincrónica el IRP con el estado correcto. En esta situación, el campo IoStatus.Information del IRP contiene un puntero al objeto socket para el socket aceptado.

Si la función de devolución de llamada de eventos WskAcceptEvent de una aplicación WSK está habilitada en un socket de escucha y la aplicación tiene una llamada pendiente a la función WskAccept en el mismo socket de escucha, entonces, cuando llega una conexión entrante, la llamada pendiente a WskAccept tiene prioridad sobre la función de devolución de llamada de eventos WskAcceptEvent . El subsistema WSK llama a la función de devolución de llamada de eventos WskAcceptEvent de la aplicación solo si no hay irP en cola de llamadas pendientes a WskAccept. Sin embargo, una aplicación WSK no debe suponer que el subsistema WSK no llamará a la función de devolución de llamada de eventos WskAcceptEvent de la aplicación para un socket de escucha que tenga una llamada pendiente a la función WskAccept . Las condiciones de carrera existen donde el subsistema WSK todavía podría llamar a la función de devolución de llamada de eventos WskAcceptEvent de la aplicación WSK para el socket. La única manera de que una aplicación WSK asegúrese de que el subsistema WSK no llamará a la función de devolución de llamada de eventos WskAcceptEvent de la aplicación para un socket de escucha es deshabilitar la función de devolución de llamada de eventos WskAcceptEvent de la aplicación en el socket.

Cuando la función WskAccept acepta correctamente una conexión entrante, todas las funciones de devolución de llamada de eventos en el socket aceptado están deshabilitadas de forma predeterminada. Para obtener más información sobre cómo habilitar cualquiera de las funciones de devolución de llamada de eventos del socket aceptado, consulte Habilitación y deshabilitación de funciones de devolución de llamada de eventos.

Si una aplicación WSK especifica un puntero distinto de NULL en el parámetro LocalAddress , en el parámetro RemoteAddress , o en ambos parámetros, y si WskAccept devuelve STATUS_PENDING, los búferes a los que apuntan esos parámetros 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 WskAccept hasta después de que se complete el IRP.

El subsistema WSK asigna la memoria para la estructura de objetos de socket ( WSK_SOCKET) para la conexión aceptada en nombre de la aplicación WSK. El subsistema WSK desasigna esta memoria cuando se cierra el socket.

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