Establecimiento y obtención de un token de log para un hilo

El registro de SetupAPI admite un mecanismo que establece un contexto de registro para un subproceso. Este contexto se establece configurando un token de registro para el hilo. SetupAPI proporciona este mecanismo para que el código invocado por un subproceso pueda escribir entradas de registro en el contexto de registro del subproceso que realiza la llamada.

Por ejemplo, un subproceso puede establecer un token de registro para su contexto de registro antes de llamar a un instalador de clase o co-instalador. El instalador, a su vez, puede recuperar el token de registro del hilo que realiza la llamada y utilizar ese token para escribir entradas de registro en el registro de texto y en la sección asociada al contexto de registro del hilo que realiza la llamada.

Establecimiento de un token de registro para un subproceso

La función SetupSetThreadLogToken establece un token de registro para el subproceso desde el que se llamó a esta función. El token de registro puede ser un token de registro definido por el sistema o un token de registro que se recuperó llamando a SetupGetThreadLogToken.

A continuación se muestran ejemplos de cómo se puede establecer un contexto de registro para un subproceso:

• Una aplicación de instalación puede llamar a SetupSetThreadLogToken para establecer un contexto de registro para otro código de instalación que se ejecuta dentro del mismo subproceso. Cuando se establece el contexto de registro para el subproceso, la aplicación debe usar un token de registro definido por el sistema, como LOGTOKEN_SETUPAPI_APPLOG, en la llamada a SetupSetThreadLogToken.

  Nota Si el contexto de registro se establece utilizando un token de registro definido por el sistema, las llamadas posteriores a una función de registro de SetupAPI que se realicen desde ese contexto de registro escribirán entradas de registro en el registro de texto de la instalación, que no forman parte de una sección de registro de texto.

• Si un instalador de clase o un coinstalador inicia un nuevo hilo, el instalador puede establecer el contexto de registro para ese hilo igual al del hilo principal. Esto se hace de la siguiente manera:

  1. Antes de que el hilo principal inicie el nuevo hilo, obtiene el token de registro actual llamando a SetupGetThreadLogToken.
  2. El hilo padre inicia el nuevo hilo y pasa el token de registro actual a través de un método específico de la implementación, como guardar el token en una variable global.
  3. El nuevo subproceso llama a SetupSetThreadLogToken con el token de registro actual. Como resultado, el nuevo subproceso "hereda" el contexto de registro del subproceso primario.

  Nota Si un subproceso de un instalador de clase o coinstalador establece el contexto de registro mediante este método, las llamadas posteriores a una función de registro de SetupAPI que se realizan desde ese contexto de registro escriben entradas de registro en el registro de texto de instalación que pueden formar parte de una sección de registro de texto. Esto solo sucede si una sección de registro de texto fue establecida por la operación de instalación de SetupAPI que llamó al instalador.

A continuación se muestra un ejemplo de una llamada a SetupSetThreadLogToken que establece el contexto de registro del subproceso actual en el registro de texto de instalación del dispositivo (SetupAPI.app.log) especificando el token de registro definido por el sistema de LOGTOKEN_SETUPAPI_APPLOG. Una llamada posterior a una función de registro setupAPI que usa este contexto de registro escribiría la entrada de registro en el registro de texto de instalación del dispositivo, pero no como parte de una sección de registro de texto.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Obtención de un token de registro para un subproceso

La función SetupGetThreadLogToken recupera un token de registro para el subproceso desde el que se llamó a esta función.

Por ejemplo, un instalador de clase puede llamar a SetupGetThreadLogToken para recuperar el token de registro que se aplica a la operación SetupAPI que llamó al instalador de clase. A continuación, el instalador de clase puede utilizar este token de registro recuperado para registrar entradas en el registro de texto que se aplica a la operación de SetupAPI correspondiente.

Nota Si el contexto de registro de un subproceso no se estableció previamente mediante una llamada a SetupSetThreadLogToken, una llamada a SetupGetThreadLogToken devuelve un token de registro con un valor de LOGTOKEN_UNSPECIFIED.

A continuación se muestra un ejemplo de una llamada a SetupGetThreadLogToken que recupera el token de registro del subproceso actual.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();