Função CreateTraceInstanceId (evntrace.h)

Um provedor de eventos baseado em RegisterTraceGuids ("Clássico") pode usar a função CreateTraceInstanceId para criar um identificador de transação exclusivo e mapeá-lo para um identificador de registro. Em seguida, o provedor usa o identificador de transação ao chamar a função TraceEventInstance para marcar eventos como pertencentes à transação especificada. O identificador de transação pode ser usado por ferramentas de análise de rastreamento para agrupar eventos.

Sintaxe

ULONG WMIAPI CreateTraceInstanceId(
  [in]  HANDLE               RegHandle,
  [out] PEVENT_INSTANCE_INFO InstInfo
);

Parâmetros

[in] RegHandle

Manipule para uma classe de rastreamento de evento registrada. A função RegisterTraceGuids retorna esse identificador no membro RegHandle da estrutura TRACE_GUID_REGISTRATION .

[out] InstInfo

Ponteiro para uma estrutura EVENT_INSTANCE_INFO . O membro InstanceId dessa estrutura contém o identificador de transação.

Retornar valor

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um dos códigos de erro do sistema. Veja a seguir alguns erros comuns e suas causas.

• ERROR_INVALID_PARAMETER

  Uma das seguintes condições é verdadeira:

  • RegHandle é NULL.
  • pInstInfo é NULL.

Comentários

Os provedores baseados em RegisterTraceGuids ("Clássico") chamam essa função. Use EventActivityIdControl para funcionalidade semelhante com um provedor baseado em EventRegister ("Crimson").

O ETW cria o identificador no processo de modo de usuário, portanto, ele pode retornar o mesmo número para instâncias diferentes em processos diferentes. O valor começa em 1 quando InstanceId atinge o valor máximo de um ULONG. Somente provedores de modo de usuário podem chamar a função CreateTraceInstanceId (os drivers não podem chamar essa função).

Exemplos

Para obter um exemplo que usa CreateTraceInstanceId, consulte Rastreamento de instâncias de evento.

Requisitos

Confira também

RegisterTraceGuids

TraceEventInstance