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

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

Syntax

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
);

Parameters

[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

Указатель на структуру QOS для сокетов.

[in] lpGQOS

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

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

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

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

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

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

Замечания

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

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

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

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

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

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

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

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

Если 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 opcode.

Параметр lpSQOS указывает структуры FLOWSPEC для сокетов, по одному для каждого направления, а затем любые дополнительные параметры, относящиеся к поставщику. Если связанный поставщик транспорта в целом или конкретный тип сокета, в частности, не может учитывать качество запроса на обслуживание, то ошибка будет возвращена, как указано в следующем примере. Значения спецификации отправки или получения потоков будут игнорироваться соответственно для любых однонаправленных сокетов. Если параметры, относящиеся к поставщику, не заданы, то для элементов структуры WSABUF, на которую указывает параметр lpCalleeData, должно быть задано значение NULL и ноль соответственно. Значение NULL для параметра lpSQOS указывает, что качество обслуживания, предоставленное приложением, отсутствует.

Зарезервировано для дальнейшего использования с группами сокетов lpGQOS указывает структуры THREADPEC для группы сокетов (если применимо), по одному для каждого направления, за которым следует все дополнительные параметры, относящиеся к поставщику. Если параметры, относящиеся к поставщику, не заданы, то для элементов структуры WSABUF, на которую указывает параметр lpCalleeData, должно быть задано значение NULL и ноль соответственно. Значение NULL для lpGQOS указывает, что качество обслуживания группы, предоставленного приложением, отсутствует. Этот параметр будет игнорироваться, если s не является создателем группы сокетов.

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

Windows 8.1 и Windows Server 2012 R2: эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версиях.

Требования

См. также

WSASyncSelect

WSABUF

WSAConnect

ConnectEx

WSAConnectByList

WSAEventSelect

Функции Winsock

Справочник по Winsock

принимать

привязывать

connect

getsockname

getsockopt

select

розетка