Função TraceEventInstance (evntrace.h)
Um provedor de eventos baseado em RegisterTraceGuids ("Clássico") usa a função TraceEventInstance para enviar um evento estruturado para uma sessão de rastreamento de eventos com um identificador de instância.
O evento usa um identificador de instância para associar o evento a uma transação. Essa função também pode ser usada para rastrear relações hierárquicas entre eventos relacionados.
Sintaxe
ULONG WMIAPI TraceEventInstance(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_INSTANCE_HEADER EventTrace,
[in] PEVENT_INSTANCE_INFO InstInfo,
[in] PEVENT_INSTANCE_INFO ParentInstInfo
);
Parâmetros
[in] TraceHandle
Manipule para a sessão de rastreamento de eventos que registra a instância de evento. O provedor obtém o identificador quando chama a função GetTraceLoggerHandle em sua implementação ControlCallback .
[in] EventTrace
Ponteiro para uma estrutura EVENT_INSTANCE_HEADER . Os dados específicos do evento são acrescentados opcionalmente à estrutura . O maior evento que você pode registrar é 64K. Você deve especificar valores para os seguintes membros da estrutura EVENT_INSTANCE_HEADER .
- Tamanho
- Sinalizadores
- RegHandle
Dependendo da complexidade das informações fornecidas pelo provedor, você também deve considerar a especificação de valores para os membros a seguir.
- Class.Type
- Class.Level
Para rastrear relações hierárquicas entre eventos relacionados, defina também o membro ParentRegHandle .
[in] InstInfo
Ponteiro para uma estrutura EVENT_INSTANCE_INFO , que contém o identificador de registro para essa classe de rastreamento de evento e o identificador de instância. Use a função CreateTraceInstanceId para inicializar a estrutura.
[in] ParentInstInfo
Ponteiro para uma estrutura EVENT_INSTANCE_INFO , que contém o identificador de registro para a classe de rastreamento de evento pai e seu identificador de instância. Use a função CreateTraceInstanceId para inicializar a estrutura. Defina como NULL se você não estiver rastreando uma relação hierárquica.
Valor retornado
Se a função obtiver êxito, 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_FLAGS
O membro Flags do EVENT_INSTANCE_HEADER não contém WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY
Não havia memória suficiente para concluir a chamada de função. As causas desse código de erro são descritas na seção Comentários a seguir.
ERROR_INVALID_PARAMETER
Uma das seguintes condições é verdadeira:
- EventTrace é NULL.
- pInstInfo é NULL.
- Os membros de pInstInfo são NULL.
- TraceHandle é NULL.
- O membro Size do EVENT_INSTANCE_HEADER está incorreto.
ERROR_INVALID_HANDLE
TraceHandle não é válido ou especifica o identificador de sessão do Agente de Kernel NT.
ERROR_NOT_ENOUGH_MEMORY
A sessão ficou sem buffers livres para gravação. Isso pode ocorrer durante as altas taxas de eventos porque o subsistema do disco está sobrecarregado ou o número de buffers é muito pequeno. Em vez de bloquear até que mais buffers fiquem disponíveis, TraceEvent descarta o evento.
Windows 2000 e Windows XP: Sem suporte.
ERROR_OUTOFMEMORY
O evento é descartado porque, embora o pool de buffers não tenha atingido seu tamanho máximo, não há memória disponível suficiente para alocar um buffer adicional e não há nenhum buffer disponível para receber o evento.
ERROR_MORE_DATA
Os dados de um único evento não podem abranger vários buffers. Um evento de rastreamento é limitado ao tamanho do buffer da sessão de rastreamento de eventos menos o tamanho da estrutura EVENT_INSTANCE_HEADER .
Comentários
Os provedores ETW baseados em MOF chamam essa função.
Observação
A maioria dos desenvolvedores não chamará essa função. Essa API dá suporte ao ETW baseado em MOF, mas o ETW baseado em MOF foi preterido em favor do ETW baseado em manifesto. Além disso, a maioria dos provedores baseados em MOF usa funções wrapper geradas por MC.exe em vez de chamar diretamente APIs ETW.
Antes que o provedor possa chamar essa função, o provedor
- Deve chamar a função RegisterTraceGuids para se registrar e a classe de rastreamento de evento.
- Deve chamar a função CreateTraceInstanceId para criar um identificador de instância para a classe de rastreamento de evento registrada.
- Deve ser habilitado. Um controlador chama a função EnableTrace para habilitar um provedor.
O evento é gravado em um arquivo de log, enviado para consumidores de rastreamento de eventos em tempo real ou ambos. O membro LogFileMode da estrutura EVENT_TRACE_PROPERTIES passada para o StartTrace define para onde o evento é enviado.
Os eventos de rastreamento são gravados na ordem em que ocorrem.
Para rastrear eventos não relacionados, use a função TraceEvent .
Windows XP: Não funciona corretamente.
Exemplos
Para obter um exemplo de geração de conjuntos de eventos relacionados usando CreateTraceInstanceId e TraceEventInstance, consulte Rastreamento de instâncias de evento.
Requisitos
| 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 |