Функция обратного вызова LPWSPJOINLEAF (ws2spi.h)

Статья
03/15/2023

Функция WSPJoinLeaf объединяет конечный узел в сеанс с несколькими точками, обменивается данными подключения и указывает необходимое качество обслуживания на основе предоставленных спецификаций потока.

Синтаксис

LPWSPJOINLEAF Lpwspjoinleaf;

SOCKET Lpwspjoinleaf(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [in]  LPWSABUF lpCallerData,
  [out] LPWSABUF lpCalleeData,
  [in]  LPQOS lpSQOS,
  [in]  LPQOS lpGQOS,
  [in]  DWORD dwFlags,
  [out] LPINT lpErrno
)
{...}

Параметры

[in] s

Дескриптор, определяющий сокет с несколькими точками.

[in] name

Имя однорангового узла, с которым должен быть присоединен сокет в структуре sockaddr .

[in] namelen

Длина имени в байтах.

[in] lpCallerData

Указатель на пользовательские данные, которые должны быть переданы одноранговой точке во время создания сеанса с несколькими точками.

[out] lpCalleeData

Указатель на пользовательские данные, которые должны быть переданы обратно из однорангового узла во время создания сеанса с несколькими точками.

[in] lpSQOS

Указатель на спецификации потока для сокетов, по одному для каждого направления.

[in] lpGQOS

Зарезервировано.

[in] dwFlags

Флаги, указывающие, что сокет выступает в качестве отправителя, получателя или и того, и другого.

[out] lpErrno

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

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

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

В блокирующем сокете возвращаемое значение указывает на успешное или неудачное выполнение операции соединения.

При использовании неблокировки сокета успешный запуск операции соединения обозначается возвращаемым значением допустимого дескриптора сокета. Затем FD_CONNECT указывает, когда операция соединения завершается успешно или иным образом. Код ошибки, связанный с FD_CONNECT, указывает на успешное или неудачное выполнение WSPJoinLeaf.

Кроме того, пока попытка присоединения к сеансу с несколькими точками не завершится, все последующие вызовы WSPJoinLeaf в том же сокете будут завершаться ошибкой с кодом WSAEALREADY. После успешного завершения WSPJoinLeaf последующая попытка обычно завершается ошибкой с кодом WSAEISCONN. Исключение из правила WSAEISCONN возникает для сокета c_root, который разрешает соединения, инициированные корнем. В этом случае после завершения предыдущего WSPJoinLeaf может быть инициировано еще одно соединение.

Если код ошибки возврата указывает, что попытка присоединения к сеансу с несколькими точками завершилась сбоем (то есть WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), клиент SPI Windows Sockets может снова вызвать WSPJoinLeaf для того же сокета.

Код ошибки	Значение
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAEADDRINUSE	Локальный адрес сокета уже используется, и сокет не помечен, чтобы разрешить повторное использование адреса с SO_REUSEADDR. Эта ошибка обычно возникает во время привязки, но может быть отложена до выполнения этой функции, если bind находилась на частично диком карта адресе (с ADDR_ANY) и если конкретный адрес необходимо "зафиксировать" во время выполнения этой функции.
WSAEINTR	Вызов (Блокирующий) был отменен через WSPCancelBlockingCall.
WSAEINPROGRESS	Выполняется блокировка вызова Windows Sockets или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEALREADY	Неблокировка вызова WSPJoinLeaf выполняется в указанном сокете.
WSAEADDRNOTAVAIL	Удаленный адрес не является допустимым адресом (например, ADDR_ANY).
WSAEAFNOSUPPORT	Адреса из заданного семейства адресов не могут использоваться с этим сокетом.
WSAECONNREFUSED	Попытка присоединиться была решительно отвергнута.
WSAEFAULT	Параметр name или namelen не является допустимой частью адресного пространства пользователя, параметр namelen слишком мал, длина буфера для lpCalleeData, lpSQOS и lpGQOS слишком мала, либо длина буфера для lpCallerData слишком велика.
WSAEISCONN	Сокет уже является членом сеанса с несколькими точками.
WSAENETUNREACH	В настоящее время сеть недоступна с этого узла.
WSAENOBUFS	Нет свободного места в буфере. Сокет не может быть соединен.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Спецификации потока, указанные в lpSQOS , не могут быть удовлетворены.
WSAEPROTONOSUPPORT	Дополнение lpCallerData не поддерживается поставщиком услуг.
WSAETIMEDOUT	Время ожидания попытки присоединения истекло без создания сеанса с несколькими точками.

Эта функция используется для присоединения конечного узла к сеансу с несколькими точками, а также для выполнения ряда других вспомогательных операций, выполняемых во время соединения сеанса. Если сокет, s, не привязан, система назначает уникальные значения локальной связи, а сокет помечается как привязанный.

WSPJoinLeaf имеет те же параметры и семантику, что и LPWSPConnect , за исключением того, что он возвращает дескриптор сокета (как в LPWSPAccept) и имеет дополнительный параметр dwFlags . Для входных параметров в этой функции можно использовать только многоточечные сокеты, созданные с помощью LPWSPSocket с соответствующими флагами нескольких точек. Если сокет находится в неблокируемом режиме, возвращаемый дескриптор сокета не будет использоваться до тех пор, пока не будет получено соответствующее FD_CONNECT указание на исходные сокеты , за исключением того, что для этого нового дескриптора сокета можно вызвать closesocket для отмены ожидающей операции соединения. Корневой узел в сеансе с несколькими точками может вызывать WSPJoinLeaf один или несколько раз, чтобы добавить несколько конечных узлов, однако не более одного запроса на многоточежное подключение одновременно. Дополнительные сведения см. в разделе Протокольная многоадресная рассылка и многоточеняя рассылка в SPI .

Для неблокировки сокетов часто невозможно завершить подключение немедленно. В таком случае эта функция возвращает еще неиспользуемый дескриптор сокета, и операция продолжается. В этом случае отсутствует код ошибки, такой как WSAEWOULDBLOCK , так как функция фактически вернула признак "успешного запуска". Когда окончательный результат успешного или неудачного результата становится известным, он может быть передан с помощью LPWSPAsyncSelect или LPWSPEventSelect в зависимости от того, как клиент регистрирует уведомления в исходных сокетах. В любом случае уведомление объявляется с FD_CONNECT, а код ошибки, связанный с FD_CONNECT, указывает на успешное выполнение или конкретную причину сбоя. Обратите внимание, что LPWSPSelect нельзя использовать для обнаружения уведомлений о завершении для WSPJoinLeaf.

Дескриптор сокета, возвращаемый WSPJoinLeaf , зависит от того, является ли дескриптор входного сокета c_root или c_leaf. При использовании с сокетом c_root параметр name определяет конкретный конечный узел для добавления, а возвращенный дескриптор сокета является сокетом c_leaf, соответствующим только что добавленному конечному узлу. (Как описано в разделе Выделение дескриптора, при выделении новых дескрипторов сокета поставщики IFS должны вызывать WPUModifyIFSHandle , а поставщики, отличные от IFS, должны вызывать WPUCreateSocketHandle. Вновь созданный сокет имеет те же свойства, что и , включая асинхронные события, зарегистрированные с помощью LPWSPAsyncSelect или LPWSPEventSelect. Он не предназначен для обмена многоточечными данными, а для получения указаний сетевых событий (например, FD_CLOSE) для подключения к определенной c_leaf. Некоторые реализации с несколькими точками также позволяют использовать этот сокет для "боковых чатов" между корнем и отдельным конечным узлом. Для этого сокета будет получено FD_CLOSE, если соответствующий конечный узел вызывает LPWSPCloseSocket для выхода из сеанса с несколькими точками. Симметрично вызов WSPCloseSocket для сокета c_leaf, возвращаемого из WSPJoinLeaf , приведет к тому, что сокет в соответствующем конечном узле получит уведомление FD_CLOSE.

При вызове WSPJoinLeaf с c_leaf сокетом параметр name содержит адрес корневого узла (для схемы управления с корнем) или существующего многоточечного сеанса (схема некорневого управления), а возвращаемый дескриптор сокета совпадает с дескриптором входного сокета. Иными словами, новый дескриптор сокета не выделяется. В схеме управления с корнем корневое приложение помещает свой c_root сокет в режим прослушивания, вызывая LPWSPListen. Стандартное уведомление FD_ACCEPT будет доставлено, когда конечный узел запросит присоединиться к сеансу с несколькими точками. Корневое приложение использует обычные функции LPWSPAccept для допуска нового конечного узла. Значение, возвращаемое WSPAccept , также является дескриптором сокета c_leaf, как и значение, возвращаемое WSPJoinLeaf. Для размещения многоточечных схем, которые допускают как соединения, инициированные корнем, так и инициируемыми конечными точками, допустимо использовать c_root сокет, который уже находится в режиме прослушивания, в качестве входных данных для WSPJoinLeaf.

Клиент SPI сокетов Windows отвечает за выделение пространства памяти, на которое прямо или косвенно указывает любой из параметров, на которые он указывает.

lpCallerData — это параметр значения, содержащий все пользовательские данные, которые должны быть отправлены вместе с запросом на присоединение к сеансу с несколькими точками. Если lpCallerData имеет значение NULL, пользовательские данные не будут передаваться в одноранговый узел. lpCalleeData — это параметр результата, который будет содержать все пользовательские данные, передаваемые из однорангового узла в рамках создания сеанса с несколькими точками. lpCalleeData-len> изначально содержит длину буфера, выделенного клиентом SPI сокетов Windows, на который указывает lpCalleeData-buf.> lpCalleeData-len> будет иметь значение 0, если данные пользователя не были переданы обратно. Сведения lpCalleeData будут действительными после завершения операции многоточечных соединений. Для блокирующих сокетов это будет происходить при возврате функции WSPJoinLeaf . Для неблокируемых сокетов это происходит после уведомления о FD_CONNECT в исходных сокетах. Если lpCalleeData имеет значение NULL, пользовательские данные не будут переданы обратно. Точный формат пользовательских данных зависит от семейства адресов, к которому принадлежит сокет, и (или) участвующих приложений.

Во время установки сеанса с несколькими точками клиент WINDOWS Sockets SPI может использовать параметры lpSQOS , чтобы переопределить предыдущую спецификацию QoS, созданную для сокета, с помощью LPWSPIoctl с помощью SIO_SET_QOS кода операции.

lpSQOS задает спецификации потока для сокетов, по одному для каждого направления, за которым следуют любые дополнительные параметры, зависящие от поставщика. Если связанный поставщик транспорта в целом или конкретный тип сокета, в частности, не может выполнить запрос QoS, будет возвращена ошибка, как указано ниже. Значения спецификации потока отправки или получения будут игнорироваться соответственно для всех однонаправленных сокетов. Если параметры, относящиеся к поставщику, не заданы, члены buf и lenlpSQOS-ProviderSpecific> должны иметь значение NULL и ноль соответственно. Значение NULL для lpSQOS указывает на отсутствие качества обслуживания, предоставляемого приложением.

Параметр dwFlags используется для указания того, будет ли сокет действовать только как отправитель (JL_SENDER_ONLY), только как получатель (JL_RECEIVER_ONLY) или оба (JL_BOTH).

**Примечание** Когда подключенные сокеты разрываются (то есть закрываются по какой-либо причине), они должны быть удалены и повторно созданы. Можно с уверенностью предположить, что если по какой-либо причине все идет на ошибку в подключенном сокете, клиент SPI windows Sockets должен отменить и повторно создать необходимые сокеты, чтобы вернуться к стабильной точке.

Требования


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