Definindo e obtendo um token de log para um thread

O registo de APIs SetupAPI suporta um mecanismo que estabelece um contexto de registo para um thread. Este contexto é estabelecido ao definir um token log para a thread. A SetupAPI fornece este mecanismo para que o código que é chamado por uma thread possa escrever entradas de log no contexto de log da thread que chama.

Por exemplo, um thread pode definir um token log para o seu contexto de log antes de chamar um instalador de classe ou co-instalador. O instalador, por sua vez, pode recuperar o token de log da thread que chama e usar esse token para escrever entradas de log no log de texto e na secção associada ao contexto log da thread que chama.

Definir um token de log para um thread

A função SetupSetThreadLogToken define um token log para o thread de onde esta função foi chamada. O token de log pode ser um token de log definido pelo sistema ou um token log que foi recuperado ao chamar SetupGetThreadLogToken.

Seguem-se exemplos de como um contexto de log pode ser estabelecido para um thread:

• Uma aplicação de instalação pode chamar o SetupSetThreadLogToken para estabelecer um contexto de registo para outro código de instalação que corra dentro do mesmo thread. Ao estabelecer o contexto de log para o thread, a aplicação deve usar um token de log definido pelo sistema, como LOGTOKEN_SETUPAPI_APPLOG, na chamada ao SetupSetThreadLogToken.

  Nota Se o contexto de registo for definido usando um token de registo definido pelo sistema, chamadas subsequentes a uma função de registo da SetupAPI feitas a partir desse contexto de registo escrevem entradas de registo no registo de texto da instalação, que não fazem parte de uma secção de registo de texto.

• Se um instalador de classes ou co-instalador iniciar um novo thread, o instalador pode definir o contexto de log desse thread para ser o mesmo do thread pai. Isto é feito da seguinte forma:

  1. Antes de a thread principal iniciar a nova thread, adquire o token de log atual ao chamar o SetupGetThreadLogToken.
  2. A thread principal inicia a nova thread e passa o token log atual através de um método específico da implementação, como guardar o token numa variável global.
  3. O novo thread chama SetupSetThreadLogToken com o token de log atual. Como resultado, a nova thread "herda" o contexto log da thread pai.

  Nota Se um thread de um instalador de classe ou co-instalador definir o contexto do registo usando este método, chamadas subsequentes a uma função de registo SetupAPI feitas a partir desse contexto do registo escrevem entradas de registo no registo de texto da instalação que podem fazer parte de uma secção de registo de texto. Isto só acontece se uma secção de registo de texto foi estabelecida pela operação de instalação do SetupAPI que chamou o instalador.

Segue-se um exemplo de chamada ao SetupSetThreadLogToken que define o contexto de registo do thread atual para o registo de texto de instalação do dispositivo (SetupAPI.app.log), especificando o token de registo definido pelo sistema de LOGTOKEN_SETUPAPI_APPLOG. Uma chamada subsequente a uma função de registo SetupAPI que utilize este contexto de registo escreveria a entrada de registo no registo de texto da instalação do dispositivo, mas não como parte de uma secção de registo de texto.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Obter um token de registo para uma thread

A função SetupGetThreadLogToken recupera um token de log para o thread de onde esta função foi chamada.

Por exemplo, um instalador de classes pode chamar o SetupGetThreadLogToken para recuperar o token de registo que se aplica à operação SetupAPI que chamou o instalador da classe. O instalador da classe pode então usar este token de registo recuperado para registar entradas no ficheiro de registo de texto que se aplicam à operação correspondente do SetupAPI.

Nota Se o contexto de log de um thread não foi previamente definido por uma chamada ao SetupSetThreadLogToken, uma chamada ao SetupGetThreadLogToken devolve um token log com o valor de LOGTOKEN_UNSPECIFIED.

Segue-se um exemplo de chamada ao SetupGetThreadLogToken que recupera o token de log para o thread atual.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();