Функция WSAJoinLeaf (winsock2.h)
Функция WSAJoinLeaf объединяет конечный узел в сеанс с несколькими точками, обменивается данными подключения и задает необходимое качество обслуживания на основе указанных структур FLOWSPEC .
Синтаксис
SOCKET WSAAPI WSAJoinLeaf(
[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
);
Параметры
[in] s
Дескриптор, определяющий сокет с несколькими точками.
[in] name
Имя однорангового узла, с которым должен быть присоединен сокет.
[in] namelen
Длина имени в байтах.
[in] lpCallerData
Указатель на пользовательские данные, которые должны быть переданы одноранговой точке во время установки сеанса с несколькими точками.
[out] lpCalleeData
Указатель на пользовательские данные, которые должны быть переданы обратно из однорангового узла во время создания сеанса с несколькими точками.
[in] lpSQOS
Указатель на структуры FLOWSPEC для сокетов, по одному для каждого направления.
[in] lpGQOS
Зарезервировано для будущего использования с группами сокетов. Указатель на структуры FLOWSPEC для группы сокетов (если применимо).
[in] dwFlags
Флаги, указывающие, что сокет выступает в качестве отправителя (JL_SENDER_ONLY), получателя (JL_RECEIVER_ONLY) или обоих (JL_BOTH).
Возвращаемое значение
Если ошибка не возникает, WSAJoinLeaf возвращает значение типа SOCKET, которое является дескриптором для созданного многоточечного сокета. В противном случае возвращается значение INVALID_SOCKET, а определенный код ошибки можно получить, вызвав WSAGetLastError.
В блокирующем сокете возвращаемое значение указывает на успешное или неудачное выполнение операции соединения.
При неблокировке сокета успешный запуск операции соединения обозначается возвратом допустимого дескриптора сокета. Впоследствии после успешного завершения операции соединения в исходном сокете будет указано FD_CONNECT. Приложение должно использовать WSAsyncSelect или WSAEventSelect с интересом, зарегистрированным для события FD_CONNECT, чтобы определить, когда операция соединения завершена, и проверить связанный код ошибки, чтобы определить успешность или сбой операции. Функция select не может использоваться для определения завершения операции соединения.
Кроме того, пока попытка присоединения к сеансу с несколькими точками не завершится, все последующие вызовы WSAJoinLeaf в том же сокете завершатся ошибкой с кодом WSAEALREADY. После успешного завершения операции WSAJoinLeaf последующая попытка обычно завершается ошибкой с кодом WSAEISCONN. Исключение из правила WSAEISCONN возникает для сокета c_root, разрешающего соединения, инициированные корнем. В этом случае после завершения предыдущей операции WSAJoinLeaf может быть инициировано другое соединение.
Если код ошибки возврата указывает на сбой попытки присоединения к сеансу с несколькими точками (то есть WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), приложение может снова вызвать WSAJoinLeaf для того же сокета.
| Код ошибки | Значение |
|---|---|
| Перед использованием этой функции должен быть выполнен успешный вызов WSAStartup . | |
| Локальный адрес сокета уже используется, и сокет не помечен, чтобы разрешить повторное использование адреса с SO_REUSEADDR. Эта ошибка обычно возникает во время привязки, но может быть отложена до выполнения этой функции, если привязка была к частичному адресу с подстановочными знаками (с ADDR_ANY) и если во время выполнения этой функции необходимо зафиксировать определенный адрес. | |
| Удаленный адрес не является допустимым (например, ADDR_ANY). | |
| Адреса из заданного семейства адресов не могут использоваться с этим сокетом. | |
| В указанном сокете выполняется неблокировка вызова WSAJoinLeaf . | |
| Попытка присоединиться была решительно отклонена. | |
| Имя или параметр namelen не являются допустимой частью адресного пространства пользователя, параметр namelen слишком мал, длина буфера для lpCalleeData, lpSQOS и lpGQOS слишком мала, или длина буфера для lpCallerData слишком велика. | |
| Вызов функции WSAJoinLeaf был выполнен в сокете UDP, который был открыт без установки флага WSA_FLAG_MULTIPOINT_C_LEAF или WSA_FLAG_MULTIPOINT_D_LEAF многоточия. | |
| Сокет уже является членом сеанса с несколькими точками. | |
| Блокирующий вызов сокета Windows 1.1 был отменен через WSACancelBlockingCall. | |
| Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова. | |
| Произошел сбой сетевой подсистемы. | |
| В настоящее время сеть недоступна с этого узла. | |
| Нет свободного места в буфере. Сокет не может быть присоединен. | |
| Дескриптор не является сокетом. | |
| Структуры FLOWSPEC, указанные в lpSQOS и lpGQOS , не могут быть удовлетворены. | |
| Расширение lpCallerData не поддерживается поставщиком услуг. | |
| Время ожидания попытки присоединения истекло без создания сеанса с несколькими точками. |
Комментарии
Функция WSAJoinLeaf используется для присоединения конечного узла к сеансу с несколькими точками, а также для выполнения ряда других вспомогательных операций, выполняемых во время присоединения сеанса. Если сокеты не связаны, система присваивает локальной связи уникальные значения, а сокет помечается как привязанный.
Функция WSAJoinLeaf имеет те же параметры и семантику, что и WSAConnect , за исключением того, что она возвращает дескриптор сокета (как в WSAAccept) и имеет дополнительный параметр dwFlags . Для входных параметров в этой функции можно использовать только многоточечные сокеты, созданные с помощью WSASocket с соответствующими многоточечными флагами. Возвращенный дескриптор сокета не будет использоваться до завершения операции соединения. Например, если сокет находится в неблокируемом режиме после получения соответствующего FD_CONNECT указание от WSAsyncSelect или WSAEventSelect в исходных сокетах, за исключением того, что в этом новом дескрипторе сокета может быть вызвана closesocket для отмены ожидающей операции соединения. Корневое приложение в сеансе с несколькими точками может вызывать WSAJoinLeaf один или несколько раз, чтобы добавить несколько конечных узлов, однако не более одного запроса на подключение с несколькими точками может быть невыполненным одновременно. Дополнительные сведения см. в статье Многоточие и семантика многоадресной рассылки .
Для неблокировки сокетов часто невозможно завершить подключение немедленно. В таком случае эта функция возвращает еще неиспользуемый дескриптор сокета, и операция продолжается. В этом случае отсутствует код ошибки , например WSAEWOULDBLOCK , так как функция фактически вернула признак успешного запуска. Когда окончательный результат успешного или неудачного результата становится известным, о нем можно сообщить с помощью WSAsyncSelect или WSAEventSelect в зависимости от того, как клиент регистрирует уведомления в исходных сокетах. В любом случае уведомление объявляется с FD_CONNECT, а код ошибки, связанный с FD_CONNECT указывает на успех или конкретную причину сбоя. Функция select не может использоваться для обнаружения уведомлений о завершении для WSAJoinLeaf.
Дескриптор сокета, возвращаемый WSAJoinLeaf , отличается в зависимости от того, является ли дескриптор входного сокета c_root или c_leaf. При использовании с сокетом c_root параметр name обозначает конкретный конечный узел для добавления, а возвращенный дескриптор сокета является сокетом c_leaf, соответствующим только что добавленному конечному узлу. Созданный сокет имеет те же свойства, что и , включая асинхронные события, зарегистрированные с помощью WSAsyncSelect или WSAEventSelect. Он не предназначен для обмена многоточечными данными, а для получения признаков сетевых событий (например, FD_CLOSE) для подключения к определенному c_leaf. Некоторые реализации с несколькими точками также позволяют использовать этот сокет для боковых чатов между корнем и отдельным конечным узлом. Для этого сокета будет получено FD_CLOSE, если соответствующий конечный узел вызывает closesocket для выхода из сеанса с несколькими точками. Симметрично вызов closesocket в сокете c_leaf, возвращенном из WSAJoinLeaf , приведет к тому, что сокет в соответствующем конечном узле получит уведомление о FD_CLOSE.
При вызове WSAJoinLeaf с c_leaf сокетом параметр name содержит адрес корневого приложения (для схемы управления с корнем) или существующего многоточечного сеанса (схема некорневого управления), а возвращаемый дескриптор сокета совпадает с дескриптором входного сокета. Иными словами, новый дескриптор сокета не выделяется. В схеме управления с корнем корневое приложение помещает свой c_root сокет в режим прослушивания путем вызова прослушивания. Стандартное уведомление FD_ACCEPT будет доставлено, когда конечный узел запросит присоединение к сеансу с несколькими точками. Корневое приложение использует обычные функции accept или WSAAccept для допуска нового конечного узла. Значение, возвращаемое методом accept или WSAAccept , также является дескриптором сокета c_leaf, как и значение, возвращенное wSAJoinLeaf. Для поддержки многоточечных схем, которые позволяют выполнять соединения, инициированные корнем и конечным элементом, допустимо использовать c_root сокет, который уже находится в режиме прослушивания, в качестве входных данных для WSAJoinLeaf.
Приложение отвечает за выделение любого пространства памяти, на которое прямо или косвенно указывает любой из указанных параметров.
lpCallerData — это параметр значения, содержащий все пользовательские данные, которые должны быть отправлены вместе с запросом на присоединение к сеансу с несколькими точками. Если lpCallerData имеет значение NULL, пользовательские данные не будут передаваться в одноранговый узел. lpCalleeData — это параметр результата, который будет содержать все пользовательские данные, передаваемые из однорангового узла в рамках создания сеанса с несколькими точками. Элемент len структуры WSABUF , на который указывает параметр lpCalleeData , изначально содержит длину буфера, выделенного приложением и на который указывает член buf структуры WSABUF . Элемент len структуры WSABUF , на который указывает параметр lpCalleeData , будет иметь значение 0, если данные пользователя не были переданы обратно. Сведения lpCalleeData будут действительными после завершения операции многоточечных соединений.
Для блокирующих сокетов это будет происходить при возврате функции WSAJoinLeaf . Для неблокируемых сокетов это будет происходить после завершения операции соединения. Например, это может произойти после FD_CONNECT уведомления в исходных сокетах). Если lpCalleeData имеет значение NULL, пользовательские данные не будут передаваться обратно. Точный формат пользовательских данных зависит от семейства адресов, к которому принадлежит сокет.
Во время создания сеанса с несколькими точками приложение может использовать параметры lpSQOS и (или) lpGQOS , чтобы переопределить любую предыдущую спецификацию качества обслуживания, созданную для сокета через WSAIoctl , с помощью SIO_SET_QOS или SIO_SET_GROUP_QOS кодов операций.
Параметр lpSQOS указывает структуры FLOWSPEC для сокетов, по одной для каждого направления, а затем любые дополнительные параметры, относящиеся к поставщику. Если связанный поставщик транспорта в целом или конкретный тип сокета, в частности, не может учитывать качество запроса на обслуживание, будет возвращена ошибка, как указано ниже. Соответствующие значения спецификации потока отправки или получения будут игнорироваться для любых однонаправленных сокетов. Если параметры, относящиеся к поставщику, не указаны, для элементов buf и len структуры WSABUF , на которые указывает параметр lpCalleeData , следует задать значение NULL и ноль соответственно. Значение NULL для lpSQOS указывает на отсутствие качества обслуживания, предоставляемого приложением.
Зарезервировано для будущих групп сокетов. Параметр lpGQOS указывает структуры FLOWSPEC для группы сокетов (если применимо), по одной для каждого направления, а затем любые дополнительные параметры, относящиеся к поставщику. Если параметры, относящиеся к поставщику, не указаны, для элементов buf и len структуры WSABUF , на которые указывает параметр lpCalleeData , должно быть задано значение NULL и ноль соответственно. Значение NULL для lpGQOS указывает на отсутствие качества обслуживания группы, предоставляемой приложением. Этот параметр будет игнорироваться, если s не является создателем группы сокетов.
Когда подключенные сокеты разрываются (то есть закрываются по какой-либо причине), они должны быть удалены и повторно созданы. Безопаснее предположить, что, когда все идет на нет по какой-либо причине в подключенном сокете, приложение должно удалить и повторно создать необходимые сокеты, чтобы вернуться к стабильной точке.
Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows на Windows 8.1, Windows Server 2012 R2 и более поздних версиях.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8.1, Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | winsock2.h |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по