Функция SetPerTcpConnectionEStats (iphlpapi.h)

Статья
08/24/2023

Функция SetPerTcpConnectionEStats задает значение в сведениях для чтения и записи для tcp-подключения IPv4. Эта функция используется для включения или отключения расширенной статистики для подключения TCP IPv4.

Синтаксис

IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
  PMIB_TCPROW     Row,
  TCP_ESTATS_TYPE EstatsType,
  PUCHAR          Rw,
  ULONG           RwVersion,
  ULONG           RwSize,
  ULONG           Offset
);

Параметры

Row

Указатель на структуру MIB_TCPROW для tcp-подключения IPv4.

EstatsType

Тип расширенной статистики для задается TCP. Этот параметр определяет данные и формат сведений, ожидаемых в параметре Rw .

Этот параметр может быть одним из значений из типа перечисления TCP_ESTATS_TYPE , определенного в файле заголовка Tcpestats.h .

Rw

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

RwVersion

Версия устанавливаемых сведений для чтения и записи. Этот параметр должен иметь нулевое значение для Windows Vista, Windows Server 2008 и Windows 7.

RwSize

Размер (в байтах) буфера, на который указывает параметр Rw .

Offset

Смещение (в байтах) к члену в структуре, на который указывает устанавливаемый параметр Rw . Этот параметр в настоящее время не используется и должен иметь нулевое значение.

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

Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не выполняется в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени).
ERROR_INVALID_USER_BUFFER	Предоставленный буфер пользователя недопустим для запрошенной операции. Эта ошибка возвращается, если параметр Row является указателем NULL , а параметр RwSize не равен нулю.
ERROR_INVALID_PARAMETER	Неправильный параметр". Эта ошибка возвращается, если параметр Row является указателем NULL .
ERROR_NOT_FOUND	Эта запрошенная запись не найдена. Эта ошибка возвращается, если не удалось найти TCP-подключение, указанное в параметре Row .
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если для параметра RwVersion или Offset не задано значение 0.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Функция SetPerTcpConnectionEStats используется для включения или отключения расширенной статистики для tcp-подключения IPv4, переданного в параметре Row . Расширенная статистика по TCP-подключению отключена по умолчанию. Функция SetPerTcpConnectionEStats используется для задания значения элемента в сведениях для чтения и записи для расширенной статистики для tcp-подключения IPv4. Тип и формат задается с помощью параметра EstatsType . Параметр Rw содержит указатель на передаваемую структуру. Необходимо указать все элементы в структуре, на которую указывает параметр Rw .

В настоящее время поддерживается только нулевая версия статистики tcp-подключений. Поэтому для параметра RwVersion, передаваемого в SetPerTcpConnectionEStats , необходимо задать значение 0.

Структура, на которую указывает параметр Rw , переданный этой функции, зависит от значения перечисления, переданного в параметре EstatsType . В следующей таблице ниже указан тип структуры, который должен передаваться в параметре Rw для каждого возможного типа параметра EstatsType .

EstatsType	Структура, на которую указывает Rw
TcpConnectionEstatsData	TCP_ESTATS_DATA_RW_v0
TcpConnectionEstatsSndCong	TCP_ESTATS_SND_CONG_RW_v0
TcpConnectionEstatsPath	TCP_ESTATS_PATH_RW_v0
TcpConnectionEstatsSendBuff	TCP_ESTATS_SEND_BUFF_RW_v0
TcpConnectionEstatsRec	TCP_ESTATS_REC_RW_v0
TcpConnectionEstatsObsRec	TCP_ESTATS_OBS_REC_RW_v0
TcpConnectionEstatsBandwidth	TCP_ESTATS_BANDWIDTH_RW_v0
TcpConnectionEstatsFineRtt	TCP_ESTATS_FINE_RTT_RW_v0

Параметр Offset в настоящее время не используется и должен иметь значение 0. Все возможные структуры, на которые указывает параметр Rw , имеют один член, за исключением структуры TCP_ESTATS_BANDWIDTH_RW_v0 . Если для параметра EstatsType задано значение TcpConnectionEstatsBandwidth, структура TCP_ESTATS_BANDWIDTH_RW_v0 , на которую указывает параметр Rw , должна иметь оба элемента структуры, равные предпочтительным значениям в одном вызове функции SetPerTcpConnectionEStats .

Если параметр RwSize имеет значение 0, функция SetPerTcpConnectionEStats возвращает NO_ERROR и не вносит изменений в состояние расширенной статистики.

Функция GetTcpTable используется для получения таблицы tcp-подключений IPv4 на локальном компьютере. Эта функция возвращает структуру MIB_TCPTABLE , содержащую массив MIB_TCPROW записей. Параметр Row , передаваемый в функцию SetPerTcpConnectionEStats , должен быть записью для существующего tcp-подключения IPv4.

После включения расширенной статистики для TCP-подключения для IPv4 приложения вызывают функцию GetPerTcpConnectionEStats для получения расширенной статистики по TCP-подключению.

Функция GetPerTcpConnectionEStats предназначена для использования ПРОТОКОЛА TCP для диагностики проблем с производительностью как в сети, так и в приложении. Если сетевое приложение работает плохо, TCP может определить, находится ли узкое место в отправителе, получателе или самой сети. Если узкое место находится в сети, TCP может предоставить конкретные сведения о его природе.

Сведения о расширенной статистике TCP для подключения IPv6 см. в разделе Функции GetPerTcp6ConnectionEStats и SetPerTcp6ConnectionEStats .

Функция SetPerTcpConnectionEStats может вызываться только пользователем, вошедшего в систему как участник группы Администраторы. Если метод SetPerTcpConnectionEStats вызывается пользователем, не включаемым в группу Администраторы, вызов функции завершится ошибкой, и возвращается ERROR_ACCESS_DENIED . Эта функция также может завершиться сбоем из-за контроля учетных записей (UAC) в Windows Vista и Windows Server 2008. Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как участник группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении в Windows Vista или Windows Server 2008 отсутствует этот файл манифеста, пользователь, вошедший в систему как член группы администраторов, отличный от встроенного администратора, должен выполнять приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени) для успешного выполнения этой функции.

В версиях Windows до Windows 10 версии 1709 (Fall Creators Update) можно использовать SetPerTcpConnectionEStats для отключения и повторного включения статистики по подключению, что приводит к сбросу всех счетчиков статистики до нуля. Начиная с Windows 10 версии 1709 (Fall Creators Update) некоторые счетчики статистики не сбрасываются при отключении и повторном добавлении статистики. Кроме того, если два приложения отслеживают статистику для одного подключения, одно приложение может запутать другое, отключив статистику. По этим причинам рекомендуется, чтобы приложение не отключалось от статистики подключений. Чтобы обнаруживать изменения с течением времени, следует сохранить значения счетчиков, прочитанные при предыдущем вызове GetPerTcpConnectionEStats, и вычесть их из значений, считанных последующим вызовом.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll