Festlegen und Abrufen eines Protokolltokens für einen Thread

SetupAPI-Protokollierung unterstützt einen Mechanismus, der einen Protokollkontext für einen Thread erstellt. Dieser Kontext wird durch Festlegen eines Protokolltokens für den Thread eingerichtet. SetupAPI stellt diesen Mechanismus bereit, damit Code, der von einem Thread aufgerufen wird, Protokolleinträge in den Protokollkontext des aufrufenden Threads schreiben kann.

Beispielsweise kann ein Thread ein Protokolltoken für seinen Protokollkontext festlegen, bevor er ein Klasseninstallationsprogramm oder ein Co-Installer aufruft. Das Installationsprogramm kann wiederum das Protokolltoken des aufrufenden Threads abrufen und dieses Token verwenden, um Protokolleinträge in das Textprotokoll und den Abschnitt zu schreiben, die dem Protokollkontext des aufrufenden Threads zugeordnet sind.

Festlegen eines Protokolltokens für einen Thread

Die SetupSetThreadLogToken-Funktion legt ein Protokolltoken für den Thread fest, von dem aus diese Funktion aufgerufen wurde. Das Protokolltoken kann entweder ein systemdefiniertes Protokolltoken oder ein Protokolltoken sein, das durch Aufrufen von SetupGetThreadLogToken abgerufen wurde.

Im Folgenden finden Sie Beispiele dafür, wie ein Protokollkontext für einen Thread eingerichtet werden kann:

• Eine Installationsanwendung kann SetupSetThreadLogToken aufrufen, um einen Protokollkontext für anderen Installationscode einzurichten, der im selben Thread ausgeführt wird. Beim Einrichten des Protokollkontexts für den Thread sollte die Anwendung im Aufruf von SetupSetThreadLogToken ein systemdefiniertes Protokolltoken wie LOGTOKEN_SETUPAPI_APPLOG verwenden.

  Hinweis Wenn der Protokollkontext mithilfe eines systemdefinierten Protokolltokens festgelegt wird, schreiben nachfolgende Aufrufe einer SetupAPI-Protokollierungsfunktion aus diesem Protokollkontext Protokolleinträge in das Installationstextprotokoll, die nicht Teil eines Textprotokollabschnitts sind.

• Wenn ein Klasseninstallationsprogramm oder ein Co-Installer einen neuen Thread startet, kann der Installer den Protokollkontext für diesen Thread so festlegen, dass er mit dem übergeordneten Thread übereinstimmt. Dies geschieht auf folgende Weise:

  1. Bevor der übergeordnete Thread den neuen Thread startet, ruft er das aktuelle Protokolltoken ab, indem SetupGetThreadLogToken aufgerufen wird.
  2. Der übergeordnete Thread startet den neuen Thread und übergibt das aktuelle Protokolltoken über eine implementierungsspezifische Methode, z. B. das Speichern des Tokens in einer globalen Variablen.
  3. Der neue Thread ruft SetupSetThreadLogToken mit dem aktuellen Protokolltoken auf. Daher "erbt" der neue Thread den Protokollkontext des übergeordneten Threads.

  Hinweis Wenn ein Thread eines Klasseninstallationsprogramms oder eines Co-Installers den Protokollkontext mithilfe dieser Methode festlegt, schreiben nachfolgende Aufrufe einer SetupAPI-Protokollierungsfunktion aus diesem Protokollkontext Protokolleinträge in das Installationstextprotokoll, das Teil eines Textprotokollabschnitts sein kann. Dies geschieht nur, wenn durch den SetupAPI-Installationsvorgang, der das Installationsprogramm aufgerufen hat, ein Textprotokollabschnitt eingerichtet wurde.

Im Folgenden wird ein Beispiel für einen Aufruf von SetupSetThreadLogToken angezeigt, der den Protokollkontext des aktuellen Threads auf das Geräteinstallationstextprotokoll (SetupAPI.app.log) festlegt, indem das systemdefinierte Protokolltoken von LOGTOKEN_SETUPAPI_APPLOG angegeben wird. Ein nachfolgender Aufruf einer SetupAPI-Protokollierungsfunktion , die diesen Protokollkontext verwendet, würde den Protokolleintrag in das Textprotokoll der Geräteinstallation schreiben, jedoch nicht als Teil eines Textprotokollabschnitts.

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

Abrufen eines Protokolltokens für einen Thread

Die SetupGetThreadLogToken-Funktion ruft ein Protokolltoken für den Thread ab, aus dem diese Funktion aufgerufen wurde.

Ein Klasseninstallationsprogramm kann beispielsweise SetupGetThreadLogToken aufrufen, um das Protokolltoken abzurufen, das für den SetupAPI-Vorgang gilt, der das Klasseninstallationsprogramm aufgerufen hat. Das Klasseninstallationsprogramm kann dann dieses abgerufene Protokolltoken verwenden, um Einträge im Textprotokoll zu protokollieren, das für den entsprechenden SetupAPI-Vorgang gilt.

Hinweis Wenn der Protokollkontext eines Threads zuvor nicht durch einen Aufruf von SetupSetThreadLogToken festgelegt wurde, gibt ein Aufruf von SetupGetThreadLogToken ein Protokolltoken mit dem Wert LOGTOKEN_UNSPECIFIED zurück.

Im Folgenden ist ein Beispiel für einen Aufruf von SetupGetThreadLogToken aufgeführt, der das Protokolltoken für den aktuellen Thread abruft.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();