Função RegisterTraceGuidsA (evntrace.h)
A função
Essa função é obsoleta. O novo código deve usar eventRegister para registrar um provedor de rastreamento de eventos ETW no estilo do Windows Vista (Crimson).
Sintaxe
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
);
Parâmetros
[in] RequestAddress
Ponteiro para uma função ControlCallback que recebe notificação quando o provedor está habilitado ou desabilitado por uma sessão de rastreamento de eventos. A função EnableTrace dispara esse retorno de chamada.
[in] RequestContext
Ponteiro para um contexto opcional definido pelo provedor que o ETW passa para a função especificada por RequestAddress.
[in] ControlGuid
Controlar GUID (ID do provedor) do provedor de registro.
[in] GuidCount
Número de elementos na matriz
[in, out] TraceGuidReg
Ponteiro para uma matriz de
TRACE_GUID_REGISTRATION estruturas.
Cada elemento identifica uma categoria de eventos que o provedor fornece.
Na entrada, o Guid membro de cada estrutura contém um GUID de classe de rastreamento de eventos atribuído pelo provedor de registro. O GUID de classe identifica uma categoria de eventos que o provedor fornece. Os provedores usam o GUID da mesma classe para definir o membro Guid do EVENT_TRACE_HEADER ao chamar a função TraceEvent para registrar o evento em log.
Na saída, o membro RegHandle recebe um identificador para o registro guid da classe do evento. Se o provedor chamar a função TraceEventInstance, use o RegHandle membro do TRACE_GUID_REGISTRATION para definir o RegHandle membro do EVENT_INSTANCE_HEADER.
Esse parâmetro poderá ser NULL se o provedor chamar apenas a função TraceEvent para registrar eventos de log. Se o provedor chamar a função TraceEventInstance para registrar eventos em log, esse parâmetro não poderá ser NULL.
[in] MofImagePath
Não há suporte para esse parâmetro. Definir como NULL. Você deve usar Mofcomp.exe para registrar o recurso MOF durante a instalação do aplicativo. Para obter mais informações, consulte Publicando seu esquema de eventos.
Windows XP com SP1, Windows XP e Windows 2000: Ponteiro para uma cadeia de caracteres opcional que especifica o caminho da DLL ou programa executável que contém o recurso especificado por MofResourceName. Esse parâmetro poderá ser NULL se o provedor de eventos e o consumidor usarem outro mecanismo para compartilhar informações sobre as classes de rastreamento de eventos usadas pelo provedor.
[in] MofResourceName
Não há suporte para esse parâmetro. Definir como NULL. Você deve usar Mofcomp.exe para registrar o recurso MOF durante a instalação do aplicativo. Para obter mais informações, consulte Publicando seu esquema de eventos.
Windows XP com SP1, Windows XP e Windows 2000: ponteiro para uma cadeia de caracteres opcional que especifica o recurso de cadeia de caracteres de MofImagePath. O recurso de cadeia de caracteres contém o nome do arquivo MOF binário que descreve as classes de rastreamento de eventos compatíveis com o provedor.
[out] RegistrationHandle
Recebe o identificador de registro do provedor. Use o identificador retornado ao chamar a função UnregisterTraceGuids.
Importante
Todos os identificadores de registro criados por uma DLL ou driver devem não ser registrados antes que a DLL ou o driver descarregue. Se o provedor não estiver registrado, ocorrerá uma falha quando o ETW tentar invocar o retorno de chamada do provedor.
Valor de retorno
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.
Importante
Essa função também pode retornar o valor retornado por ControlCallback se um controlador chamar EnableTrace para habilitar o provedor e o provedor ainda não tiver chamado RegisterTraceGuids. Quando isso ocorrer, RegisterTraceGuids retornará o valor retornado do retorno de chamada se o registro tiver sido bem-sucedido.
ERROR_INVALID_PARAMETER
Uma das seguintes opções é verdadeira:
- RequestAddress é NULL.
- ControlGuid é NULL.
- RegistrationHandle é NULL.
Windows XP e Windows 2000: TraceGuidReg é NULL ou guidCount é menor ou igual a zero.
Observações
Nota
A maioria dos desenvolvedores não chamará essa função diretamente. Em vez disso, os desenvolvedores normalmente usarão uma estrutura ETW. Por exemplo, o WPP baseado em TMF gerencia as chamadas para RegisterTraceGuids, TraceMessagee UnregisterTraceGuids em seu nome.
Essa função abre um identificador do provedor de eventos Clássico do
Nota
Para abrir um
Se o ControlGuid do provedor tiver sido registrado e habilitado anteriormente, os registros subsequentes que fazem referência ao mesmo ControlGuid serão habilitados automaticamente.
Um processo pode registrar até 1.024 GUIDs do provedor; no entanto, você deve limitar o número de provedores que seu processo registra para um ou dois. Esse limite inclui aqueles registrados usando essa função e a função EventRegister.
Antes do Windows Vista: Não há limite para o número de provedores que um processo pode registrar.
Exemplos
Para obter um exemplo que usa RegisterTraceGuids, consulte Gravando eventos clássicos.
Nota
O cabeçalho evntrace.h define RegisterTraceGuids como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | evntrace.h |
| biblioteca | Sechost.lib no Windows 8.1 e Windows Server 2012 R2; Advapi32.lib no Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
| de DLL |
Sechost.dll no Windows 8.1 e no Windows Server 2012 R2; Advapi32.dll no Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |