Een logboektoken instellen en ophalen voor een thread

SetupAPI-logging ondersteunt een mechanisme waarmee een logcontext voor een thread wordt ingesteld. Deze context wordt tot stand gebracht door een logtoken in te stellen voor de thread. SetupAPI biedt dit mechanisme, zodat code die wordt aangeroepen door een thread logboekvermeldingen kan schrijven naar de logboekcontext van de aanroepende thread.

Een thread kan bijvoorbeeld een logtoken instellen voor de logcontext voordat het een class installer of co-installatieprogramma aanroept. Het installatieprogramma kan op zijn beurt het logboektoken van de aanroepende thread ophalen en dat token gebruiken om logboekvermeldingen te schrijven in het tekstlogboek en de sectie die is gekoppeld aan de logboekcontext van de aanroepende thread.

Een logboektoken instellen voor een thread

Met de functie SetupSetThreadLogToken wordt een logboektoken ingesteld voor de thread waaruit deze functie is aangeroepen. Het logboektoken kan een door het systeem gedefinieerd logboektoken of een logboektoken zijn dat is opgehaald door SetupGetThreadLogToken aan te roepen.

Hier volgen enkele voorbeelden van hoe een logboekcontext voor een thread tot stand kan worden gebracht:

• Een installatietoepassing kan SetupSetThreadLogToken aanroepen om een logboekcontext tot stand te brengen voor andere installatiecode die binnen dezelfde thread wordt uitgevoerd. Wanneer de logboekcontext voor de thread tot stand wordt gebracht, moet de toepassing een door het systeem gedefinieerd logboektoken gebruiken, zoals LOGTOKEN_SETUPAPI_APPLOG, in de aanroep naar SetupSetThreadLogToken.

  Opmerking Als de logboekcontext is ingesteld met behulp van een door het systeem gedefinieerd logtoken, schrijven volgende aanroepen naar een SetupAPI-logboekfunctie die vanuit die logboekcontext worden gemaakt, logboekvermeldingen naar het installatietekstlogboek, die geen deel uitmaken van een tekstlogboeksectie.

• Als een klasse-installatieprogramma of co-installatieprogramma een nieuwe thread start, kan het installatieprogramma de logboekcontext voor die thread instellen op dezelfde als de bovenliggende thread. Dit gebeurt op de volgende manier:

  1. Voordat de bovenliggende thread de nieuwe thread start, verkrijgt deze het huidige logboektoken door SetupGetThreadLogToken aan te roepen.
  2. De bovenliggende thread start de nieuwe thread en geeft het huidige logboektoken door via een implementatiespecifieke methode, zoals het opslaan van het token in een globale variabele.
  3. De nieuwe thread roept SetupSetThreadLogToken aan met het huidige logboektoken. Als gevolg hiervan neemt de nieuwe thread de logboekcontext van de bovenliggende thread over.

  Opmerking Als een thread van een klasse-installatieprogramma of co-installatieprogramma de logboekcontext instelt met behulp van deze methode, schrijven daaropvolgende aanroepen naar een SetupAPI-logboekfunctie die vanuit die logboekcontext worden gemaakt logboekvermeldingen naar het installatietekstlogboek die mogelijk deel uitmaken van een tekstlogboeksectie. Dit gebeurt alleen als er een tekstlogboeksectie is gemaakt door de SetupAPI-installatiebewerking die het installatieprogramma heeft aangeroepen.

Hier volgt een voorbeeld van een aanroep van SetupSetThreadLogToken waarmee de logboekcontext van de huidige thread wordt ingesteld op het tekstlogboek voor de installatie van het apparaat (SetupAPI.app.log) door het door het systeem gedefinieerde logboektoken van LOGTOKEN_SETUPAPI_APPLOG op te geven. Een volgende aanroep van een SetupAPI-logboekfunctie die gebruikmaakt van deze logboekcontext, schrijft de logboekvermelding naar het installatietekstlogboek van het apparaat, maar niet als onderdeel van een tekstlogboeksectie.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Een log token ophalen voor een thread

De functie SetupGetThreadLogToken haalt een logboektoken op voor de thread waaruit deze functie is aangeroepen.

Een klasse-installatieprogramma kan bijvoorbeeld SetupGetThreadLogToken aanroepen om het logboektoken op te halen dat van toepassing is op de SetupAPI-bewerking die het klasse-installatieprogramma heeft aangeroepen. Het installatieprogramma van de klasse kan vervolgens dit opgehaalde logboektoken gebruiken om vermeldingen in het tekstlogboek te registreren die van toepassing zijn op de bijbehorende SetupAPI-bewerking.

Opmerking Als de logboekcontext van een thread niet eerder is ingesteld door een aanroep naar SetupSetThreadLogToken, retourneert een aanroep naar SetupGetThreadLogToken een logboektoken met de waarde LOGTOKEN_UNSPECIFIED.

Hier volgt een voorbeeld van een aanroep naar SetupGetThreadLogToken waarmee het logboektoken voor de huidige thread wordt opgehaald.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();