Functia EventWriteTransfer (evntprov.h) – aplicatii Win32

• 12/05/2018
• 3 minute de citit

In acest articol

Scrie un eveniment ETW cu un ID de activitate si un ID de activitate legat optional.

Sintaxa

ULONG EVNTAPI EventWriteTransfer (REGHANDLE RegHandle, PCEVENT_DESCRIPTOR EventDescriptor, LPCGUID ActivityId, LPCGUID RelatedActivityId, ULONG UserDataCount, PEVENT_DATA_DESCRIPTOR UserData);

Parametrii

RegHandle

Mana de inregistrare a furnizorului. Manerul provine de la EventRegister. Evenimentul generat va utiliza ProviderId asociat cu manerul.

EventDescriptor

EVENT_DESCRIPTOR cu informatii despre eveniment (metadate), inclusiv ID, versiune, nivel, cuvant cheie, canal, cod optional si activitate.

Important: ProviderId, Level si Keyword sunt mijloacele principale pentru filtrarea evenimentelor. Sunt posibile si alte tipuri de filtrare, dar au o cheltuiala mult mai mare. Alocati intotdeauna un nivel si un cuvant cheie diferit de zero fiecarui eveniment.

ActivityId

Un indicator optional catre un ID de activitate pe 128 de biti pentru acest eveniment. Daca acesta nu este NULL, EventWriteTransfer va utiliza valoarea specificata pentru ID-ul activitatii evenimentului. Daca acesta este NULL, EventWriteTransfer va utiliza ID-ul de activitate al firului curent.

Instrumentele de procesare a urmelor pot utiliza ID-ul activitatii evenimentului pentru a organiza evenimente in grupuri numite activitati. Pentru informatii suplimentare despre ID-ul activitatii, consultati EventActivityIdControl.

RelatedActivityId

Un indicator optional catre un ID de activitate pe 128 de biti care este parintele activitatii acestui eveniment. Daca acesta nu este NULL, EventWriteTransfer va utiliza valoarea specificata pentru ID-ul activitatii aferente evenimentului. Daca acesta este NULL, evenimentul nu va avea un ID de activitate asociat. ID-ul activitatii aferente este setat de obicei pe evenimentul START al activitatii (primul eveniment al activitatii, inregistrat cu Opcode = START).

Instrumentele de procesare a urmelor pot utiliza ID-ul activitatii aferente evenimentului pentru a determina relatia dintre activitati, de exemplu, activitatea legata este parintele activitatii nou-incepute. Pentru informatii suplimentare despre ID-ul activitatii corelate, consultati EventActivityIdControl.

UserDataCount

Numarul de structuri EVENT_DATA_DESCRIPTOR din UserData . Numarul maxim este 128.

Datele utilizatorului

O serie de structuri UserDataCount EVENT_DATA_DESCRIPTOR care descriu datele care trebuie incluse in eveniment. UserData poate fi NULL daca UserDataCount este zero.

Fiecare EVENT_DATA_DESCRIPTOR descrie un bloc de memorie care trebuie inclus in eveniment. Blocurile specificate vor fi concatenate in ordine, fara nicio umplere sau aliniere pentru a forma continutul evenimentului. Daca utilizati decodare bazata pe manifest, continutul evenimentului trebuie sa se potriveasca cu aspectul specificat in sablonul asociat evenimentului din manifest.

Valoare returnata

Returneaza ERROR_SUCCESS daca are succes sau un cod de eroare. Codurile de eroare posibile includ urmatoarele:

• ERROR_INVALID_PARAMETER : Unul sau mai multi parametri nu sunt valabili.
• ERROR_INVALID_HANDLE : manerul de inregistrare al furnizorului nu este valid.
• ERROR_ARITHMETIC_OVERFLOW : dimensiunea evenimentului este mai mare decat maximul permis (64KB – antet).
• ERROR_MORE_DATA : Dimensiunea bufferului sesiunii este prea mica pentru eveniment.
• ERROR_NOT_ENOUGH_MEMORY : Apare atunci cand tampoanele umplute incearca sa treaca pe disc, dar IO-urile de pe disc nu se intampla suficient de repede. Acest lucru se intampla atunci cand discul este lent si traficul de evenimente este intens. In cele din urma, nu mai exista tampoane gratuite (goale) si evenimentul este abandonat.
• STATUS_LOG_FILE_FULL : Fisierul de redare in timp real este plin. Evenimentele nu sunt inregistrate in sesiune pana cand un consumator in timp real nu consuma evenimentele din fisierul de redare.

Codul de eroare este destinat in principal utilizarii in scenarii de depanare si diagnostic. Majoritatea codului de productie ar trebui sa ruleze in continuare si sa raporteze in continuare evenimente chiar daca un eveniment ETW nu a putut fi scris, astfel incat versiunile de lansare ar trebui sa ignore, de obicei, codul de eroare.

Majoritatea furnizorilor de evenimente nu vor apela EventWriteTransfer direct. In schimb, majoritatea furnizorilor de evenimente sunt implementati utilizand un cadru ETW care incheie apelurile catre EventRegister , EventWriteTransfer si EventUnregister . De exemplu, puteti scrie un manifest de eveniment si apoi utilizati compilatorul de mesaje pentru a genera cod C / C ++ pentru evenimente sau puteti utiliza TraceLogging pentru a evita necesitatea unui manifest.

EventWriteTransfer va directiona evenimentul catre sesiunile de urmarire corespunzatoare pe baza ProviderId (determinat din RegHandle ), nivel, cuvant cheie si alte caracteristici ale evenimentului. Daca nicio sesiune de urmarire nu inregistreaza acest eveniment, aceasta functie nu va face nimic si va returna ERROR_SUCCESS .

Pentru a reduce impactul asupra performantei de evenimente care nu sunt inregistrate de orice sesiune de urmarire, puteti apela EventEnabled pentru a determina daca orice sesiune urma este inregistrarea evenimentului inainte de pregatirea datelor si apelarea EventWriteTransfer .

EventWriteTransfer este echivalent cu EventWriteEx cu 0 pentru Filter si 0 pentru Flags .

Cerinte

    Windows Vista client minim acceptat [aplicatii desktop | Aplicatii UWP] Server minim acceptat Windows Server 2008 [aplicatii desktop | Aplicatii UWP ] Platforma tinta Antet Windows evntprov.h Biblioteca Advapi32.lib DLL Advapi32.dll

Vezi si

EventActivityIdControl

EventRegister

EventWrite

EventWriteEx

Scrierea evenimentelor bazate pe manifest.