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

Artículo
08/08/2023

La función WskSocket crea un nuevo socket y devuelve un puntero al objeto de socket asociado.

Sintaxis

PFN_WSK_SOCKET PfnWskSocket;

NTSTATUS PfnWskSocket(
  [in]           PWSK_CLIENT Client,
  [in]           ADDRESS_FAMILY AddressFamily,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const VOID *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 de WSK_CLIENT que se devolvió a través del parámetro WskProviderNpi del Función WskCaptureProviderNPI .

[in] AddressFamily

Familia de direcciones para el socket que se está creando. Para obtener más información sobre las familias de direcciones admitidas, consulte Familias de direcciones de WSK.

[in] SocketType

Tipo de socket que se está creando. 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 confianza.

SOCK_RAW

Admite el acceso sin procesar al protocolo de transporte.

Para obtener más información sobre los tipos de socket que se admiten para cada familia de direcciones admitidas, consulte
Familias de direcciones de WSK.

[in] Protocol

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

[in] Flags

Marca que especifica la categoría de socket WSK para el socket que se va a crear. Este parámetro puede ser una de las siguientes marcas:

WSK_FLAG_BASIC_SOCKET

Se creará un socket básico que solo se puede usar para obtener y establecer opciones de socket de pila de transporte o para realizar operaciones de control de E/S de socket.

WSK_FLAG_LISTEN_SOCKET

Se creará un socket de escucha que se puede usar para escuchar las conexiones entrantes desde direcciones de transporte remotas.

WSK_FLAG_DATAGRAM_SOCKET

Se creará un socket de datagrama que se puede usar para enviar y recibir datagramas.

WSK_FLAG_CONNECTION_SOCKET

Se creará un socket orientado a la conexión que se puede usar para enviar y recibir datos de red a través de una conexión.

WSK_FLAG_STREAM_SOCKET

Se creará un socket de flujo que se puede usar para escuchar las conexiones entrantes desde direcciones de transporte remotas, o enviar y recibir datos de red a través de una conexión.

Si una aplicación WSK no especifica ninguna de las marcas anteriores, WskSocket crea un socket básico.

[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 habilitará ninguna función de devolución de llamada de eventos en el nuevo socket, debe establecer este puntero en NULL. Para un socket básico, este puntero siempre debe ser NULL.

[in, optional] Dispatch

Puntero a una estructura de distribución de cliente constante. 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. Dependiendo de la categoría de socket WSK del socket (según lo especificado por el parámetro Flags ), este parámetro es un puntero a una de las siguientes estructuras.

Marca	Estructura de tabla de distribución
WSK_FLAG_LISTEN_SOCKET	WSK_CLIENT_LISTEN_DISPATCH
WSK_FLAG_DATAGRAM_SOCKET	WSK_CLIENT_DATAGRAM_DISPATCH
WSK_FLAG_CONNECTION_SOCKET	WSK_CLIENT_CONNECTION_DISPATCH
WSK_FLAG_STREAM_SOCKET	WSK_CLIENT_STREAM_DISPATCH

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 habilitará ninguna función de devolución de llamada de eventos en el nuevo socket, debe establecer el puntero Dispatch en NULL. Para un socket básico, este puntero siempre debe ser 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 de WSK_CACHE_SD . Para especificar un descriptor de seguridad predeterminado que no permita 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

WskSocket 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 de WSK_TRANSPORT que contiene todas las combinaciones válidas de los parámetros AddressFamily, SocketType y Protocol .

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