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

Artículo
03/08/2023

La función WskSocketConnect crea un nuevo socket orientado a la conexión, lo enlaza a una dirección de transporte local, lo conecta a una dirección de transporte remota determinada y devuelve un puntero al objeto de socket asociado.

Sintaxis

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

Parámetros

[in] Client

Puntero a una estructura WSK_CLIENT que se devolvió a través del parámetro WskProviderNpi del Función WskCaptureProviderNPI .

[in] SocketType

Tipo del socket que se va a crear. Se admiten los siguientes tipos de socket:

SOCK_STREAM

Admite la comunicación de flujo de bytes orientada a la conexión confiable.

SOCK_DGRAM

Admite la comunicación de datagramas sin conexión no confiable.

SOCK_RAW

Admite el acceso sin procesar al protocolo de transporte.

Para obtener más información sobre los tipos de socket admitidos para cada familia de direcciones compatibles, consulte
WSK direcciona a las familias.

[in] Protocol

Protocolo de transporte para el socket que se está creando. Para obtener más información sobre los protocolos que se admiten para cada familia de direcciones compatibles, vea Familias de direcciones de WSK.

[in] LocalAddress

Puntero a una estructura que especifica la dirección de transporte local a la que se va a enlazar el socket. La aplicación WSK debe especificar un puntero al tipo de estructura SOCKADDR específico que corresponde a la familia de direcciones del socket que se está creando.

[in] RemoteAddress

Puntero a una estructura que especifica la dirección de transporte remota a la que se va a conectar el socket. La aplicación WSK debe especificar un puntero al tipo de estructura SOCKADDR específico que corresponde a la familia de direcciones del socket que se está creando.

Flags

Este parámetro está reservado para uso del sistema. Las aplicaciones WSK deben establecer este parámetro en cero.

[in, optional] SocketContext

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

[in, optional] Dispatch

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 nuevo socket. Si la aplicación WSK no habilitará todas las funciones de devolución de llamada de eventos para el nuevo socket, 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 va a habilitar ninguna función de devolución de llamada de eventos en el nuevo socket, debe establecer este puntero en NULL.

[in, optional] OwningProcess

Puntero al proceso desde el que el subsistema WSK recuperará el contexto de seguridad que se usará cuando enlaza el socket. El subsistema WSK usa el contexto de seguridad para determinar si la dirección de transporte local se puede compartir si esa dirección ya está en uso. Para especificar el proceso actual, una aplicación WSK establece este puntero en NULL.

[in, optional] OwningThread

Puntero a un subproceso específico desde el que el subsistema WSK recuperará el contexto de seguridad que se usará cuando enlaza el socket. El subsistema WSK usa el contexto de seguridad para determinar si la dirección de transporte local se puede compartir si esa dirección ya está en uso. Si una aplicación WSK no necesita especificar un subproceso específico, establece este puntero en NULL.

[in, optional] SecurityDescriptor

Puntero a una estructura de SECURITY_DESCRIPTOR que especifica el descriptor de seguridad que se va a aplicar al socket que se va a crear. El descriptor de seguridad controla el uso compartido de la dirección de transporte local a la que está enlazado el socket. Si una aplicación WSK especifica un puntero distinto de NULL , debe especificar un puntero a una copia almacenada en caché de un descriptor de seguridad que se obtuvo llamando a la función WskControlClient con el código de control WSK_CACHE_SD . Para especificar un descriptor de seguridad predeterminado que no permite el uso compartido de la dirección de transporte local, una aplicación WSK establece SecurityDescriptor en NULL.

Para obtener más información sobre la estructura de SECURITY_DESCRIPTOR, consulte la página de referencia de SECURITY_DESCRIPTOR en la documentación de Microsoft Windows SDK.

[in, out] Irp

Puntero a un IRP asignado por el autor de la llamada que usa el subsistema WSK para completar la creación del nuevo socket 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

WskSocketConnect devuelve uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	El nuevo socket se creó correctamente. El IRP se completará con el estado correcto.
STATUS_PENDING	El subsistema WSK no pudo crear el socket inmediatamente. El subsistema WSK completará el IRP una vez creado el nuevo socket. El estado de la creación del socket se devolverá en el campo IoStatus.Status del IRP.
Otros códigos de estado	Se produjo un error. El IRP se completará con el estado de error.

Comentarios

Si el IRP se completa con el estado correcto, el campo IoStatus.Information del IRP contiene un puntero a una estructura de objetos de socket ( WSK_SOCKET) para el nuevo socket.

Una aplicación WSK puede obtener una lista de protocolos de transporte disponibles llamando a la función WskControlClient con el código de control WSK_TRANSPORT_LIST_QUERY . WskControlClient devuelve una lista de estructuras WSK_TRANSPORT que contiene todas las combinaciones válidas de los parámetros SocketType y Protocol .

El subsistema WSK determina la familia de direcciones para el nuevo socket de la familia de direcciones especificada en la estructura SOCKADDR a la que apunta el parámetro LocalAddress .

Si la aplicación WSK necesita establecer una opción de socket o emitir una operación de control de E/S en el socket antes de enlazar o conectar el socket, la aplicación WSK debe llamar a las funciones WskSocket, WskBind y WskConnect en lugar de llamar a la función WskSocketConnect .

Cuando una aplicación WSK crea correctamente un nuevo socket, todas las funciones de devolución de llamada de eventos del nuevo socket se deshabilitan 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 nuevo socket, 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 para el parámetro SecurityDescriptor , no debe liberar el descriptor de seguridad almacenado en caché hasta que se complete el IRP.

El subsistema WSK asigna la memoria para la estructura de objetos de socket (WSK_SOCKET) para el nuevo socket 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