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

Статья
08/24/2023

Функция GetPerTcpConnectionEStats извлекает расширенную статистику для подключения TCP IPv4.

Синтаксис

IPHLPAPI_DLL_LINKAGE ULONG GetPerTcpConnectionEStats(
        PMIB_TCPROW     Row,
        TCP_ESTATS_TYPE EstatsType,
  [out] PUCHAR          Rw,
        ULONG           RwVersion,
        ULONG           RwSize,
  [out] PUCHAR          Ros,
        ULONG           RosVersion,
        ULONG           RosSize,
  [out] PUCHAR          Rod,
        ULONG           RodVersion,
        ULONG           RodSize
);

Параметры

Row

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

EstatsType

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

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

Значение	Значение
TcpConnectionEstatsSynOpts	Это значение запрашивает сведения об обмене SYN для TCP-подключения. Для этого значения перечисления доступны только статические сведения только для чтения. Если параметр Ros не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Ros , должен содержать TCP_ESTATS_SYN_OPTS_ROS_v0 структуру.
TcpConnectionEstatsData	Это значение запрашивает расширенные сведения о передаче данных для TCP-подключения. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать TCP_ESTATS_DATA_RW_v0 структуру. Если для этого TCP-подключения была включена расширенная передача данных, параметр Rod не был равен NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_DATA_ROD_v0 структуру.
TcpConnectionEstatsSndCong	Это значение запрашивает перегрузку отправителя для TCP-подключения. Для этого значения перечисления доступны все три типа информации (статические данные только для чтения, динамические только для чтения и сведения для чтения и записи). Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать структуру TCP_ESTATS_SND_CONG_RW_v0 . Если параметр Ros не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Ros , должен содержать TCP_ESTATS_SND_CONG_ROS_v0 структуру. Если для этого TCP-подключения были включены сведения о перегрузке отправителя, параметр Rod не был равен NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_SND_CONG_ROD_v0 структуру.
TcpConnectionEstatsPath	Это значение запрашивает расширенные сведения об измерении пути для TCP-подключения. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать структуру TCP_ESTATS_PATH_RW_v0 . Если для этого TCP-подключения были включены расширенные сведения об измерении пути, параметр Rod не был равен NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_PATH_ROD_v0 структуру.
TcpConnectionEstatsSendBuff	Это значение запрашивает расширенные сведения о очереди вывода для TCP-подключения. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать структуру TCP_ESTATS_SEND_BUFF_RW_v0 . Если для этого tcp-подключения включена расширенная очередь вывода, параметр Rod не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_SEND_BUFF_ROD_v0 структуру.
TcpConnectionEstatsRec	Это значение запрашивает расширенные сведения о локальном приемнике для TCP-подключения. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать структуру TCP_ESTATS_REC_RW_v0 . Если для этого TCP-подключения были включены расширенные сведения о локальном приемнике, параметр Rod не был равен NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_REC_ROD_v0 структуру.
TcpConnectionEstatsObsRec	Это значение запрашивает расширенные сведения о удаленном приемнике для TCP-подключения. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция выполняется успешно, буфер, на который указывает параметр Rw , должен содержать TCP_ESTATS_OBS_REC_RW_v0 структуру. Если для этого TCP-подключения была включена расширенная информация удаленного приемника, параметр Rod не был равен NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_OBS_REC_ROD_v0 структуру.
TcpConnectionEstatsBandwidth	Это значение запрашивает статистику оценки пропускной способности для TCP-подключения по пропускной способности. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать TCP_ESTATS_BANDWIDTH_RW_v0 структуру. Если статистика оценки пропускной способности была включена для этого TCP-подключения, параметр Rod не был равен NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать структуру TCP_ESTATS_BANDWIDTH_ROD_v0 .
TcpConnectionEstatsFineRtt	Это значение запрашивает детализированную статистику оценки времени кругового пути (RTT) для TCP-подключения. Для этого значения перечисления доступны только динамические сведения только для чтения, а также сведения для чтения и записи. Если параметр Rw не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rw , должен содержать TCP_ESTATS_FINE_RTT_RW_v0 структуру. Если для этого TCP-соединения включена тонкая статистика оценки RTT, параметр Rod не имеет значения NULL и функция завершается успешно, буфер, на который указывает параметр Rod , должен содержать TCP_ESTATS_FINE_RTT_ROD_v0 структуру.

[out] Rw

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

RwVersion

Версия запрошенной информации для чтения и записи. Текущее поддерживаемое значение является нулевой версией.

RwSize

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

[out] Ros

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

RosVersion

Версия запрошенной статической информации только для чтения. Текущее поддерживаемое значение является нулевой версией.

RosSize

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

[out] Rod

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

RodVersion

Версия запрошенной динамической информации только для чтения. Текущее поддерживаемое значение является нулевой версией.

RodSize

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

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

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

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

Код возврата	Описание
ERROR_INSUFFICIENT_BUFFER	Буфер, передаваемый в функцию, слишком мал. Эта ошибка возвращается, если буфер, на который указывают параметры Rw, Ros или Rod , недостаточно велик для получения данных. Эта ошибка также возвращается, если один из указанных буферов, на который указывают параметры Rw, Ros или Rod , имеет значение NULL, но длина была указана в связанном объекте RwSize, RosSize или RodSize. Это значение ошибки возвращается в Windows Vista и Windows Server 2008.
ERROR_INVALID_PARAMETER	Неправильный параметр". Эта ошибка возвращается, если параметр Row является указателем NULL .
ERROR_INVALID_USER_BUFFER	Предоставленный буфер пользователя недопустим для запрошенной операции. Эта ошибка возвращается, если один из заданных буферов, на который указывают параметры Rw, Ros или Rod , имеет значение NULL, но длина была указана в связанном объекте RwSize, RosSize или RodSize. В результате эта ошибка возвращается при выполнении любого из следующих условий: Параметр Row является указателем NULL , а параметр RwSize — ненулевым. Параметр Ros является указателем NULL , а параметр RosSize — ненулевым. Параметр Rod является указателем NULL , а параметр RodSize — ненулевым. Это значение ошибки возвращается в Windows 7 и Windows Server 2008 R2.
ERROR_NOT_FOUND	Эта запрошенная запись не найдена. Эта ошибка возвращается, если не удалось найти TCP-подключение, указанное в параметре Row .
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если для параметра RwVersion, RosVersion или RodVersion не задано нулевое значение.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

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

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

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

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

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

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

Вызывающий объект GetPerTcpConnectionEStats должен проверка поле EnableCollection в возвращаемой структуре Rw, а если это не TRUE, то вызывающий объект должен игнорировать данные в структуре Ros и Rod. Если для EnableCollection задано значение FALSE, то данные, возвращаемые в Ros и Rod , не определены. Например, одно из условий, при которых это может произойти, — если вы используете GetPerTcpConnectionEStats для получения расширенной статистики для подключения TCP IPv4 и ранее вызывали SetPerTcpConnectionEStats , чтобы включить расширенную статистику. Если вызов SetPerTcpConnectionEStats завершается сбоем, последующие вызовы GetPerTcpConnectionEStats будут возвращать бессмысленные случайные данные, а не расширенную статистику TCP. Вы можете увидеть этот пример, выполнив приведенный ниже пример как от имени администратора, так и от имени обычного пользователя.

Примеры

Пример кода см. в разделе Примеры в разделе Функции GetPerTcp6ConnectionEStats .

Требования


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