Festlegen und Abrufen eines Protokolltokens für einen Thread

Die SetupAPI-Protokollierung unterstützt einen Mechanismus, der einen Protokollkontext für einen Thread festlegt. 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-Installationsprogramm aufruft. Das Installationsprogramm kann wiederum das Protokolltoken des aufrufenden Threads abrufen und dieses Token verwenden, um Protokolleinträge in das Textprotokoll und in den Abschnitt zu schreiben, der dem Protokollkontext des aufrufenden Threads zugeordnet ist.

Festlegen eines Protokolltokens für einen Thread

Die SetupSetThreadLogToken-Funktion legt ein Protokolltoken für den Thread fest, aus dem 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 innerhalb desselben Threads ausgeführt wird. Wenn der Protokollkontext für den Thread eingerichtet wird, sollte die Anwendung ein systemdefiniertes Protokolltoken verwenden, z. B. LOGTOKEN_SETUPAPI_APPLOG, im Aufruf von SetupSetThreadLogToken.

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

• Wenn ein Klasseninstallationsprogramm oder ein Co-Installer einen neuen Thread startet, kann das Installationsprogramm den Protokollkontext für diesen Thread so festlegen, dass er mit dem übergeordneten Thread übereinstimmt. Dabei gehen Sie folgendermaßen vor:

  1. Bevor der übergeordnete Thread den neuen Thread startet, ruft er das aktuelle Protokolltoken durch Aufrufen von SetupGetThreadLogToken ab.
  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, werden nachfolgende Aufrufe einer SetupAPI-Protokollierungsfunktion , die aus diesem Protokollkontext vorgenommen werden, Protokolleinträge in das Installationstextprotokoll schreiben, das Teil eines Textprotokollabschnitts sein kann. Dies geschieht nur, wenn ein Textprotokollabschnitt durch den SetupAPI-Installationsvorgang eingerichtet wurde, der das Installationsprogramm aufgerufen hat.

Nachfolgend sehen Sie ein Beispiel für einen Aufruf von SetupSetThreadLogToken , der den Protokollkontext des aktuellen Threads auf das Textprotokoll der Geräteinstallation (SetupAPI.app.log) festlegt, indem das systemdefinierte Protokolltoken von LOGTOKEN_SETUPAPI_APPLOG angegeben wird. Ein anschließender 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, von dem aus diese Funktion aufgerufen wurde.

Beispielsweise kann ein Klasseninstallationsprogramm SetupGetThreadLogToken aufrufen, um das Protokolltoken abzurufen, das für den SetupAPI-Vorgang gilt, der das Klasseninstallationsprogramm aufgerufen hat. Anschließend kann das Klasseninstallationsprogramm dieses abgerufene Protokolltoken zum Protokollieren von Einträgen im Textprotokoll verwenden, 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.

Nachfolgend sehen Sie ein Beispiel für einen Aufruf von SetupGetThreadLogToken , der das Protokolltoken für den aktuellen Thread abruft.

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();