Код элемента управления SIO_KEEPALIVE_VALS

Статья
06/12/2023

Описание

Код элемента управления SIO_KEEPALIVE_VALS включает или отключает параметр для каждого подключения параметра tcp keep-alive, который указывает время ожидания и интервал активности TCP.

Для выполнения этой операции вызовите функцию WSAIoctl или WSPIoctl со следующими параметрами.

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Параметры

s

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

dwIoControlCode

Код элемента управления для операции. Используйте SIO_KEEPALIVE_VALS для этой операции.

lpvInBuffer

Указатель на входной буфер. Этот параметр должен указывать на структуру tcp_keepalive .

cbInBuffer

Размер входного буфера в байтах. Этот параметр должен быть равен или больше размера структуры tcp_keepalive , на которую указывает параметр lpvInBuffer .

lpvOutBuffer

Указатель на выходной буфер. Этот параметр не используется для данной операции.

cbOutBuffer

Размер выходного буфера в байтах. Для этого параметра необходимо задать нулевое значение.

lpcbBytesReturned

Указатель на переменную, которая получает размер в байтах данных, хранящихся в выходном буфере. Этот возвращаемый параметр указывает на значение DWORD , равное нулю для данной операции, так как выходные данные отсутствуют.

lpvOverlapped

Указатель на структуру WSAOVERLAPPED .

Если сокеты были созданы без перекрываемого атрибута, параметр lpOverlapped игнорируется.

Если объект был открыт с перекрывающимся атрибутом, а параметр lpOverlapped не равен NULL, операция выполняется как перекрываемая (асинхронная) операция. В этом случае параметр lpOverlapped должен указывать на допустимую структуру WSAOVERLAPPED .

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

lpCompletionRoutine

Тип: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Указатель на подпрограмму завершения, вызываемую при завершении операции (игнорируется для неперекрывающихся сокетов).

lpThreadId

Указатель на структуру WSATHREADID , которая будет использоваться поставщиком в последующем вызове WPUQueueApc. Поставщик должен хранить указанную структуру WSATHREADID (не указатель на нее), пока не будет возвращена функция WPUQueueApc .

Примечание Этот параметр применяется только к функции WSPIoctl .

lpErrno

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

Примечание Этот параметр применяется только к функции WSPIoctl .

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

Если операция завершается успешно, функция WSAIoctl или WSPIoctl возвращает ноль.

Если операция завершается сбоем или находится в состоянии ожидания, функция WSAIoctl или WSPIoctl возвращает SOCKET_ERROR. Чтобы получить расширенные сведения об ошибке, вызовите WSAGetLastError.

Код ошибки	Значение
WSA_IO_PENDING	Перекрываемая операция была успешно инициирована, и ее завершение будет указано позже.
WSA_OPERATION_ABORTED	Перекрываемая операция была отменена из-за закрытия сокета или выполнения команды IOCTL SIO_FLUSH .
WSAEFAULT	Параметр lpOverlapped или lpCompletionRoutine не полностью содержится в допустимой части адресного пространства пользователя.
WSAEINPROGRESS	Функция вызывается при выполнении обратного вызова.
WSAEINTR	Блокирующая операция была прервана.
WSAEINVAL	Параметр dwIoControlCode не является допустимой командой, или указанный входной параметр недопустим, либо команда не применима к указанному типу сокета.
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAENOPROTOOPT	Параметр сокета не поддерживается в указанном протоколе. Эта ошибка возвращается для сокета датаграммы.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Указанная команда IOCTL не поддерживается. Эта ошибка возвращается, если поставщик транспорта не поддерживает SIO_KEEPALIVE_VALS IOCTL.

Код управления SIO_KEEPALIVE_VALS включает или отключает параметр для каждого подключения параметра tcp keep-alive, который указывает время ожидания и интервал ожидания активности TCP, используемые для пакетов проверки активности TCP. Дополнительные сведения о параметре поддержания активности см. в разделе 4.2.3.6 статьи Требования к узлам Интернета — уровни связи, указанные в RFC 1122, доступные на веб-сайте IETF. (Этот ресурс может быть доступен только на английском языке.)

Параметр lpvInBuffer должен указывать на структуру tcp_keepalive , определенную в файле заголовка Mstcpip.h . Эта структура определяется следующим образом:

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

Значение, указанное в элементе onoff , определяет, включена или отключена поддержка TCP. Если для элемента onoff задано ненулевое значение, включено сохранение активности TCP и используются другие члены структуры. Член keepalivetime указывает время ожидания (в миллисекундах) без действия до отправки первого пакета keep-alive. Член keepaliveinterval задает интервал в миллисекундах между отправкой последовательных пакетов проверки активности, если подтверждение не получено.

Параметр SO_KEEPALIVE , который является одним из SOL_SOCKET параметров сокета, также можно использовать для включения или отключения активности TCP при подключении, а также для запроса текущего состояния этого параметра. Чтобы запросить, включена ли поддержка TCP для сокета, можно вызвать функцию getsockopt с параметром SO_KEEPALIVE . Чтобы включить или отключить функцию проверки активности TCP, можно вызвать функцию setsockopt с параметром SO_KEEPALIVE . Если поддержка активности TCP включена с SO_KEEPALIVE, то параметры TCP по умолчанию используются для времени ожидания и интервала активности, если эти значения не были изменены с помощью SIO_KEEPALIVE_VALS.

Значение времени ожидания активности по умолчанию для всей системы можно контролировать с помощью параметра реестра KeepAliveTime , который принимает значение в миллисекундах. Если ключ не задан, время ожидания активности по умолчанию составляет 2 часа. Общесистемное значение интервала активности по умолчанию управляется с помощью параметра реестра KeepAliveInterval , который принимает значение в миллисекундах. Если ключ не задан, интервал активности по умолчанию составляет 1 секунду.

В Windows Vista и более поздних версиях количество проб проверки активности (повторных передач данных) равно 10 и не может быть изменено.

В Windows Server 2003, Windows XP и Windows 2000 значение по умолчанию для количества проб поддержания активности равно 5. Количество проб проверки активности можно контролировать с помощью параметров реестра TcpMaxDataRetransmissions и PPTPTcpMaxDataRetransmissions . Для количества проб проверки активности устанавливается большее из двух значений разделов реестра. Если это число равно 0, проверка активности не будет отправлена. Если это число превышает 255, оно корректируется до 255.