Функция WSAConnect (winsock2.h)

Статья
08/27/2023

Функция WSAConnect устанавливает подключение к другому приложению сокета, обменивается данными подключения и задает требуемое качество обслуживания на основе указанной структуры FLOWSPEC .

Синтаксис

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

Параметры

[in] s

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

[in] name

Указатель на структуру sockaddr , указывающую адрес, к которому нужно подключиться. Для IPv4 sockaddr содержит AF_INET для семейства адресов, IPv4-адреса назначения и порта назначения. Для IPv6 структура sockaddr содержит AF_INET6 для семейства адресов, IPv6-адреса назначения, порта назначения, а также может содержать дополнительные сведения о потоке и область идентификаторе.

[in] namelen

Длина структуры sockaddr в байтах, на которую указывает параметр name .

[in] lpCallerData

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

[out] lpCalleeData

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

[in] lpSQOS

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

[in] lpGQOS

Зарезервировано для дальнейшего использования с группами сокетов. Указатель на структуры FLOWSPEC для группы сокетов (если применимо). Этот параметр должен иметь значение NULL.

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

Если ошибка не возникает, WSAConnect возвращает ноль. В противном случае он возвращает SOCKET_ERROR, и конкретный код ошибки можно получить, вызвав WSAGetLastError. В блокирующем сокете возвращаемое значение указывает на успешное или неудачное завершение попытки подключения.

При использовании неблокированного сокета попытка подключения не может быть завершена немедленно. В этом случае WSAConnect возвращает SOCKET_ERROR, а WSAGetLastError возвращает WSAEWOULDBLOCK; таким образом, приложение может:

Используйте select , чтобы определить завершение запроса на подключение, проверив, доступен ли сокет для записи.
Если приложение использует WSAsyncSelect для указания интереса к событиям подключения, приложение получит FD_CONNECT уведомление, когда операция подключения будет завершена (успешно или нет).
Если приложение использует WSAEventSelect для указания интереса к событиям подключения, то связанный объект события будет сигнализировать о завершении операции подключения (успешной или нет).

Для неблокировочного сокета, пока попытка подключения не завершится, все последующие вызовы WSAConnect в том же сокете завершатся ошибкой с кодом WSAEALREADY.

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

Код ошибки	Значение
WSANOTINITIALISED	Перед использованием этой функции должен произойти успешный вызов WSAStartup .
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAEADDRINUSE	Локальный адрес сокета уже используется, и сокет не помечен, чтобы разрешить повторное использование адреса с SO_REUSEADDR. Эта ошибка обычно возникает во время выполнения привязки, но может быть отложена до выполнения этой функции, если функция привязки работает с частично подстановочными знаками (с ADDR_ANY) и если конкретный адрес необходимо "зафиксировать" во время выполнения этой функции.
WSAEINTR	Вызов сокета Windows 1.1 был отменен через WSACancelBlockingCall.
WSAEINPROGRESS	Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEALREADY	Для указанного сокета выполняется неблокировка подключения или вызова WSAConnect .
WSAEADDRNOTAVAIL	Удаленный адрес не является допустимым адресом (например, ADDR_ANY).
WSAEAFNOSUPPORT	Адреса из заданного семейства адресов не могут использоваться с этим сокетом.
WSAECONNREFUSED	Попытка подключения была отклонена.
WSAEFAULT	Параметр name или namelen не является допустимой частью адресного пространства пользователя, параметр namelen слишком мал, длина буфера для lpCalleeData, lpSQOS и lpGQOS слишком мала, либо длина буфера для lpCallerData слишком велика.
WSAEINVAL	Параметр s является прослушивающим сокетом, или указанный адрес назначения не согласуется с адресом ограниченной группы, к которой принадлежит сокет, или параметр lpGQOS не имеет значения NULL.
WSAEISCONN	Сокет уже подключен (только для сокетов, ориентированных на подключение).
WSAENETUNREACH	В настоящее время сеть недоступна с этого узла.
WSAEHOSTUNREACH	Сделана попытка выполнить операцию на сокете для недоступного хоста.
WSAENOBUFS	Нет свободного места в буфере. Не удается подключить сокет.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Структуры FLOWSPEC, указанные в lpSQOS и lpGQOS , не могут быть удовлетворены.
WSAEPROTONOSUPPORT	Параметр lpCallerData не поддерживается поставщиком услуг.
WSAETIMEDOUT	Истекло время ожидания попытки подключения без установления подключения.
WSAEWOULDBLOCK	Сокет помечается как неблокируемый, и подключение не может быть завершено немедленно.
WSAEACCES	Попытка подключения сокета датаграммы к широковещательным адресам завершилась сбоем, так как SO_BROADCAST setsockopt не включена.

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

Для приложений, предназначенных для Windows Vista и более поздних версий, рекомендуется использовать функцию WSAConnectByList или WSAConnectByName , которая значительно упрощает проектирование клиентских приложений.

Для сокетов, ориентированных на подключение (например, тип SOCK_STREAM), активное подключение инициируется к внешнему узлу с использованием имени (адрес в пространстве имен сокета; подробное описание см. в разделе привязка). После успешного завершения этого вызова сокет будет готов к отправке и получению данных. Если параметр address структуры имен равен нулю, WSAConnect вернет ошибку WSAEADDRNOTAVAIL. Любая попытка повторно подключить активное подключение завершится ошибкой с кодом WSAEISCONN.

Примечание Если открывается сокет, выполняется вызов setsockopt , а затем выполняется вызов sendto , Windows Sockets выполняет неявный вызов функции привязки .

Для неблокированных сокетов, ориентированных на подключение, часто не удается завершить подключение немедленно. В таких случаях эта функция возвращает ошибку WSAEWOULDBLOCK. Однако операция продолжается. Когда об успешном или неудачном результате становится известно, это может быть сообщено одним из нескольких способов в зависимости от того, как клиент регистрирует уведомление. Если клиент использует select, успешное выполнение отображается в наборе writefds , а сбой — в наборе exceptfds . Если клиент использует WSAsyncSelect или WSAEventSelect, уведомление будет объявлено с FD_CONNECT, а код ошибки, связанный с FD_CONNECT, указывает на успешное выполнение или конкретную причину сбоя.

Для сокета без подключения (например, тип SOCK_DGRAM) операция, выполняемая WSAConnect , заключается в том, чтобы установить адрес назначения по умолчанию, чтобы сокет можно было использовать в последующих операциях отправки и получения, ориентированных на подключение (send, WSASend, recv и WSARecv). Все датаграммы, полученные с адреса, отличного от указанного адреса назначения, будут удалены. Если вся структура имен равна нулям (а не только параметру address структуры имени), сокет будет отключен. Затем удаленный адрес по умолчанию будет неопределенным, поэтому вызовы send, WSASend, recv и WSARecv будут возвращать код ошибки WSAENOTCONN. Однако по-прежнему можно использовать sendto, WSASendTo, recvfrom и WSARecvFrom . Назначение по умолчанию можно изменить, просто повторно вызвав WSAConnect , даже если сокет уже подключен. Все датаграммы, помещенные в очередь для получения, удаляются, если имя отличается от имени предыдущего WSAConnect.

Для сокетов без подключения имя может указывать любой допустимый адрес, включая широковещательный адрес. Однако для подключения к широковещательным адресам для сокета должен быть включен SO_BROADCAST setsockopt . В противном случае WSAConnect завершится ошибкой с кодом WSAEACCES.

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

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

Параметр lpCallerData содержит указатель на все пользовательские данные, которые должны быть отправлены вместе с запросом на подключение (называемые данными подключения). Это дополнительные данные, а не в обычном потоке сетевых данных, которые отправляются с сетевыми запросами для установления подключения. Этот параметр используется устаревшими протоколами, такими как DECNet, OSI TP4 и другие.

Примечание Данные подключения не поддерживаются протоколом TCP/IP в Windows. Подключение данных поддерживается только в ATM (RAWWAN) через необработанный сокет.

Если lpCallerData имеет значение NULL, пользовательские данные не будут передаваться в одноранговый узел. lpCalleeData — это результирующий параметр, который будет содержать все пользовательские данные, передаваемые обратно из другого сокета в рамках установки подключения в структуре WSABUF. Элемент len структуры WSABUF , на который указывает параметр lpCalleeData , изначально содержит длину буфера, выделенного приложением для элемента buf структуры WSABUF . Элемент len структуры WSABUF , на который указывает параметр lpCalleeData , будет равен нулю, если пользовательские данные не были переданы обратно. Сведения lpCalleeData будут действительными после завершения операции подключения. Для блокирующих сокетов операция подключения завершается при возврате функции WSAConnect . Для неблокируемых сокетов завершение будет выполнено после уведомления о 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 не является создателем группы сокетов.

Когда подключенные сокеты закрываются по какой-либо причине, их следует отменить и повторно создать. Можно с уверенностью предположить, что, когда все идет не так по какой-либо причине в подключенном сокете, приложение должно отменить и повторно создать необходимые сокеты, чтобы вернуться к стабильной точке.

Примечание При выполнении блокирующего вызова Winsock, например WSAConnect, Winsock может потребоваться дождаться сетевого события, прежде чем вызов сможет завершиться. В этой ситуации Winsock выполняет оповещенное ожидание, которое может быть прервано асинхронным вызовом процедуры (APC), запланированным в том же потоке. Выполнение другого блокирующего вызова Winsock внутри APC, который прервал текущий блокирующий вызов Winsock в том же потоке, приведет к неопределенному поведению и никогда не должен выполняться клиентами Winsock.

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone Windows Phone 8 и более поздних версий.

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