функция shutdown (winsock.h)

Статья
03/15/2023

Функция завершения работы отключает отправку или получение в сокете.

Синтаксис

int shutdown(
  [in] SOCKET s,
  [in] int    how
);

Параметры

[in] s

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

[in] how

Флаг, который описывает, какие типы операций больше не будут разрешены. Возможные значения для этого флага перечислены в файле заголовка Winsock2.h .

Значение	Значение
SD_RECEIVE 0	Завершение работы операций получения.
SD_SEND 1	Завершение операций отправки.
SD_BOTH 2	Завершите операции отправки и получения.

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

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

Код ошибки	Значение
WSAECONNABORTED	Виртуальное подключение разорвано из-за тайм-аута или иного сбоя. Приложение должно закрыть сокет, поскольку он больше не может использоваться. Эта ошибка применяется только к сокету, ориентированному на подключение.
WSAECONNRESET	Виртуальное подключение было сброшено удаленной стороной путем прерывания. Приложение должно закрыть сокет, поскольку он больше не может использоваться. Эта ошибка применяется только к сокету, ориентированному на подключение.
WSAEINPROGRESS	Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEINVAL	Параметр how недопустим или не согласуется с типом сокета. Например, SD_SEND используется с типом сокета UNI_RECV.
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOTCONN	Сокет не подключен. Эта ошибка применяется только к сокету, ориентированному на подключение.
WSAENOTSOCK	Примечание Дескриптор не является сокетом.
WSANOTINITIALISED	Перед использованием этой функции должен произойти успешный вызов WSAStartup .

Если параметр how SD_RECEIVE, последующие вызовы функции recv в сокете будут запрещены. Это не влияет на нижние уровни протокола. Для сокетов TCP, если в сокете по-прежнему есть данные в очереди, ожидающие получения, или данные поступают впоследствии, подключение сбрасывается, так как данные не могут быть доставлены пользователю. Для сокетов UDP входящие датаграммы принимаются и помещаются в очередь. Ни в каких случаях не создается пакет ошибки ICMP.

Если параметр how SD_SEND, последующие вызовы функции отправки запрещены. Для сокетов TCP fins будет отправляться после отправки всех данных и подтверждения получателем.

Настройка SD_BOTH отключает отправку и получение, как описано выше.

Функция завершения работы не закрывает сокет. Все ресурсы, подключенные к сокету, не будут освобождены до вызова closesocket .

Чтобы обеспечить отправку и получение всех данных в подключенном сокете перед закрытием, приложение должно использовать завершение работы , чтобы закрыть подключение перед вызовом closesocket. Один из методов ожидания уведомления о том, что удаленный конец отправил все свои данные и инициировал корректное отключение, использует функцию WSAEventSelect следующим образом:

Вызовите WSAEventSelect , чтобы зарегистрироваться для получения уведомления FD_CLOSE.
Вызовите завершение работы с помощью how=SD_SEND.
При получении FD_CLOSE вызовите recv или WSARecv , пока функция не завершится успешно и не укажет, что получено ноль байтов. Если возвращается SOCKET_ERROR, корректное отключение невозможно.
Вызовите closesocket.

Другой метод ожидания уведомления о том, что удаленный конец отправил все свои данные и инициировал корректное отключение, использует перекрывающиеся вызовы приема:

Вызовите завершение работы с помощью how=SD_SEND.
Вызовите recv или WSARecv , пока функция не завершится успешно и не укажет, что получено ноль байтов. Если возвращается SOCKET_ERROR, корректное отключение невозможно.
Вызовите closesocket.

Примечание Функция завершения работы не блокируется независимо от параметра SO_LINGER в сокете.

Дополнительные сведения см. в разделе Корректное завершение работы, параметры задержки и закрытие сокета.

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

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

Если приложение хочет повторно использовать сокет, необходимо вызвать функцию DisconnectEx с параметром dwFlags , для параметра TF_REUSE_SOCKET , чтобы закрыть подключение к сокету и подготовить дескриптор сокета для повторного использования. После завершения запроса DisconnectEx дескриптор сокета можно передать в функцию AcceptEx или ConnectEx .

Если приложению требуется повторно использовать сокет, функции TransmitFile или TransmitPackets можно вызвать с параметром dwFlags , заданным с TF_DISCONNECT и TF_REUSE_SOCKET отключиться после того, как все данные будут поставлены в очередь для передачи, и подготовить дескриптор сокета для повторного использования. После завершения запроса TransmitFile дескриптор сокета можно передать в вызов функции, ранее использовавшийся для установления соединения, например AcceptEx или ConnectEx. После завершения функции TransmitPackets дескриптор сокета можно передать в функцию AcceptEx .

Примечание Отключение на уровне сокета зависит от поведения базового транспорта. Например, сокет TCP может находиться в состоянии tcp-TIME_WAIT, что приводит к задержке вызова DisconnectEx, TransmitFile или TransmitPackets .

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

Примечания для банкомата

Существуют важные проблемы, связанные с разрывом подключения при использовании режима асинхронной передачи (ATM) и сокетов Windows 2. Дополнительные сведения об этих важных рекомендациях см. в разделе Заметки для ATM в разделе Примечания справочника по функции closesocket .

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	winsock.h (включая Winsock2.h, Webhost.h)
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll