撰寫以資訊清單為基礎的事件
您必須先註冊提供者，才能將事件寫入追蹤會話。 註冊提供者會告知 ETW 您的提供者已準備好將事件寫入追蹤會話。 進程最多可以註冊 1，024 個提供者 GUID;不過，您應該將進程註冊的提供者數目限制為一或兩個。
在 Windows Vista 之前： 進程可以註冊的提供者數目沒有限制。
若要註冊以資訊清單為基礎的提供者，請呼叫 EventRegister 函式。 函式會註冊提供者的 GUID，並在控制器啟用或停用提供者時識別 ETW 呼叫的選擇性回呼。
在提供者結束之前，請呼叫 EventUnregister 函式，從 ETW 移除提供者的註冊。 EventRegister函式會傳回您傳遞至EventUnregister函式的註冊控制碼。
資訊清單型 提供者不需要實作 EnableCallback 函式，即可在會話啟用或停用提供者時接收通知。 回呼是選擇性的，用於參考用途;註冊提供者時，您不需要指定或實作回呼。 以資訊清單為基礎的提供者可以直接寫入事件，ETW 會決定事件是否記錄到追蹤會話。 如果事件要求您執行廣泛的工作來產生事件的資料，建議您先呼叫EventEnabled 或 EventProviderEnabled函式，以確認事件在執行工作之前會寫入會話。
一般而言，如果您的提供者要求控制器傳遞提供者定義的篩選資料， (看到EnableCallback的FilterData參數) 給提供者，或者提供者會使用它註冊本身時所指定的內容資訊， (看到EventRegister) 的CallbackCoNtext參數。
以資訊清單為基礎的提供者會呼叫EventWrite 或 EventWriteString函式，以將事件寫入會話。 如果您的事件資料是字串，或您未定義提供者的資訊清單，而且事件資料是單一字串，請呼叫 EventWriteString 函式來寫入事件。 對於包含數值或複雜資料類型的事件資料，請呼叫 EventWrite 函式來記錄事件。
下列範例示範如何使用 EventWrite 函式準備要寫入的事件資料。 此範例會參考針對 資訊清單型提供者發佈事件架構中所定義的事件。
#include <windows.h>
#include <stdio.h>
#include <evntprov.h>
#include "provider.h" // Generated from manifest
#define SUNDAY 0X1
#define MONDAY 0X2
#define TUESDAY 0X4
#define WEDNESDAY 0X8
#define THURSDAY 0X10
#define FRIDAY 0X20
#define SATURDAY 0X40
enum TRANSFER_TYPE {
Download = 1,
Upload,
UploadReply
};
#define MAX_NAMEDVALUES 5 // Maximum array size
#define MAX_PAYLOAD_DESCRIPTORS 9 + (2 * MAX_NAMEDVALUES)
typedef struct _namedvalue {
LPWSTR name;
USHORT value;
} NAMEDVALUE, *PNAMEDVALUE;
void wmain(void)
{
DWORD status = ERROR_SUCCESS;
REGHANDLE RegistrationHandle = NULL;
EVENT_DATA_DESCRIPTOR Descriptors[MAX_PAYLOAD_DESCRIPTORS];
DWORD i = 0;
// Data to load into event descriptors
USHORT Scores[3] = {45, 63, 21};
ULONG pImage = (ULONG)&Scores;
DWORD TransferType = Upload;
DWORD Day = MONDAY | TUESDAY;
LPWSTR Path = L"c:\\path\\folder\\file.ext";
BYTE Cert[11] = {0x2, 0x4, 0x8, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x0, 0x1};
PBYTE Guid = (PBYTE) &ProviderGuid;
USHORT ArraySize = MAX_NAMEDVALUES;
BOOL IsLocal = TRUE;
NAMEDVALUE NamedValues[MAX_NAMEDVALUES] = {
{L"Bill", 1},
{L"Bob", 2},
{L"William", 3},
{L"Robert", 4},
{L"", 5}
};
status = EventRegister(
&ProviderGuid, // GUID that identifies the provider
NULL, // Callback not used
NULL, // Context noot used
&RegistrationHandle // Used when calling EventWrite and EventUnregister
);
if (ERROR_SUCCESS != status)
{
wprintf(L"EventRegister failed with %lu\n", status);
goto cleanup;
}
// Load the array of data descriptors for the TransferEvent event.
// Add the data to the array in the order of the <data> elements
// defined in the event's template.
EventDataDescCreate(&Descriptors[i++], &pImage, sizeof(ULONG));
EventDataDescCreate(&Descriptors[i++], Scores, sizeof(Scores));
EventDataDescCreate(&Descriptors[i++], Guid, sizeof(GUID));
EventDataDescCreate(&Descriptors[i++], Cert, sizeof(Cert));
EventDataDescCreate(&Descriptors[i++], &IsLocal, sizeof(BOOL));
EventDataDescCreate(&Descriptors[i++], Path, (ULONG)(wcslen(Path) + 1) * sizeof(WCHAR));
EventDataDescCreate(&Descriptors[i++], &ArraySize, sizeof(USHORT));
// If your event contains a structure, you should write each member
// of the structure separately. If the structure contained integral data types
// such as DWORDs and the data types were aligned on an 8-byte boundary, you
// could use the following call to write the structure, however, you are
// encouraged to write the members separately.
//
// EventDataDescCreate(&EvtData, struct, sizeof(struct));
//
// Because the array of structures in this example contains both strings
// and numbers, you must write each member of the structure separately.
for (int j = 0; j < MAX_NAMEDVALUES; j++)
{
EventDataDescCreate(&Descriptors[i++], NamedValues[j].name, (ULONG)(wcslen(NamedValues[j].name)+1) * sizeof(WCHAR) );
EventDataDescCreate(&Descriptors[i++], &(NamedValues[j].value), sizeof(USHORT) );
}
EventDataDescCreate(&Descriptors[i++], &Day, sizeof(DWORD));
EventDataDescCreate(&Descriptors[i++], &TransferType, sizeof(DWORD));
// Write the event. You do not have to verify if your provider is enabled before
// writing the event. ETW will write the event to any session that enabled
// the provider. If no session enabled the provider, the event is not
// written. If you need to perform extra work to write an event that you
// would not otherwise do, you may want to call the EventEnabled function
// before performing the extra work. The EventEnabled function tells you if a
// session has enabled your provider, so you know if you need to perform the
// extra work or not.
status = EventWrite(
RegistrationHandle, // From EventRegister
&TransferEvent, // EVENT_DESCRIPTOR generated from the manifest
(ULONG)MAX_PAYLOAD_DESCRIPTORS, // Size of the array of EVENT_DATA_DESCRIPTORs
&Descriptors[0] // Array of descriptors that contain the event data
);
if (status != ERROR_SUCCESS)
{
wprintf(L"EventWrite failed with 0x%x", status);
}
cleanup:
EventUnregister(RegistrationHandle);
}
當您編譯資訊清單 (請參閱編譯上述範例所使用的 檢測資訊清單) 時，它會建立上述範例中所參考的下列標頭檔 () 。
//**********************************************************************`
//* This is an include file generated by Message Compiler. *`
//* *`
//* Copyright (c) Microsoft Corporation. All Rights Reserved. *`
//**********************************************************************`
#pragma once
//+
// Provider Microsoft-Windows-ETWProvider Event Count 1
//+
EXTERN_C __declspec(selectany) const GUID ProviderGuid = {0xd8909c24, 0x5be9, 0x4502, {0x98, 0xca, 0xab, 0x7b, 0xdc, 0x24, 0x89, 0x9d}};
//
// Keyword
//
#define READ_KEYWORD 0x1
#define WRITE_KEYWORD 0x2
#define LOCAL_KEYWORD 0x4
#define REMOTE_KEYWORD 0x8
//
// Event Descriptors
//
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR TransferEvent = {0x1, 0x0, 0x0, 0x4, 0x0, 0x0, 0x5};
#define TransferEvent_value 0x1
#define MSG_Provider_Name 0x90000001L
#define MSG_Event_WhenToTransfer 0xB0000001L
#define MSG_Map_Download 0xD0000001L
#define MSG_Map_Upload 0xD0000002L
#define MSG_Map_UploadReply 0xD0000003L
#define MSG_Map_Sunday 0xF0000001L
#define MSG_Map_Monday 0xF0000002L
#define MSG_Map_Tuesday 0xF0000003L
#define MSG_Map_Wednesday 0xF0000004L
#define MSG_Map_Thursday 0xF0000005L
#define MSG_Map_Friday 0xF0000006L
#define MSG_Map_Saturday 0xF0000007L
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應