SetupWriteTextLog-Funktion (setupapi.h)

Artikel
08/26/2023

Die SetupWriteTextLog-Funktion schreibt einen Protokolleintrag in ein SetupAPI-Textprotokoll.

Syntax

WINSETUPAPI VOID SetupWriteTextLog(
  [in] SP_LOG_TOKEN LogToken,
  [in] DWORD        Category,
  [in] DWORD        Flags,
  [in] PCSTR        MessageStr,
       ...          
);

Parameter

[in] LogToken

Ein Protokolltoken , das entweder ein systemdefiniertes Protokolltoken ist oder von SetupGetThreadLogToken zurückgegeben wurde.

[in] Category

Ein DWORD-typisierter Wert, der die Ereigniskategorie für den Protokolleintrag angibt. Die Ereigniskategorien, die für einen Protokolleintrag angegeben werden können, sind identisch mit denen, die für ein Textprotokoll aktiviert werden können. Eine Liste der Ereigniskategorien finden Sie unter Aktivieren von Ereigniskategorien für ein SetupAPI-Textprotokoll.

[in] Flags

Ein DWORD-typisierter Wert, der ein bitweises OR von Flagwerten ist, die Folgendes angeben:

Die Ereignisebene für den Protokolleintrag. Die Ereignisebenen, die für einen Protokolleintrag angegeben werden können, sind identisch mit denen, die für ein Textprotokoll aktiviert werden können. Eine Liste der Flags auf Ereignisebene finden Sie unter Festlegen der Ereignisebene für ein SetupAPI-Textprotokoll.
Gibt an, ob ein Zeitstempel in den Protokolleintrag eingeschlossen werden soll. Der Zeitstempelflagwert ist TXTLOG_TIMESTAMP.
Die Änderung, falls vorhanden, an der Einzugstiefe des Abschnitts und des aktuellen Protokolleintrags. Informationen zur Verwendung der Einzugsflags finden Sie unter Schreiben von Protokolleinträgen mit Einzug.

[in] MessageStr

Ein Zeiger auf eine NULL-beendete konstante Zeichenfolge, die eine printf-kompatible Formatzeichenfolge enthält, die die formatierte Nachricht angibt, die in den Protokolleintrag aufgenommen werden soll. Die durch Trennzeichen getrennte Parameterliste, die auf MessageStr folgt, muss mit den Formatbezeichnern in der Formatzeichenfolge übereinstimmen.

...

Eine durch Trennzeichen getrennte Parameterliste, die mit den Formatbezeichnern in der von MessageStr bereitgestellten Formatzeichenfolge übereinstimmt.

Rückgabewert

Keine

Bemerkungen

Wenn der Wert von LogToken durch einen Aufruf von SetupGetThreadLogToken zurückgegeben wurde und der entsprechende Textprotokollabschnitt gefunden werden kann, schreibt SetupWriteTextLog den Protokolleintrag in diesen Textprotokollabschnitt. Wenn SetupWriteTextLog den Abschnitt nicht finden kann, schreibt SetupWriteTextLog den Protokolleintrag in das entsprechende Textprotokoll, schließt den Protokolleintrag jedoch nicht in einen Abschnitt ein.

Wenn der Wert von LogToken eines der systemdefinierten Protokolltoken ist, die in der folgenden Tabelle aufgeführt sind, führt SetupWriteTextLog den Schreibvorgang aus, der für dieses Protokolltoken angegeben ist.

Systemdefiniertes Protokolltoken	Schreibvorgang
LOGTOKEN_NOLOG	Der Protokolleintrag wird nicht in ein Textprotokoll geschrieben.
LOG_TOKEN_UNSPECIFIED	Der Protokolleintrag wird in das Textprotokoll der Anwendungsinstallation geschrieben. Der Protokolleintrag ist nicht in einem Textprotokollabschnitt enthalten.
LOGTOKEN_SETUPAPI_APPLOG	Der Protokolleintrag wird in das Textprotokoll der Anwendungsinstallation geschrieben. Der Protokolleintrag ist nicht in einem Textprotokollabschnitt enthalten.
LOGTOKEN_SETUPAPI_DEVLOG	Der Protokolleintrag wird in das Textprotokoll für die Geräteinstallation geschrieben. Der Protokolleintrag ist nicht in einem Textprotokollabschnitt enthalten.

Hinweis Wenn Sie den Wert von LogToken auf eines der systemdefinierten Protokolltoken festlegen, ändert sich der Wert des aktuellen Protokolltokens für den Thread nicht.

Darüber hinaus schreibt SetupWriteTextLog keinen Protokolleintrag, wenn einer der folgenden Punkte zutrifft:

Die für das Textprotokoll festgelegte Ereignisebene ist kleiner als die Ereignisebene, die für den Protokolleintrag angegeben wird.
Die Ereigniskategorie für den Protokolleintrag ist für das Textprotokoll nicht aktiviert. Weitere Informationen zu Ereigniskategorien finden Sie unter Aktivieren von Ereigniskategorien für ein Textprotokoll.

Die maximale Länge eines Protokolleintrags in Zeichen beträgt 336.

Um Informationen zu einem SetupAPI-spezifischen Fehler oder einem Win32-Fehler in einem Textprotokoll zu schreiben, kann eine Anwendung SetupWriteTextLogError verwenden.

Allgemeine Informationen zum Schreiben von Protokolleinträgen in den SetupAPI-Textprotokollen finden Sie unter SetupAPI-Protokollierung (Windows Vista und höher).

Weitere Informationen zum Vorgang von SetupWriteTextLog finden Sie unter Aufrufen von SetupWriteTextLog.

Weitere Informationen zu Protokolltoken finden Sie unter Protokolltoken.

Weitere Informationen zur Verwendung von Protokolltoken finden Sie unter Festlegen und Abrufen eines Protokolltokens für einen Thread.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und späteren Windows-Versionen.
Zielplattform	Desktop
Kopfzeile	setupapi.h (schließen Sie Setupapi.h ein)
Bibliothek	Setupapi.lib
APIs	ext-ms-win-setupapi-logging-l1-1-0 (eingeführt in Windows 8)

Weitere Informationen

SetupGetThreadLogToken

SetupWriteTextLogError

Freigeben über