Функция QueryAllTracesW (evntrace.h)

Статья
07/16/2024

Функция QueryAllTraces извлекает свойства и статистику для всех сеансов трассировки событий, для которых вызывающий объект имеет разрешения на запрос.

Синтаксис

ULONG WMIAPI QueryAllTracesW(
  [out] PEVENT_TRACE_PROPERTIES *PropertyArray,
  [in]  ULONG                   PropertyArrayCount,
  [out] PULONG                  LoggerCount
);

Параметры

[out] PropertyArray

Массив указателей на EVENT_TRACE_PROPERTIES структуры, получающие свойства сеанса и статистику для сеансов трассировки событий.

Необходимо задать только Wnode.BufferSize, LogerNameOffset и LogFileNameOffset членов структуры EVENT_TRACE_PROPERTIES. Остальные члены должны иметь значение нулю.

[in] PropertyArrayCount

Количество структур в массиве PropertyArra y. Это значение должно быть меньше или равно 64, максимальное количество сеансов трассировки событий, поддерживаемых ETW.

Windows 10:PropertyArrayCount может превышать 64, а некоторые системы могут поддерживать более 64 сеансов трассировки.

[out] LoggerCount

Фактическое количество сеансов трассировки событий, запущенных на компьютере.

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

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

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

ERROR_INVALID_PARAMETER

Одно из следующих значений:
- PropertyArrayCount равно нулю или больше максимального числа поддерживаемых сеансов
- PropertyArray имеет значение NULL
ERROR_MORE_DATA

Массив свойств слишком мал, чтобы получать сведения для всех сеансов (SessionCount больше PropertyArrayCount). Функция заполняет массив свойств числом структур свойств, указанными в PropertyArrayCount.

Замечания

Контроллеры трассировки событий вызывают эту функцию.

Эта функция извлекает сеансы трассировки, которые вызывающий имеет разрешения на запрос. Пользователи, работающие с повышенными правами администратора, пользователи группы пользователей журнала производительности и службы, работающие как LocalSystem, LocalService, NetworkService, могут просматривать все сеансы трассировки.

Эта функция не возвращает закрытые сеансы ведения журнала.

Чтобы получить сведения для одного сеанса, используйте функцию ControlTrace ControlTrace и задайте для параметра ControlCode значение EVENT_TRACE_CONTROL_QUERY.

Примеры

В следующем примере показано, как вызвать эту функцию.

#include <windows.h>
#include <evntrace.h>
#include <vector>

const unsigned MAX_SESSION_NAME_LEN = 1024;
const unsigned MAX_LOGFILE_PATH_LEN = 1024;
const unsigned PropertiesSize =
    sizeof(EVENT_TRACE_PROPERTIES) +
    (MAX_SESSION_NAME_LEN * sizeof(CHAR)) +
    (MAX_LOGFILE_PATH_LEN * sizeof(CHAR));

int main()
{
    ULONG status;
    std::vector<EVENT_TRACE_PROPERTIES*> sessions; // Array of pointers to property structures
    std::vector<BYTE> buffer;                      // Buffer that contains all the property structures
    ULONG sessionCount;                            // Actual number of sessions started on the computer

    // The size of the session name and log file name used by the
    // controllers are not known, therefore create a properties structure that allows
    // for the maximum size of both.

    try
    {
        sessionCount = 64; // Start with room for 64 sessions.
        do
        {
            sessions.resize(sessionCount);
            buffer.resize(PropertiesSize * sessionCount);

            for (size_t i = 0; i != sessions.size(); i += 1)
            {
                sessions[i] = (EVENT_TRACE_PROPERTIES*)&buffer[i * PropertiesSize];
                sessions[i]->Wnode.BufferSize = PropertiesSize;
                sessions[i]->LoggerNameOffset = sizeof(EVENT_TRACE_PROPERTIES);
                sessions[i]->LogFileNameOffset = sizeof(EVENT_TRACE_PROPERTIES) + (MAX_SESSION_NAME_LEN * sizeof(CHAR));
            }

            status = QueryAllTracesA(&sessions[0], sessionCount, &sessionCount);
        } while (status == ERROR_MORE_DATA);

        if (status != ERROR_SUCCESS)
        {
            printf("Error calling QueryAllTraces: %u\n", status);
        }
        else
        {
            printf("Actual session count: %u.\n\n", sessionCount);

            for (ULONG i = 0; i < sessionCount; i++)
            {
                WCHAR sessionGuid[50];
                (void)StringFromGUID2(sessions[i]->Wnode.Guid, sessionGuid, ARRAYSIZE(sessionGuid));

                printf(
                    "Session GUID: %ls\n"
                    "Session ID: %llu\n"
                    "Session name: %s\n"
                    "Log file: %s\n"
                    "min buffers: %u\n"
                    "max buffers: %u\n"
                    "buffers: %u\n"
                    "buffers written: %u\n"
                    "buffers lost: %u\n"
                    "events lost: %u\n"
                    "\n",
                    sessionGuid,
                    sessions[i]->Wnode.HistoricalContext,
                    (PCSTR)((LPCBYTE)sessions[i] + sessions[i]->LoggerNameOffset),
                    (PCSTR)((LPCBYTE)sessions[i] + sessions[i]->LogFileNameOffset),
                    sessions[i]->MinimumBuffers,
                    sessions[i]->MaximumBuffers,
                    sessions[i]->NumberOfBuffers,
                    sessions[i]->BuffersWritten,
                    sessions[i]->LogBuffersLost,
                    sessions[i]->EventsLost);
            }
        }
    }
    catch (std::bad_alloc const&)
    {
        printf("Error allocating memory for properties.\n");
        status = ERROR_OUTOFMEMORY;
    }

    return status;
}

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	evntrace.h
библиотеки	Sechost.lib в Windows 8.1 и Windows Server 2012 R2; Advapi32.lib в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP
DLL	Sechost.dll в Windows 8.1 и Windows Server 2012 R2; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP

См. также

ControlTrace

EVENT_TRACE_PROPERTIES

EnumerateTraceGuids

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