Funzione RegisterTraceGuidsW (evntrace.h)
La funzione RegisterTraceGuids registra un provider di traccia eventi ETW classico (di tipo Windows 2000) e le classi di traccia evento usate per generare eventi. Questa funzione specifica anche la funzione di callback utilizzata dal sistema per abilitare e disabilitare la traccia dal provider.
questa funzione è obsoleta. Il nuovo codice deve usare EventRegister per registrare un provider di traccia eventi ETW (Crimson) di windows Vista .
Sintassi
ULONG WMIAPI RegisterTraceGuidsW(
[in] WMIDPREQUEST RequestAddress,
[in] PVOID RequestContext,
[in] LPCGUID ControlGuid,
[in] ULONG GuidCount,
[in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
[in] LPCWSTR MofImagePath,
[in] LPCWSTR MofResourceName,
[out] PTRACEHANDLE RegistrationHandle
);
Parametri
[in] RequestAddress
Puntatore a una funzione ControlCallback che riceve una notifica quando il provider è abilitato o disabilitato da una sessione di traccia eventi. La funzione EnableTrace attiva questo callback.
[in] RequestContext
Puntatore a un contesto facoltativo definito dal provider che ETW passa alla funzione specificata da RequestAddress.
[in] ControlGuid
Controllare il GUID (ID provider) del provider di registrazione.
[in] GuidCount
Numero di elementi nella matrice TraceGuidReg . Se TraceGuidReg è NULL, impostare questo parametro su 0.
[in, out] TraceGuidReg
Puntatore a una matrice di
TRACE_GUID_REGISTRATION strutture.
Ogni elemento identifica una categoria di eventi forniti dal provider.
All'input, il membro Guid di ogni struttura contiene un GUID della classe di traccia eventi assegnato dal provider di registrazione. Il GUID della classe identifica una categoria di eventi forniti dal provider. I provider usano lo stesso GUID di classe per impostare il membro Guid di EVENT_TRACE_HEADER quando si chiama la funzione TraceEvent per registrare l'evento.
Nell'output, il membro RegHandle riceve un handle per la registrazione GUID della classe dell'evento. Se il provider chiama la funzione TraceEventInstance , utilizzare il membro RegHandle di TRACE_GUID_REGISTRATION per impostare il membro RegHandle di EVENT_INSTANCE_HEADER.
Questo parametro può essere NULL se il provider chiama solo la funzione TraceEvent per registrare gli eventi. Se il provider chiama la funzione TraceEventInstance per registrare gli eventi, questo parametro non può essere NULL.
[in] MofImagePath
Questo parametro non è supportato. Impostare su NULL. È consigliabile usare Mofcomp.exe per registrare la risorsa MOF durante la configurazione dell'applicazione. Per altre informazioni, vedere Pubblicazione dello schema eventi.
Windows XP con SP1, Windows XP e Windows 2000: Puntatore a una stringa facoltativa che specifica il percorso del programma DLL o eseguibile che contiene la risorsa specificata da MofResourceName. Questo parametro può essere NULL se il provider di eventi e il consumer usano un altro meccanismo per condividere informazioni sulle classi di traccia evento utilizzate dal provider.
[in] MofResourceName
Questo parametro non è supportato. Impostare su NULL. È consigliabile usare Mofcomp.exe per registrare la risorsa MOF durante la configurazione dell'applicazione. Per altre informazioni, vedere Pubblicazione dello schema eventi.
Windows XP con SP1, Windows XP e Windows 2000: Puntatore a una stringa facoltativa che specifica la risorsa stringa di MofImagePath. La risorsa stringa contiene il nome del file MOF binario che descrive le classi di traccia evento supportate dal provider.
[out] RegistrationHandle
Riceve l'handle di registrazione del provider. Usare l'handle restituito quando si chiama la funzione UnregisterTraceGuids .
Importante
Tutti gli handle di registrazione creati da una DLL o da un driver devono essere annullati prima dello scaricamento della DLL o del driver. Se il provider non è registrato, si verificherà un arresto anomalo quando ETW tenta di richiamare il callback del provider.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. Di seguito sono riportati alcuni errori comuni e le relative cause.
Importante
Questa funzione può anche restituire il valore restituito da ControlCallback se un controller chiama EnableTrace per abilitare il provider e il provider non ha ancora chiamato RegisterTraceGuids. In questo caso, RegisterTraceGuids restituirà il valore restituito del callback se la registrazione ha avuto esito positivo.
ERROR_INVALID_PARAMETER
Una delle seguenti condizioni è vera:
- RequestAddress è NULL.
- ControlGuid è NULL.
- RegistrationHandle è NULL.
Windows XP e Windows 2000:TraceGuidReg è NULL o GuidCount è minore o uguale a zero.
Commenti
Nota
La maggior parte degli sviluppatori non chiamerà direttamente questa funzione. Gli sviluppatori usano in genere un framework ETW. Ad esempio, WPP basato su TMF gestisce le chiamate a RegisterTraceGuids, TraceMessage e UnregisterTraceGuids per conto dell'utente.
Questa funzione apre un handle di provider di eventi classico (windows 2000) che può essere usato per scrivere eventi ETW basati su MOF e TMF tramite TraceEvent, TraceEventInstance, TraceMessage e TraceMessageVa.
Nota
Per aprire un handle del provider di stile Windows Vista che scrive eventi ETW basati su manifesto o TraceLogging tramite EventWrite, usare EventRegister.
Se ControlGuid del provider è stato registrato e abilitato in precedenza, le registrazioni successive che fanno riferimento allo stesso ControlGuid vengono abilitate automaticamente.
Un processo può registrare fino a 1.024 GUID del provider; Tuttavia, è necessario limitare il numero di provider registrati dal processo a uno o due. Questo limite include quelli registrati usando questa funzione e la funzione EventRegister .
Prima di Windows Vista: Non esiste alcun limite al numero di provider che un processo può registrare.
Esempio
Per un esempio che usa RegisterTraceGuids, vedere Scrittura di eventi classici.
Nota
L'intestazione evntrace.h definisce RegisterTraceGuids come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Client minimo supportato | Windows 2000 Professional [app desktop | App UWP] |
| Server minimo supportato | Windows 2000 Server [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntrace.h |
| Libreria | Sechost.lib in Windows 8.1 e Windows Server 2012 R2; Advapi32.lib in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
| DLL | Sechost.dll in Windows 8.1 e Windows Server 2012 R2; Advapi32.dll in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |