queryAllTracesA 函数 (evntrace.h)

QueryAllTraces 函数检索调用方有权查询的所有事件跟踪会话的属性和统计信息。

语法

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

参数

[out] PropertyArray

指向 EVENT_TRACE_PROPERTIES 结构的指针数组，这些结构接收事件跟踪会话的会话属性和统计信息。

只需设置 EVENT_TRACE_PROPERTIES 结构的 Wnode.BufferSize、LoggerNameOffset 和 LogFileNameOffset 成员。 其他成员应全部设置为零。

[in] PropertyArrayCount

PropertyArray 数组中的结构数。 此值必须小于或等于 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 函数并将 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(WCHAR)) +
    (MAX_LOGFILE_PATH_LEN * sizeof(WCHAR));

int wmain()
{
    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(WCHAR));
            }

            status = QueryAllTracesW(&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: %ls\n"
                    "Log file: %ls\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,
                    (PCWSTR)((LPCBYTE)sessions[i] + sessions[i]->LoggerNameOffset),
                    (PCWSTR)((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 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	evntrace.h
Library	Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.lib;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.lib
DLL	Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.dll

请参阅

ControlTrace

EVENT_TRACE_PROPERTIES

EnumerateTraceGuids