Définition et obtention d'un jeton de journal pour un thread

La journalisation SetupAPI prend en charge un mécanisme qui établit un contexte de journal pour un thread. Ce contexte est établi en définissant un jeton de journal pour le thread. SetupAPI fournit ce mécanisme afin que le code appelé par un thread puisse écrire des entrées de journal dans le contexte de journal du thread appelant.

Par exemple, un thread peut définir un jeton de journal pour son contexte de journal avant d'appeler un programme d'installation de classe ou un co-programme d'installation. Le programme d’installation, à son tour, peut récupérer le jeton de journal du thread appelant et utiliser ce jeton pour écrire des entrées de journal dans le journal de texte et la section associée au contexte de journal du thread appelant.

Définir un jeton de journal pour un thread

La fonction SetupSetThreadLogToken définit un jeton de journal pour le thread à partir duquel cette fonction a été appelée. Le jeton de journal peut être un jeton de journal défini par le système ou un jeton de journal récupéré en appelant SetupGetThreadLogToken.

Voici quelques exemples de la façon dont un contexte de journalisation peut être établi pour un fil d’exécution :

• Une application d’installation peut appeler SetupSetThreadLogToken pour établir un contexte de journal pour d’autres codes d’installation qui s’exécutent dans le même thread. Lorsqu’elle établit le contexte du journal pour le thread, l’application doit utiliser un jeton de journal défini par le système, tel que LOGTOKEN_SETUPAPI_APPLOG, dans l’appel à SetupSetThreadLogToken.

  Remarque Si le contexte de journal est défini à l’aide d’un jeton de journal défini par le système, les appels suivants à une fonction de journalisation SetupAPI effectués à partir de ce contexte de journal, écrivent des entrées de journal dans le journal de texte d’installation, qui ne font pas partie d’une section du journal de texte.

• Si un programme d'installation de classe ou un co-programme d'installation démarre un nouveau thread, le programme d'installation peut définir le contexte de journal de ce thread pour qu'il soit identique à celui du thread parent. Pour ce faire, procédez comme suit :

  1. Avant que le thread parent démarre le nouveau thread, il acquiert le jeton de journal actuel en appelant SetupGetThreadLogToken.
  2. Le thread parent démarre le nouveau thread et transmet le jeton de journal actuel via une méthode spécifique à l’implémentation, telle que l’enregistrement du jeton dans une variable globale.
  3. Le nouveau thread appelle SetupSetThreadLogToken avec le jeton de journal actuel. Par conséquent, le nouveau thread « hérite » du contexte de journal du thread parent.

  Remarque Si un thread d’un programme d’installation de classe ou d’un co-programme d’installation définit le contexte de journalisation à l’aide de cette méthode, les appels suivants à une fonction de journalisation SetupAPI effectuée à partir de ce contexte de journal écrivent des entrées de journal dans le journal de texte d’installation qui peuvent faire partie d’une section du journal de texte. Cela se produit uniquement si une section de journal de texte a été établie par l’opération d’installation SetupAPI qui a appelé le programme d’installation.

Voici un exemple d’appel à SetupSetThreadLogToken qui définit le contexte de journal du thread actuel dans le journal de texte d’installation de l’appareil (SetupAPI.app.log) en spécifiant le jeton de journal défini par le système de LOGTOKEN_SETUPAPI_APPLOG. Un appel ultérieur à une fonction de journalisation SetupAPI qui utiliserait ce contexte de journalisation écrirait l’entrée de journal dans le journal de texte d’installation de l’appareil, mais pas dans le cadre d’une section du journal de texte.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Obtenir un jeton de journal pour un thread

La fonction SetupGetThreadLogToken récupère un jeton de journal pour le thread à partir duquel cette fonction a été appelée.

Par exemple, un programme d’installation de classe peut appeler SetupGetThreadLogToken pour récupérer le jeton de journal qui s’applique à l’opération SetupAPI qui a appelé le programme d’installation de classe. Le programme d'installation de classe peut ensuite utiliser ce jeton de journal récupéré pour consigner des entrées dans le journal texte qui s'applique à l'opération SetupAPI correspondante.

Remarque Si le contexte de journal d’un thread n’a pas été précédemment défini par un appel à SetupSetThreadLogToken, un appel à SetupGetThreadLogToken retourne un jeton de journal avec la valeur LOGTOKEN_UNSPECIFIED.

Voici un exemple d’appel à SetupGetThreadLogToken qui récupère le jeton de journal pour le thread actuel.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();