Функция WPUCreateSocketHandle (ws2spi.h)

Статья
08/28/2023

Функция WPUCreateSocketHandle создает новый дескриптор сокета.

Синтаксис

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

Параметры

[in] dwCatalogEntryId

Дескриптор, определяющий поставщика вызывающей службы.

[in] dwContext

Значение контекста для связи с новым дескриптором сокета.

[out] lpErrno

Указатель на код ошибки.

Возвращаемое значение

Если ошибка не возникает, WPUCreateSocketHandle возвращает новый дескриптор сокета. В противном случае возвращается INVALID_SOCKET, и в lpErrno доступен определенный код ошибки.

Код ошибки	Значение
WSAENOBUFS	Недостаточно буферов для создания нового дескриптора сокета.

Функция WPUCreateSocketHandle создает новый дескриптор сокета для указанного поставщика. Дескрипторы, созданные WPUCreateSocketHandle , не отличаются от дескрипторов файловой системы. Это важно в двух отношениях. Во-первых, архитектура сокета Windows 2 выполняет перенаправление функций файловой системы ReadFile и WriteFile на функции LPWSPRecv и LPWSPSend этого поставщика услуг соответственно. Во-вторых, в операционных системах, поддерживающих порты завершения, архитектура Windows Sockets 2 поддерживает связывание порта завершения с дескриптором сокета и его использование для создания отчетов о завершении перекрывающихся операций ввода-вывода.

**Примечание** Механизм перенаправления ReadFile и WriteFile обязательно включает переход между пользователем и ядром для перехода к перенаправлению, а затем переход между ядрами и пользователем для получения [LPWSPRecv](nc-ws2spi-lpwsprecv.md) или [LPWSPSend](nc-ws2spi-lpwspsend.md). При возврате эти переходы отменяются в обратном порядке. Это может быть значительным снижением производительности. Любой поставщик услуг, использующий **WPUCreateSocketHandle** для создания дескрипторов сокета, не должен задавать XP1_IFS_HANDLES в своей структуре WSAProtocol_Info . Клиенты должны принимать отсутствие XP1_IFS_HANDLES в качестве рекомендаций, чтобы избежать использования **ReadFile** и **WriteFile**.

**Примечание** При использовании механизма порта завершения с дескрипторами сокетов, созданными с помощью **WPUCreateSocketHandle**, нет исключительных штрафов производительности. Поставщик услуг должен использовать WPUCompleteOverlappedRequest , чтобы объявить о завершении перекрывающихся операций ввода-вывода, которые могут включать порт завершения. Клиенты могут свободно использовать функции операционной системы для создания, связывания и использования порта завершения для уведомления о завершении (например, CreateIoCompletionPort, GetQueuedCompletionStatus, см. соответствующую документацию по операционной системе). Обратите внимание, что порты завершения не интегрированы с другими асинхронными механизмами уведомлений, предлагаемыми Windows Sockets 2. Это значит, что клиент может выполнять несколько операций ожидания, включающих несколько событий и обратных вызовов завершения, но нет предопределенного способа включения портов завершения с множественным ожиданием.

**Рекомендации по многоуровневой службе**

Эта процедура представляет особый интерес для поставщиков многоуровневых служб. Поставщик многоуровневых служб может использовать эту процедуру вместо WPUModifyIFSHandle для создания дескрипторов сокета, предоставляемых клиенту. Преимущество этой процедуры заключается в том, что все запросы ввода-вывода, включающие сокет, могут быть гарантированно проходить через этого поставщика услуг. Это верно, даже если клиент предполагает, что сокеты являются дескрипторами файловой системы, и вызывает функции файловой системы ReadFile и WriteFile (хотя за это предположение он будет платить штраф за производительность).

Гарантия того, что все операции ввода-вывода проходят через этот уровень, является обязательным требованием для слоев, которым необходимо обработать поток ввода-вывода до или после фактической операции ввода-вывода. Создание дескрипторов сокетов с помощью WPUCreateSocketHandle и указание соответствующей таблицы диспетчеризации интерфейса поставщика услуг во время WSPStartup гарантирует, что слой может участвовать в запуске каждой операции ввода-вывода. Когда клиент запрашивает перекрывающиеся операции ввода-вывода, этот уровень поставщика услуг обычно должен упорядочить, чтобы получить путь уведомления о завершении ввода-вывода.

Чтобы понять, почему это так, рассмотрим, что происходит, если клиент связывает порт завершения с дескриптором сокета для получения перекрывающихся уведомлений о завершении ввода-вывода. Порт связан с дескриптором сокета, предоставляемым этим слоем, а не с дескриптором сокета следующего слоя. Этот уровень не может определить, связан ли порт завершения или что это за порт. Когда этот слой вызывает операцию ввода-вывода следующего слоя, он использует дескриптор сокета следующего слоя. Дескриптор сокета следующего слоя не будет иметь то же самое сопоставление портов завершения. Уведомление об ожидаемом завершении клиента не будет выполнено без дополнительной помощи.

Обычно многоуровневый поставщик услуг отвечает за это, заменяя другую перекрывающуюся структуру ввода-вывода и разные перекрывающиеся параметры ввода-вывода при вызове операции ввода-вывода на следующем уровне. Замещающий перекрытие структуры ввода-вывода ссылается на хранимую перекрываемую структуру и параметры клиента. Вызов следующего слоя настраивает уведомление обратного вызова. Когда происходит уведомление обратного вызова, этот уровень выполняет любую требуемую постобработку, извлекает перекрывающиеся данные ввода-вывода, хранящиеся от имени клиента, отменяет замещающие структуры и пересылает клиенту соответствующее уведомление о завершении.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	ws2spi.h