Função CreateTraceInstanceId (evntrace.h)

  • Artigo

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

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho evntrace.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

RegisterTraceGuids

TraceEventInstance