Función WPUCreateSocketHandle (ws2spi.h)

Artículo
08/28/2023

La función WPUCreateSocketHandle crea un nuevo identificador de socket.

Sintaxis

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

Parámetros

[in] dwCatalogEntryId

Descriptor que identifica al proveedor de servicios de llamada.

[in] dwContext

Valor de contexto que se va a asociar al nuevo identificador de socket.

[out] lpErrno

Puntero al código de error.

Valor devuelto

Si no se produce ningún error, WPUCreateSocketHandle devuelve el nuevo identificador de socket. De lo contrario, devuelve INVALID_SOCKET y hay disponible un código de error específico en lpErrno.

Código de error	Significado
WSAENOBUFS	No hay suficientes búferes disponibles para crear el nuevo identificador de socket.

Observaciones

La función WPUCreateSocketHandle crea un nuevo identificador de socket para el proveedor especificado. Los identificadores creados por WPUCreateSocketHandle son indistinguibles de los identificadores del sistema de archivos verdaderos. Esto es significativo en dos aspectos. En primer lugar, la arquitectura de Windows Socket 2 se encarga de redirigir las funciones del sistema de archivos ReadFile y WriteFile a las funciones LPWSPRecv y LPWSPSend de este proveedor de servicios, respectivamente. En segundo lugar, en sistemas operativos que admiten puertos de finalización, la arquitectura de Windows Sockets 2 admite la asociación de un puerto de finalización con el identificador de socket y su uso para notificar la finalización de E/S superpuesta.

**Nota** El mecanismo para redirigir ReadFile y WriteFile implica necesariamente una transición de usuario a kernel para llegar al redirector, seguido de una transición de kernel a usuario para llegar a [LPWSPRecv](nc-ws2spi-lpwsprecv.md) o [LPWSPSend](nc-ws2spi-lpwspsend.md). A cambio, estas transiciones se revierten a la inversa. Esto puede ser una penalización significativa del rendimiento. Cualquier proveedor de servicios que use **WPUCreateSocketHandle** para crear sus identificadores de socket no debe establecer XP1_IFS_HANDLES en su estructura de WSAProtocol_Info . Los clientes deben tomar la ausencia de XP1_IFS_HANDLES como guía para evitar el uso de **ReadFile** y **WriteFile**.

**Nota** No hay ninguna penalización de rendimiento excepcional para usar el mecanismo de puerto de finalización con identificadores de socket creados con **WPUCreateSocketHandle**. Un proveedor de servicios debe usar WPUCompleteOverlappedRequest para anunciar la finalización de operaciones de E/S superpuestas que pueden implicar un puerto de finalización. Los clientes pueden usar libremente funciones del sistema operativo para crear, asociar y usar un puerto de finalización para la notificación de finalización (por ejemplo, CreateIoCompletionPort, GetQueuedCompletionStatus, consulte la documentación pertinente del sistema operativo para obtener más información). Tenga en cuenta que los puertos de finalización no están integrados con los otros mecanismos de notificación asincrónicos que ofrece Windows Sockets 2. Es decir, un cliente puede realizar una espera múltiple que incluya varios eventos y devoluciones de llamada de finalización, pero no hay ninguna manera predefinida de que la espera múltiple incluya puertos de finalización.

**Consideraciones del proveedor de servicios superpuestas**

Este procedimiento es de especial interés para los proveedores de servicios en capas. Un proveedor de servicios en capas puede usar este procedimiento, en lugar de WPUModifyIFSHandle para crear los identificadores de socket que expone a su cliente. La ventaja de usar este procedimiento es que se pueden garantizar todas las solicitudes de E/S que implican el socket para pasar por este proveedor de servicios. Esto es cierto incluso si el cliente supone que los sockets son controladores del sistema de archivos y llama a las funciones del sistema de archivos ReadFile y WriteFile (aunque pagaría una penalización de rendimiento por esta suposición).

La garantía de que todas las E/S pasan por esta capa es un requisito para las capas que necesitan procesar la secuencia de E/S antes o después de la operación de E/S real. La creación de identificadores de socket mediante WPUCreateSocketHandle y la especificación de una tabla de distribución de procedimientos de interfaz del proveedor de servicios adecuada en el momento de WSPStartup garantiza que la capa tenga la oportunidad de participar en iniciar cada operación de E/S. Cuando el cliente solicita operaciones de E/S superpuestas, este nivel de proveedor de servicios normalmente tendrá que organizarse para acceder también a la ruta de acceso de la notificación de finalización de E/S.

Para ver por qué esto es cierto, tenga en cuenta lo que sucede si el cliente asocia un puerto de finalización con el identificador de socket para la notificación de finalización de E/S superpuesta. El puerto está asociado al controlador de socket expuesto por esta capa, no al controlador de socket de la capa siguiente. No hay ninguna manera de que esta capa determine si se ha asociado un puerto de finalización o cuál es el puerto. Cuando esta capa llama a la operación de E/S de la capa siguiente, usa el identificador de socket de la capa siguiente. El controlador de socket de la capa siguiente no tendrá la misma asociación de puerto de finalización. La notificación de puerto de finalización esperada del cliente no se producirá sin ayuda adicional.

La forma habitual en que un proveedor de servicios en capas se encarga de esto es sustituir una estructura de E/S superpuesta diferente y distintos parámetros de E/S superpuestos al invocar una operación de E/S en la capa siguiente. La estructura de E/S superpuesta sustituida hace referencia a la estructura y los parámetros superpuestos almacenados del cliente. La invocación de la capa siguiente configura una notificación de devolución de llamada. Cuando se produce la notificación de devolución de llamada, esta capa realiza cualquier procesamiento posterior deseado, recupera la información de E/S superpuesta almacenada en nombre del cliente, descarta las estructuras de sustitución y reenvía una notificación de finalización adecuada al cliente.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2spi.h