Manifesto Tabanlı Olaylar Yazma

İzleme oturumuna olay yazabilmeniz için önce sağlayıcınızı kaydetmeniz gerekir. Sağlayıcının kaydedilmesi ETW'ye sağlayıcınızın izleme oturumuna olay yazmaya hazır olduğunu bildirir. Bir işlem en fazla 1.024 sağlayıcı GUID'sini kaydedebilir; ancak, işleminizin kaydettiğiniz sağlayıcı sayısını bir veya iki ile sınırlamanız gerekir.

Windows Vista'nın öncesinde: İşlemin kaydedilebileceği sağlayıcı sayısıyla ilgili bir sınır yoktur.

Bildirim tabanlı bir sağlayıcıyı kaydetmek için EventRegister işlevini çağırın. İşlev, sağlayıcının GUID'sini kaydeder ve bir denetleyici sağlayıcıyı etkinleştirdiğinde veya devre dışı bıraktığında ETW'nin çağırmış olduğu isteğe bağlı bir geri çağırma tanımlar.

Sağlayıcıdan çıkmadan önce, sağlayıcının kaydını ETW'den kaldırmak için EventUnregister işlevini çağırın. EventRegister işlevi, EventUnregister işlevine geçirdiğiniz kayıt tutamacını döndürür.

Bildirim tabanlı sağlayıcılarının, bir oturum sağlayıcıyı etkinleştirdiğinde veya devre dışı bırakdığında bildirim almak için EnableCallback işlevi uygulaması gerekmez. Geri çağırma isteğe bağlıdır ve bilgilendirme amacıyla kullanılır; sağlayıcıyı kaydederken geri çağırmayı belirtmeniz veya uygulamanız gerekmez. Bildirim tabanlı bir sağlayıcı yalnızca olayları yazabilir ve ETW olayın bir izleme oturumuna kaydedilip kaydedilmeyeceğine karar verir. Bir olay, olayın verilerini oluşturmak için kapsamlı bir çalışma yapmanızı gerektiriyorsa, işe başlamadan önce olayın bir oturuma yazılacağını doğrulamak için önce EventEnabled veya EventProviderEnabled fonksiyonunu çağırmak isteyebilirsiniz.

Genellikle, sağlayıcınız denetleyicinin sağlayıcı tanımlı filtre verilerini sağlayıcıya iletmesini gerektiriyorsa (bkz. EnableCallbackfonksiyonundaki FilterData parametresi) veya sağlayıcı kendisini kaydederken belirttiği bağlam bilgilerini kullanıyorsa (bkz. EventRegisterfonksiyonundaki CallbackContext parametresi).

Bildirim tabanlı sağlayıcıları bir oturuma olay yazmak için eventWriteEventWrite veya EventWriteString işlevini çağırır. Olay verileriniz bir dizeyse veya sağlayıcınız için bir bildirim tanımlamazsanız ve olay verileriniz tek bir dizeyse, olayı yazmak için eventWriteStringişlevini çağırın. Sayısal veya karmaşık veri türleri içeren olay verileri için olayı günlüğe kaydetmek için EventWrite işlevini çağırın.

Aşağıdaki örnekte, EventWrite işlevi kullanılarak yazılacak olay verilerinin nasıl hazırlanacağı gösterilmektedir. Örnek, bildirim tabanlı sağlayıcı için Olay Şemanızı Yayımlamaiçinde tanımlanan olaylara başvurur.

#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 {
  LPCWSTR name;
  USHORT  value;
} NAMEDVALUE, *PNAMEDVALUE;

int 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};
    void* pImage = &Scores;
    DWORD TransferType = Upload;
    DWORD Day = MONDAY | TUESDAY;
    LPCWSTR 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(pImage));
    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);
    return 0;
}

Yukarıdaki örnekte kullanılan bildirimi derlediğinizde (bkz. Bir İzleme Bildirimi Derlemek), örnekte başvurulan aşağıdaki üst bilgi dosyasını oluşturur.

//**********************************************************************`
//* 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