Condividi tramite


Funzione RegisterTraceGuidsA (evntrace.h)

La funzione RegisterTraceGuids registra un classico (stile Windows 2000) e le classi di traccia evento usate per generare eventi. Questa funzione specifica anche la funzione di callback usata 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 di eventi ETW di (Crimson) di windows Vista .

Sintassi

ULONG WMIAPI RegisterTraceGuidsA(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCSTR                   MofImagePath,
  [in]      LPCSTR                   MofResourceName,
  [out]     TRACEGUID_HANDLE         *RegistrationHandle
);

Parametri

[in] RequestAddress

Puntatore a una funzione ControlCallback che riceve la 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

GUID di controllo (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 guid membro di ogni struttura contiene un GUID della classe di traccia di eventi assegnato dal provider di registrazione. Il GUID della classe identifica una categoria di eventi forniti dal provider. I provider usano lo stesso GUID della classe per impostare il membro Guid di EVENT_TRACE_HEADER quando si chiama la funzione TraceEvent per registrare l'evento.

In caso di 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 di eventi.

Windows XP con SP1, Windows XP e Windows 2000: Puntatore a una stringa facoltativa che specifica il percorso della DLL o del programma 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 usate 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 di 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 eventi 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 è 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 condizioni seguenti è vera:

    • RequestAddress è NULL.
    • ControlGuid è NULL.
    • RegistrationHandle è NULL.

    Windows XP e Windows 2000:TraceGuidReg è NULL o GuidCount è minore o uguale a zero.

Osservazioni

Nota

La maggior parte degli sviluppatori non chiamerà direttamente questa funzione. Gli sviluppatori useranno in genere un framework ETW. Ad esempio, WPP basato su TMF gestisce le chiamate a RegisterTraceGuids, TraceMessagee UnregisterTraceGuids per conto dell'utente.

Questa funzione apre un handle del provider di eventi classico (stile Windows 2000) che può essere usato per scrivere eventi WPP ETW basati su MOF e TMF tramite TraceEvent, TraceEventInstance, TraceMessagee TraceMessageVa.

Nota

Per aprire un provider di di di windows Vista che scrive eventi ETW basati su manifesto o TraceLogging tramite EventWrite, usare EventRegister.

Se il 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.

Esempi

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 di per i prototipi di funzioni.

Fabbisogno

Requisito Valore
client minimo supportato Windows 2000 Professional [app desktop | App UWP]
server minimo supportato Windows 2000 Server [app desktop | App UWP]
piattaforma di destinazione Finestre
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

Vedere anche

EnableTrace

unregisterTraceGuids