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 (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
程式庫	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