Функция TdhQueryProviderFieldInformation (tdh.h)
Извлекает сведения для указанного поля из описаний событий для тех значений полей, которые соответствуют заданному значению.
Синтаксис
TDHSTATUS TdhQueryProviderFieldInformation(
[in] LPGUID pGuid,
[in] ULONGLONG EventFieldValue,
[in] EVENT_FIELD_TYPE EventFieldType,
[out] PPROVIDER_FIELD_INFOARRAY pBuffer,
[in, out] ULONG *pBufferSize
);
Параметры
[in] pGuid
GUID, идентифицирующий поставщика, данные которого требуется получить.
[in] EventFieldValue
Получение сведений о поле, если значение поля совпадает с этим значением. Если тип поля является ключевое слово, сведения извлекаются для каждого события, ключевое слово бита, содержащегося в маске.
[in] EventFieldType
Укажите тип поля, для которого требуется получить сведения. Возможные значения см. в перечислении EVENT_FIELD_TYPE .
[out] pBuffer
Выделенный пользователем буфер для получения сведений о поле. Дополнительные сведения см. в разделе структура PROVIDER_FIELD_INFOARRAY .
[in, out] pBufferSize
Размер буфера pBuffer (в байтах). Если функция выполняется успешно, этот параметр получает размер используемого буфера. Если буфер слишком мал, функция возвращает ERROR_INSUFFICIENT_BUFFER и задает для этого параметра требуемый размер буфера. Если размер буфера равен нулю при входных данных, данные в буфере не возвращаются, и этот параметр получает требуемый размер буфера.
Возвращаемое значение
В случае успешного выполнения возвращает ERROR_SUCCESS. В противном случае эта функция возвращает один из следующих кодов возврата в дополнение к другим.
| Код возврата | Описание |
|---|---|
|
Размер буфера pBuffer слишком мал. Используйте необходимый размер буфера, заданный в pBufferSize , чтобы выделить новый буфер. |
|
Запрошенный тип поля недопустим. |
|
Манифест или класс MOF не найден или не содержит сведений для запрошенного типа поля, или поле, значение которого соответствует заданному значению, не найдено. |
|
Один или несколько параметров недопустимы. |
|
Атрибут resourceFileName в манифесте содержит расположение двоичного файла поставщика. При регистрации манифеста расположение записывается в реестр. TDH не удалось найти двоичный файл на основе зарегистрированного расположения. |
Комментарии
Эта функция использует XML-манифест или класс WMI MOF для получения сведений.
Примеры
В следующем примере показано, как запрашивать сведения, содержащиеся в манифесте или классе MOF для запрошенного поля.
#include <windows.h>
#include <stdio.h>
#include <wmistr.h>
#include <evntrace.h>
#include <tdh.h>
#pragma comment(lib, "tdh.lib")
DWORD QueryFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType, ULONGLONG fieldValue);
// GUID of the provider whose metadata you want to enumerate.
EXTERN_C __declspec(selectany) const GUID ProviderGuid = {0xd8909c24, 0x5be9, 0x4502, {0x98, 0xca, 0xab, 0x7b, 0xdc, 0x24, 0x89, 0x9d}};
void wmain(void)
{
DWORD status = ERROR_SUCCESS;
// Retrieve channel information if the provider defines a channel
// whose value is 17. Returns one entry if the channel exists.
wprintf(L"Retrieve EventChannelInformation for channel value 17.\n");
status = QueryFieldInfo((LPGUID)&ProviderGuid, EventChannelInformation, 17);
if (ERROR_SUCCESS != status)
{
wprintf(L"Failed to retrieve EventChannelInformation (%lu).\n\n", status);
}
// Retrieve keyword information for keywords whose value is 2 or 8.
wprintf(L"Retrieve EventKeywordInformation for keywords 2 and 8.\n");
status = QueryFieldInfo((LPGUID)&ProviderGuid, EventKeywordInformation, 0xA);
if (ERROR_SUCCESS != status)
{
wprintf(L"Failed to retrieve EventKeywordInformation (%lu).\n\n", status);
}
}
// Prints the information associated with the specified field type.
DWORD QueryFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType, ULONGLONG fieldValue)
{
DWORD status = ERROR_SUCCESS;
PROVIDER_FIELD_INFOARRAY* penum = NULL;
DWORD bufferSize = 0;
// Retrieve the required buffer size. If the status is ERROR_INSUFFICIENT_BUFFER,
// use bufferSize to allocate the buffer.
status = TdhQueryProviderFieldInformation(pProvider, fieldValue, fieldType, penum, &bufferSize);
if (ERROR_INSUFFICIENT_BUFFER == status)
{
penum = (PROVIDER_FIELD_INFOARRAY*) malloc(bufferSize);
if (penum == NULL)
{
wprintf(L"Allocation failed (size=%lu).\n", bufferSize);
status = ERROR_OUTOFMEMORY;
goto cleanup;
}
// Retrieve the information for the field type and value.
status = TdhQueryProviderFieldInformation(pProvider, fieldValue, fieldType, penum, &bufferSize);
}
// The first call can fail with ERROR_NOT_FOUND if none of the provider's event
// descriptions contain the requested field type information.
if (ERROR_SUCCESS == status)
{
// Loop through the list of field information and print the field's name,
// description (if it exists), and value.
for (DWORD i = 0; i < penum->NumberOfElements; i++)
{
wprintf(L"Field name: %s\nDescription: %s\nValue: %I64u\n\n",
(PWCHAR)((PBYTE)(penum) + penum->FieldInfoArray[i].NameOffset),
(penum->FieldInfoArray[i].DescriptionOffset) ?
(PWCHAR)((PBYTE)(penum) + penum->FieldInfoArray[i].DescriptionOffset): L"",
penum->FieldInfoArray[i].Value);
}
}
else
{
if (ERROR_NOT_FOUND == status)
{
wprintf(L"Requested field type not found.\n");
}
else
{
wprintf(L"TdhQueryProviderFieldInformation failed with %lu.\n", status);
}
goto cleanup;
}
cleanup:
if (penum)
{
free(penum);
penum = NULL;
}
return status;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | tdh.h |
| Библиотека | Tdh.lib |
| DLL | Tdh.dll |