Função EventWriteTransfer (evntprov.h)

Grava um evento ETW com uma ID de atividade e uma ID de atividade relacionada opcional.

Sintaxe

ULONG EVNTAPI EventWriteTransfer(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parâmetros

[in] RegHandle

Identificador de registro do provedor. O identificador vem de EventRegister. O evento gerado usará a ProviderId associada ao identificador.

[in] EventDescriptor

EVENT_DESCRIPTOR com informações de evento (metadados), incluindo ID, Versão, Nível, Palavra-chave, Canal, Opcode e Tarefa.

[in, optional] ActivityId

Um ponteiro opcional para uma ID de atividade de 128 bits para esse evento. Se isso não for NULL, EventWriteTransfer usará o valor especificado para a ID de atividade do evento. Se for NULL, EventWriteTransfer usará a ID de atividade do thread atual.

As ferramentas de processamento de rastreamento podem usar a ID de atividade do evento para organizar eventos em grupos chamados atividades. Para obter informações adicionais sobre a ID da atividade, consulte EventActivityIdControl.

[in, optional] RelatedActivityId

Um ponteiro opcional para uma ID de atividade de 128 bits que é o pai da atividade desse evento. Se isso não for NULL, EventWriteTransfer usará o valor especificado para a ID de atividade relacionada do evento. Se for NULL, o evento não terá uma ID de atividade relacionada. A ID da atividade relacionada geralmente é definida no evento START da atividade (o primeiro evento da atividade, registrado com Opcode = START).

As ferramentas de processamento de rastreamento podem usar a ID de atividade relacionada do evento para determinar a relação entre as atividades, por exemplo, a atividade relacionada é o pai da atividade recém-iniciada. Para obter informações adicionais sobre a ID da atividade relacionada, consulte EventActivityIdControl.

[in] UserDataCount

Número de estruturas de EVENT_DATA_DESCRIPTOR no UserData. O número máximo é 128.

[in, optional] UserData

Uma matriz de estruturas EVENT_DATA_DESCRIPTOR UserDataCount que descrevem os dados a serem incluídos no evento. UserData poderá ser NULL se UserDataCount for zero.

Cada EVENT_DATA_DESCRIPTOR descreve um bloco de memória a ser incluído no evento. Os blocos especificados serão concatenados em ordem sem preenchimento ou alinhamento para formar o conteúdo do evento. Se estiver usando a decodificação baseada em manifesto, o conteúdo do evento deverá corresponder ao layout especificado no modelo associado ao evento no manifesto.

Retornar valor

Retorna ERROR_SUCCESS se tiver êxito ou um código de erro. Os códigos de erro possíveis incluem o seguinte:

• ERROR_INVALID_PARAMETER: um ou mais dos parâmetros não são válidos.
• ERROR_INVALID_HANDLE: o identificador de registro do provedor não é válido.
• ERROR_ARITHMETIC_OVERFLOW: o tamanho do evento é maior que o máximo permitido (64 KB – cabeçalho).
• ERROR_MORE_DATA: o tamanho do buffer de sessão é muito pequeno para o evento.
• ERROR_NOT_ENOUGH_MEMORY: ocorre quando os buffers preenchidos estão tentando liberar para o disco, mas os IOs de disco não estão acontecendo rápido o suficiente. Isso acontece quando o disco está lento e o tráfego de eventos é pesado. Eventualmente, não há mais buffers gratuitos (vazios) e o evento é descartado.
• STATUS_LOG_FILE_FULL: o arquivo de reprodução em tempo real está cheio. Os eventos não são registrados na sessão até que um consumidor em tempo real consuma os eventos do arquivo de reprodução.

O código de erro destina-se principalmente ao uso em cenários de depuração e diagnóstico. A maioria dos códigos de produção deve continuar a ser executada e continuar a relatar eventos mesmo que um evento ETW não possa ser gravado, portanto, os builds de versão geralmente devem ignorar o código de erro.

Comentários

A maioria dos provedores de eventos não chamará EventWriteTransfer diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que encapsula as chamadas para EventRegister, EventWriteTransfer e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e usar o Compilador de Mensagens para gerar código C/C++ para os eventos ou pode usar TraceLogging para evitar a necessidade de um manifesto.

EventWriteTransfer roteará o evento para as sessões de rastreamento apropriadas com base no ProviderId (determinado do RegHandle), Level, Keyword e outras características de evento. Se nenhuma sessão de rastreamento estiver gravando esse evento, essa função não fará nada e retornará ERROR_SUCCESS.

Para reduzir o impacto no desempenho de eventos que não são registrados por nenhuma sessão de rastreamento, você pode chamar EventEnabled para determinar se qualquer sessão de rastreamento está gravando seu evento antes de preparar os dados e chamar EventWriteTransfer.

EventWriteTransfer é equivalente a EventWriteEx com 0 para Filtro e 0 para Sinalizadores.

Requisitos

Confira também

EventActivityIdControl

EventRegister

EventWrite

EventWriteEx

Gravando eventos baseados em manifesto.