Функция PdhParseInstanceNameW (pdh.h)

Статья
11/20/2024

Анализирует элементы строки экземпляра.

Синтаксис

PDH_FUNCTION PdhParseInstanceNameW(
  [in]      LPCWSTR szInstanceString,
  [out]     LPWSTR  szInstanceName,
  [in, out] LPDWORD pcchInstanceNameLength,
  [out]     LPWSTR  szParentName,
  [in, out] LPDWORD pcchParentNameLength,
  [out]     LPDWORD lpIndex
);

Параметры

[in] szInstanceString

строке null-terminated, указывающей строку экземпляра для синтаксического анализа отдельных компонентов. Эта строка может содержать следующие форматы и меньше MAX_PATH символов в длину:

пример
instance#index
parent/instance
parent/instance#index

[out] szInstanceName

Выделенный вызывающим буфером, который получает имя экземпляра null-terminated. Если pcchInstanceNameLength значение NULL равно нулю.

[in, out] pcchInstanceNameLength

Размер буфера szInstanceName в TCHARs. Если значение равно нулю входных данных, функция возвращает PDH_MORE_DATA и задает этот параметр требуемому размеру буфера. Если буфер больше требуемого размера, функция задает этот параметр фактическому размеру используемого буфера. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.

[out] szParentName

Выделенный вызывающим буфером, который получает null-завершенное имя родительского экземпляра, если он указан. Установите значение NULL, если pcchParentNameLength равно нулю.

[in, out] pcchParentNameLength

Размер буфера szParentName в TCHARs. Если значение равно нулю входных данных, функция возвращает PDH_MORE_DATA и задает этот параметр требуемому размеру буфера. Если буфер больше требуемого размера, функция задает этот параметр фактическому размеру используемого буфера. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.

[out] lpIndex

Значение индекса экземпляра. Если запись индекса отсутствует в строке, это значение равно нулю. Этот параметр может быть NULL.

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

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

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

Возвращаемый код	Описание
PDH_INVALID_ARGUMENT	Недопустимый параметр. Например, в некоторых выпусках можно получить эту ошибку, если указанный размер входных данных больше нуля, но меньше требуемого размера.
PDH_MORE_DATA	Один или оба буфера строки слишком малы, чтобы содержать данные. Это возвращаемое значение ожидается, если соответствующий буфер размера равен нулю входных данных. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.
PDH_INVALID_INSTANCE	Строка экземпляра неправильно отформатирована, превышает MAX_PATH символов длиной или не может быть проанализирована.

Замечания

Эта функция должна вызываться дважды, при первом получении требуемого размера буфера (присвойте буферам значение NULL и размеров буфера равным 0), а второй раз для получения данных.

Заметка

Заголовок pdh.h определяет PdhParseInstanceName как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	pdh.h
библиотеки	Pdh.lib
DLL	Pdh.dll

См. также

PdhMakeCounterPath

Поделиться через