Função ReportEventA (winbase.h)
Grava uma entrada no final do log de eventos especificado.
Sintaxe
BOOL ReportEventA(
[in] HANDLE hEventLog,
[in] WORD wType,
[in] WORD wCategory,
[in] DWORD dwEventID,
[in] PSID lpUserSid,
[in] WORD wNumStrings,
[in] DWORD dwDataSize,
[in] LPCSTR *lpStrings,
[in] LPVOID lpRawData
);
Parâmetros
[in] hEventLog
Um identificador para o log de eventos. A função RegisterEventSource retorna esse identificador.
A partir do Windows XP com SP2, esse parâmetro não pode ser um identificador para o log de segurança . Para gravar um evento no log de segurança , use a função AuthzReportSecurityEvent .
[in] wType
O tipo de evento a ser registrado. Esse parâmetro pode usar um dos valores a seguir.
Para obter mais informações sobre tipos de eventos, consulte Tipos de eventos.
[in] wCategory
A categoria de evento. São informações específicas da origem; a categoria pode ter qualquer valor. Para obter mais informações, consulte Categorias de eventos.
[in] dwEventID
O identificador de evento. O identificador de evento especifica a entrada no arquivo de mensagem associado à origem do evento. Para obter mais informações, consulte Identificadores de eventos.
[in] lpUserSid
Um ponteiro para o identificador de segurança do usuário atual. Esse parâmetro poderá ser NULL se o identificador de segurança não for necessário.
[in] wNumStrings
O número de cadeias de caracteres de inserção na matriz apontada pelo parâmetro lpStrings . Um valor zero indica que nenhuma cadeia de caracteres está presente.
[in] dwDataSize
O número de bytes de dados brutos (binários) específicos ao evento a serem gravados no log. Se esse parâmetro for zero, nenhum dado específico do evento estará presente.
[in] lpStrings
Um ponteiro para um buffer que contém uma matriz de cadeias de caracteres terminadas em nulo que são mescladas na mensagem antes de Visualizador de Eventos exibe a cadeia de caracteres para o usuário. Esse parâmetro deve ser um ponteiro válido (ou NULL), mesmo que wNumStrings seja zero. Cada cadeia de caracteres é limitada a 31.839 caracteres.
Antes do Windows Vista: Cada cadeia de caracteres é limitada a 32 mil caracteres.
[in] lpRawData
Um ponteiro para o buffer que contém os dados binários. Esse parâmetro deve ser um ponteiro válido (ou NULL), mesmo que o parâmetro dwDataSize seja zero.
Retornar valor
Se a função for bem-sucedida, o valor retornado será diferente de zero, indicando que a entrada foi gravada no log.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError, que retorna um dos seguintes códigos de erro estendidos.
| Código do erro | Significado |
|---|---|
|
Um dos parâmetros não é válido.
Esse erro será retornado no Windows Server 2003 se os dados da mensagem a serem registrados forem muito grandes. Esse erro será retornado pelo servidor RPC no Windows Server 2003 se o parâmetro dwDataSize for maior que 261.991 (0x3ff67). |
|
Recursos de memória insuficientes estão disponíveis para concluir a operação. |
|
Os limites da matriz são inválidos.
Esse erro será retornado se os dados da mensagem a serem registrados forem muito grandes. No Windows Vista e posterior, esse erro será retornado se o parâmetro dwDataSize for maior que 61.440 (0xf000). |
|
O stub recebeu dados incorretos.
Esse erro será retornado no Windows XP se os dados da mensagem a serem registrados forem muito grandes. Esse erro será retornado pelo servidor RPC no Windows XP, se o parâmetro dwDataSize for maior que 262.143 (0x3ffff). |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
Essa função é usada para registrar um evento em log. A entrada é gravada no final do log configurado para a origem identificada pelo parâmetro hEventLog . A função ReportEvent adiciona o tempo, o comprimento da entrada e os deslocamentos antes de armazenar a entrada no log. Para habilitar a função para adicionar o nome de usuário, você deve fornecer o SID do usuário no parâmetro lpUserSid .
Há limites de tamanho diferentes no tamanho dos dados da mensagem que podem ser registrados dependendo da versão do Windows usada pelo cliente em que o aplicativo é executado e pelo servidor em que a mensagem é registrada. O servidor é determinado pelo parâmetro lpUNCServerName passado para a função RegisterEventSource . Erros diferentes são retornados quando o limite de tamanho é excedido que dependem da versão do Windows.
Se a cadeia de caracteres que você registra contiver %n, em que n é um valor inteiro (por exemplo, %1), o visualizador de eventos a tratará como uma cadeia de caracteres de inserção. Como um endereço IPv6 pode conter essa sequência de caracteres, você deve fornecer um especificador de formato (! S!) para registrar uma mensagem de evento que contém um endereço IPv6. Esse especificador informa ao código de formatação para usar a cadeia de caracteres literalmente e não executar nenhuma expansão adicional (por exemplo, "meu endereço IPv6 é: %1! S!").
Exemplos
Para obter um exemplo, consulte Reportando um evento.
Observação
O cabeçalho winbase.h define ReportEvent como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de 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 Convenções para protótipos de função.
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 | winbase.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |