Partager via

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

  • Article

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és au contexte de journal du thread appelant.

Définition d’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 qui a été récupéré en appelant SetupGetThreadLogToken.

Voici quelques exemples de la façon dont un contexte de journal peut être établi pour un thread :

  • Une application d’installation peut appeler SetupSetThreadLogToken pour établir un contexte de journal pour un autre code d’installation qui s’exécute dans le même thread. Lorsqu’elle établit le contexte de 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.

    Note 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 qui sont effectués à partir de ce contexte de journal, écrivent les entrées du journal dans le journal de texte d’installation, qui ne font pas partie d’une section de journal texte.

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

    1. Avant que le thread parent ne 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.

    Note Si un thread d’un programme d’installation ou d’un co-programme d’installation de classe définit le contexte du journal à l’aide de cette méthode, les appels suivants à une fonction de journalisation SetupAPI qui sont effectués à partir de ce contexte de journalisation écrivent les entrées du journal dans le journal de texte d’installation qui peut faire partie d’une section de journal texte. Cela se produit uniquement si une section de journal 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 sur 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 utilise ce contexte de journalisation écrit l’entrée de journal dans le journal texte d’installation de l’appareil, mais pas dans une section de journal texte.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Obtention d’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 journaliser les entrées dans le journal de texte qui s’applique à l’opération SetupAPI correspondante.

Note Si le contexte de journal d’un thread n’a pas été défini précédemment par un appel à SetupSetThreadLogToken, un appel à SetupGetThreadLogToken renvoie un jeton de journal avec une valeur de 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();