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

Статья
08/28/2023

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

Синтаксис

LPWSPCONNECT Lpwspconnect;

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

Параметры

[in] s

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

[in] name

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

[in] namelen

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

[in] lpCallerData

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

[out] lpCalleeData

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

[in] lpSQOS

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

[in] lpGQOS

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

[out] lpErrno

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

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

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

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

Код ошибки	Значение
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAEADDRINUSE	Локальный адрес сокета уже используется, и сокет не помечен, чтобы разрешить повторное использование адреса с SO_REUSEADDR. Эта ошибка обычно возникает во время привязки, но может быть отложена до выполнения этой функции, если привязка была к частичному адресу с подстановочными знаками (с ADDR_ANY) и если во время выполнения этой функции необходимо зафиксировать определенный адрес.
WSAEINTR	(Блокирующий) вызов был отменен через LPWSPCancelBlockingCall.
WSAEINPROGRESS	Выполняется блокировка вызова Winsock или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEALREADY	Неблокировка вызова LPWSPConnect выполняется в указанном сокете. Чтобы сохранить обратную совместимость, эта ошибка сообщается как WSAEINVAL приложениям Windows Sockets 1.1, которые связываются с Winsock.dll или Wsock32.dll.
WSAEADDRNOTAVAIL	Удаленный адрес не является допустимым адресом (например, ADDR_ANY).
WSAEAFNOSUPPORT	Адреса из заданного семейства адресов не могут использоваться с этим сокетом.
WSAECONNREFUSED	Попытка подключения отклонена.
WSAEFAULT	Имя или параметр namelen не является допустимой частью адресного пространства пользователя, параметр namelen слишком мал, длина буфера для lpCalleeData, lpSQOS и lpGQOS слишком мала, или длина буфера для lpCallerData слишком велика.
WSAEINVAL	Параметр s является сокетом прослушивания.
WSAEISCONN	Сокет уже подключен (только для сокетов, ориентированных на подключение).
WSAENETUNREACH	В настоящее время сеть недоступна с этого узла.
WSAENOBUFS	Нет свободного места в буфере. Не удается подключить сокет.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Спецификации потока, указанные в lpSQOS , не могут быть удовлетворены.
WSAEPROTONOSUPPORT	Дополнение lpCallerData не поддерживается поставщиком услуг.
WSAETIMEDOUT	Время ожидания попытки подключения истекло без установления соединения.
WSAEWOULDBLOCK	Сокет помечается как неблокируемый, и подключение не может быть завершено немедленно. Можно выбрать сокет с помощью функции LPWSPSelect во время подключения с помощью функции WSPSelect, чтобы выбрать его для записи.
WSAEACCES	Не удалось подключить сокет датаграммы к широковещательным адресам, так как WSPSetSockOpt SO_BROADCAST не включен.

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

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

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

Для сокета без подключения (например, тип SOCK_DGRAM) операция, выполняемая LPWSPConnect , заключается в том, чтобы установить адрес назначения по умолчанию, чтобы сокет можно было использовать с последующими операциями отправки и получения, ориентированными на подключение (LPWSPSend, LPWSPRecv). Все датаграммы, полученные с адреса, отличного от указанного адреса назначения, будут удалены. Если адресный элемент структуры имен содержит все нули, сокет будет отключен. Удаленный адрес по умолчанию будет неопределенным, поэтому вызовы LPWSPSend и LPWSPRecv возвращают код ошибки WSAENOTCONN. Однако по-прежнему можно использовать LPWSPSendTo и LPWSPRecvFrom . Назначение по умолчанию можно изменить, просто повторно вызвав LPWSPConnect , даже если сокет уже подключен. Все датаграммы, помещенные в очередь для получения, удаляются, если имя отличается от имени предыдущего LPWSPConnect.

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

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

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

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

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

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхняя часть	ws2spi.h