Compartilhar via

Chamando SetupWriteTextLogError

  • Artigo

SetupWriteTextLogError grava informações sobre um erro específico de SetupAPI ou um erro Win32 em um log de texto SetupAPI. SetupWriteTextLogError grava duas entradas consecutivas em um log de texto: a primeira entrada contém as mesmas informações no mesmo formato que a escrita por SetupWriteTextLog e a segunda entrada registra um código de erro correspondente e uma descrição amigável do erro.

Para chamar SetupWriteTextLogError, um aplicativo fornece as mesmas informações que forneceria para chamar SetupWriteTextLog e, além disso, fornece o valor de um erro específico de SetupAPI ou um erro Win32.

SetupWriteTextLogError grava a primeira entrada de log no seguinte formato:

categoria **** entry_prefix time_stamp indentation formatted-message

SetupWriteTextLogError grava a segunda entrada de log no seguinte formato:

categoria ** entry_prefix time_stamp recuo **Error:error-number error-description

Em que:

  • Os campos entry_prefix, carimbo de data/hora, categoria, recuo e mensagem formatada são os mesmos descritos em Formato de um Corpo da Seção de Log de Texto.

  • O campo número de erro contém o número de erro.

  • O campo de descrição de erro contém uma descrição amigável do erro.

O exemplo a seguir mostra como um aplicativo normalmente pode chamar SetupWriteTextLogError para registrar informações sobre um erro em um log de texto. O erro usado no exemplo é um erro de início do sistema. O aplicativo chama SetupWriteTextLogError, fornecendo os seguintes valores de parâmetro:

  • LogToken é definido como um valor de token de log que foi obtido chamando SetupGetThreadLogToken ou é um dos valores de token de log definidos pelo sistema descritos em Tokens de Log.

  • A categoria é definida como TXTLOG_VENDOR, o que indica que a entrada de log é feita por um aplicativo fornecido pelo fornecedor. As categorias de evento são descritas em Habilitando categorias de evento para um log de texto.

  • LogFlags é definido como TXTLOG_ERROR. Este exemplo não inclui um carimbo de data/hora ou altera a profundidade de recuo. A profundidade de recuo atual foi definida anteriormente como cinco espaços de texto monoespaço. Para obter informações sobre como alterar a profundidade do recuo, consulte Gravando entradas de log recuadas. Os níveis de evento são descritos em Configurando o nível de evento para um log de texto.

  • O erro é definido como o valor do código de erro Win32, ERROR_SERVICE_ALREADY_RUNNING. O valor decimal desse código de erro é 1056.

  • MessageStr está definido como TEXT("Serviço inicial: falha ao iniciar o serviço 'SomeService'").

  • Uma lista de parâmetros separados por vírgulas não é fornecida.

Os parâmetros LogToken, Category e LogFlags afetam a operação de SetupWriteTextLogError da mesma maneira que esses parâmetros afetam a operação de SetupWriteTextLog.

O código a seguir chama SetupWriteTextLogError para gravar a entrada de log para este exemplo:

//The LogToken value was previously returned by call to
//SetupGetThreadLogToken or one of the system-defined log token values
DWORD Category = TXTLOG_VENDOR; 
DWORD Flags = TXTLOG_ERROR ;
DWORD ErrorCode = 1056; // The corresponding Win32 error code

SetupWriteTextLog(LogToken, Category, Flags, ErrorCode, TEXT("Start Service: Failed to start service 'SomeService'"),);

Se a categoria de evento TXTLOG_VENDOR estiver habilitada e o nível de evento TXTLOG_ERROR for definido para o log de texto, esse código criará uma entrada no log de texto que seria formatada da seguinte maneira:

!!!     :  Start Service: Failed to start service 'SomeService' 
!!!   :  Error 1056: An instance of the service is already running.

Lembre-se de que SetupWriteTextLogError fornece a cadeia de caracteres "Uma instância do serviço já está em execução". Para descrever o erro Win32 cujo valor é 1056.