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

Статья
03/15/2023

Функция LPWSPAccept условно принимает соединение на основе возвращаемого значения функции условия.

Синтаксис

LPWSPACCEPT Lpwspaccept;

SOCKET Lpwspaccept(
  [in]      SOCKET s,
  [out]     sockaddr *addr,
  [in, out] LPINT addrlen,
  [in]      LPCONDITIONPROC lpfnCondition,
  [in]      DWORD_PTR dwCallbackData,
  [out]     LPINT lpErrno
)
{...}

Параметры

[in] s

Дескриптор, определяющий сокет, прослушивающий подключения после LPWSPListen.

[out] addr

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

[in, out] addrlen

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

[in] lpfnCondition

Адрес экземпляра процедуры функции необязательных условий, предоставляемой сокетами Windows. Эта функция используется в принятии или отклонении решения на основе информации вызывающего объекта, переданной в качестве параметров.

[in] dwCallbackData

Данные обратного вызова, передаваемые клиенту Windows Socket 2 в качестве значения параметра dwCallbackData функции условия. Этот параметр не интерпретируется поставщиком услуг.

[out] lpErrno

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

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

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

Код ошибки	Значение
WSAECONNREFUSED	Запрос на подключение был принудительно отклонен, как указано в возвращаемом значении функции условия (CF_REJECT).
WSAECONNRESET	Входящие подключения были указаны, но впоследствии были завершены удаленным одноранговым узлом перед принятием вызова.
WSAENETDOWN	Сбой сетевой подсистемы.
WSAEFAULT	Параметр addrlen слишком мал или параметр lpfnCondition не входит в адресное пространство пользователя.
WSAEINTR	Вызов (блокировка) был отменен через LPWSPCancelBlockingCall.
WSAEINPROGRESS	Выполняется блокировка вызова сокетов Windows.
WSAEINVAL	LPWSPListen не был вызван до LPWSPAccept, параметр g, указанный в функции условия, не является допустимым, возвращаемое значение функции условия не является допустимым или в любом случае, если указанный сокет находится в недопустимом состоянии.
WSAEMFILE	Очередь не является простой при входе в LPWSPAccept и нет дескрипторов сокетов.
WSAENOBUFS	Буферное пространство недоступно.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Ссылающийся сокет не является типом, поддерживающим службу, ориентированную на подключение.
WSATRY_AGAIN	Принятие запроса подключения было отложено, как указано в возвращаемом значении функции условия (CF_DEFER).
WSAEWOULDBLOCK	Сокет помечается как неблокировка и не принимается никаких подключений.
WSAEACCES	Предлагаемый запрос подключения истек или снят.

Замечания

Функция LPWSPAccept извлекает первое подключение в очереди ожидающих подключений всокета и проверяет его на соответствие функции условия, если указана функция условия (то есть не null). Функция условия должна выполняться в том же потоке, что и эта подпрограмма. Если функция условия возвращает CF_ACCEPT, LPWSPAccept создает новый сокет.

Только что созданные сокеты имеют те же свойства, что исокета , включая сетевые события, зарегистрированные в LPWSPAsyncSelect или с LPWSPEventSelect. Как описано в descriptorAllocation, когда выделены новые дескрипторы сокетов, поставщики IFS должны вызывать WPUModifyIFSHandle и поставщики, отличные от IFS, должны вызывать WPUCreateSocketHandle.

Если функция условия возвращает CF_REJECT, LPWSPAccept отклоняет запрос на подключение. Если решение о принятии или отклонении приложения не может быть принято немедленно, функция условия вернет CF_DEFER, чтобы указать, что решение не было принято. Никакие действия об этом запросе на подключение не должны приниматься поставщиком услуг. Когда приложение готово к выполнению действий по запросу подключения, оно вызовет LPWSPAccept снова и возвращает CF_ACCEPT или CF_REJECT в качестве возвращаемого значения из функции условия.

Для сокетов, находящихся в режиме блокировки (по умолчанию), если в очереди нет ожидающих подключений, LPWSPAccept блокирует вызывающий объект до тех пор, пока подключение не будет установлено. Для сокетов в режиме неблокировки, если эта функция вызывается при отсутствии ожидающих подключений в очереди, LPWSPAccept возвращает код ошибки WSAEWOULDBLOCK. Принятый сокет нельзя использовать для принятия дополнительных подключений. Исходный сокет остается открытым.

Параметр надстройки является результирующий параметр, заполненный адресом подключающейся сущности, как известно поставщику услуг. Точный формат параметра надстройки определяется семейством адресов, в котором происходит взаимодействие. addrlen является параметром результата значений; Изначально он будет содержать объем пространства, на который указывает надстройка. При возврате он должен содержать фактическую длину (в байтах) адреса, возвращаемого поставщиком услуг. Этот вызов используется с типами сокетов, ориентированными на подключение, например SOCK_STREAM. Если надстройки и/или addrlen равны null, то никакие сведения о удаленном адресе принятого сокета не возвращаются. В противном случае эти два параметра должны быть заполнены независимо от того, указана ли функция условия или что она возвращает.

Прототип функции условия выглядит следующим образом.

int CALLBACK 
ConditionFunc( 
  IN     LPWSABUF    lpCallerId, 
  IN     LPWSABUF    lpCallerData, 
  IN OUT LPQOS       lpSQOS, 
  IN OUT LPQOS       lpGQOS,
  IN     LPWSABUF    lpCalleeId, 
  IN     LPWSABUF    lpCalleeData, 
  OUT    GROUP FAR * g, 	
  IN     DWORD_PTR   dwCallbackData
);

lpCallerId и lpCallerData — это параметры значений, которые должны содержать адрес подключаемой сущности и все пользовательские данные, отправленные вместе с запросом подключения. Если нет идентификатора вызывающего или вызывающего объекта, соответствующий параметр будет иметь значение NULL. Многие сетевые протоколы не поддерживают данные абонента во время подключения. Большинство обычных сетевых протоколов могут поддерживать сведения об идентификаторе вызывающего абонента во время запроса подключения. буф часть WSABUF указывает на lpCallerId указывает на sockaddr. sockaddr интерпретируется в соответствии с его адресной семьей (как правило, путем приведения sockaddr к определенному типу, конкретному семейству адресов).

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

lpCalleeId — это параметр значения, содержащий локальный адрес подключенной сущности. буф часть WSABUF указывает на lpCalleeId указывает на sockaddr. sockaddr интерпретируется в соответствии с его адресной семьей (как правило, путем приведения sockaddr к определенному типу, конкретному семейству адресов).

lpCalleeData — это параметр результата, используемый функцией условия для предоставления пользовательских данных обратно в сущность подключения. Хранилище для этих данных должно предоставляться поставщиком услуг. lpCalleeData->len изначально содержит длину буфера, выделенного поставщиком услуг, и указывает на lpCalleeData->буф. Значение нуля означает, что передача пользовательских данных обратно вызывающей стороне не поддерживается. Функция условия будет копировать до lpCalleeData->len байт данных в lpCalleeData->buf, а затем обновить lpCalleeData->len, чтобы указать фактическое количество переданных байтов. Если пользовательские данные не передаются обратно вызывающей стороне, функция условия устанавливает lpCalleeData—>len равно нулю. Формат всех данных адреса и пользователя зависит от семейства адресов, к которому принадлежит сокет.

Значение параметра dwCallbackData, переданное функции условия, является значением, переданным в качестве параметра dwCallbackData в исходном вызове LPWSPAccept. Это значение интерпретируется только клиентом Windows Sockets 2. Это позволяет клиенту передавать некоторые сведения о контексте из LPWSPAccept через функцию условия, которая предоставляет функцию условия с дополнительными сведениями, необходимыми для определения того, следует ли принимать подключение. Обычное использование заключается в передаче указателя (подходящего приведения) в структуру данных, содержащую ссылки на определяемые приложением объекты, с которым связан этот сокет.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	ws2spi.h