Configurando e obtendo um token de log para um thread

O log de SetupAPI dá suporte a um mecanismo que estabelece um contexto de log para um thread. Esse contexto é estabelecido definindo um token de log para o thread. SetupAPI fornece esse mecanismo para que o código chamado por um thread possa gravar entradas de log no contexto de log do thread de chamada.

Por exemplo, um thread pode definir um token de log para seu contexto de log antes de chamar um instalador de classe ou um co-instalador. O instalador, por sua vez, pode recuperar o token de log do thread de chamada e usar esse token para gravar entradas de log no log de texto e na seção associadas ao contexto de log do thread de chamada.

Configurando um token de log para um thread

A função SetupSetThreadLogToken define um token de log para o thread do qual essa função foi chamada. O token de log pode ser um token de log definido pelo sistema ou um token de log que foi recuperado chamando SetupGetThreadLogToken.

Veja a seguir exemplos de como um contexto de log pode ser estabelecido para um thread:

• Um aplicativo de instalação pode chamar SetupSetThreadLogToken para estabelecer um contexto de log para outro código de instalação executado no mesmo thread. Quando ele está estabelecendo o contexto de log para o thread, o aplicativo deve usar um token de log definido pelo sistema, como LOGTOKEN_SETUPAPI_APPLOG, na chamada para SetupSetThreadLogToken.

  Nota Se o contexto de log for definido usando um token de log definido pelo sistema, chamadas subsequentes para uma função de log setupAPI que são feitas a partir desse contexto de log, escreva entradas de log no log de texto de instalação, que não fazem parte de uma seção de log de texto.

• Se um instalador de classe ou co-instalador iniciar um novo thread, o instalador poderá definir o contexto de log para esse thread como o mesmo que o thread pai. Isso é feito da seguinte maneira:

  1. Antes que o thread pai inicie o novo thread, ele adquire o token de log atual chamando SetupGetThreadLogToken.
  2. O thread pai inicia o novo thread e passa o token de log atual por meio de um método específico da implementação, como salvar o token em uma variável global.
  3. O novo thread chama SetupSetThreadLogToken com o token de log atual. Como resultado, o novo thread "herda" o contexto de log do thread pai.

  Nota Se um thread de um instalador de classe ou co-instalador definir o contexto de log usando esse método, chamadas subsequentes para uma função de log setupAPI que são feitas a partir dessas entradas de log de gravação de contexto de log para o log de texto de instalação que pode fazer parte de uma seção de log de texto. Isso só acontecerá se uma seção de log de texto tiver sido estabelecida pela operação de instalação setupAPI que chamou o instalador.

Veja a seguir um exemplo de uma chamada para SetupSetThreadLogToken que define o contexto de log do thread atual para o log de texto de instalação do dispositivo (SetupAPI.app.log) especificando o token de log definido pelo sistema de LOGTOKEN_SETUPAPI_APPLOG. Uma chamada subsequente para uma função de log setupAPI que usa esse contexto de log gravaria a entrada de log no log de texto de instalação do dispositivo, mas não como parte de uma seção de log de texto.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Obtendo um token de log para um thread

A função SetupGetThreadLogToken recupera um token de log para o thread do qual essa função foi chamada.

Por exemplo, um instalador de classe pode chamar SetupGetThreadLogToken para recuperar o token de log que se aplica à operação SetupAPI que chamou o instalador de classe. Em seguida, o instalador de classe pode usar esse token de log recuperado para registrar entradas no log de texto que se aplica à operação SetupAPI correspondente.

Nota Se o contexto de log de um thread não tiver sido definido anteriormente por uma chamada para SetupSetThreadLogToken, uma chamada para SetupGetThreadLogToken retornará um token de log com um valor de LOGTOKEN_UNSPECIFIED.

Veja a seguir um exemplo de uma chamada para SetupGetThreadLogToken que recupera o token de log para o thread atual.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();