Freigeben über

Aufrufen von SetupWriteTextLogError

  • Artikel

SetupWriteTextLogError schreibt Informationen zu einem SetupAPI-spezifischen Fehler oder einem Win32-Fehler in ein SetupAPI-Textprotokoll. SetupWriteTextLogError schreibt zwei aufeinanderfolgende Einträge in ein Textprotokoll: Der erste Eintrag enthält dieselben Informationen im gleichen Format wie das von SetupWriteTextLog geschriebene, und der zweite Eintrag protokolliert einen entsprechenden Fehlercode und eine benutzerfreundliche Beschreibung des Fehlers.

Um SetupWriteTextLogError aufzurufen, stellt eine Anwendung die gleichen Informationen bereit, die sie zum Aufrufen von SetupWriteTextLog bereitstellen würde, und stellt darüber hinaus den Wert eines SetupAPI-spezifischen Fehlers oder eines Win32-Fehlers bereit.

SetupWriteTextLogError schreibt den ersten Protokolleintrag im folgenden Format:

entry_prefix time_stamp Kategorie ****Einzüge formatierte Nachricht

SetupWriteTextLogError schreibt den zweiten Protokolleintrag im folgenden Format:

entry_prefix time_stamp Kategorie **Einzug **Error:error-number error-description

Hierbei gilt:

  • Die Felder entry_prefix, Zeitstempel, Kategorie, Einzug und formatierte Nachricht sind identisch mit denen, die unter Format eines Textprotokollabschnittstexts beschrieben werden.

  • Das Feld error-number enthält die Fehlernummer.

  • Das Feld error-description enthält eine benutzerfreundliche Beschreibung des Fehlers.

Das folgende Beispiel zeigt, wie eine Anwendung in der Regel SetupWriteTextLogError aufrufen kann, um Informationen zu einem Fehler in einem Textprotokoll zu protokollieren. Der im Beispiel verwendete Fehler ist ein Systemstartfehler. Die Anwendung ruft SetupWriteTextLogError auf und gibt die folgenden Parameterwerte an:

  • LogToken ist auf einen Protokolltokenwert festgelegt, der entweder durch Aufrufen von SetupGetThreadLogToken abgerufen wurde oder einer der systemdefinierte Protokolltokenwerte ist, die unter Protokolltoken beschrieben werden.

  • Kategorie ist auf TXTLOG_VENDOR festgelegt, was angibt, dass der Protokolleintrag von einer vom Anbieter bereitgestellten Anwendung erstellt wird. Ereigniskategorien werden unter Aktivieren von Ereigniskategorien für ein Textprotokoll beschrieben.

  • LogFlags ist auf TXTLOG_ERROR festgelegt. In diesem Beispiel wird kein Zeitstempel eingeschlossen oder die Einzugstiefe geändert. Die aktuelle Einzugstiefe wurde zuvor auf fünf Monospace-Texträume festgelegt. Informationen zum Ändern der Einzugstiefe finden Sie unter Schreiben von Eingezogenen Protokolleinträgen. Ereignisebenen werden unter Festlegen der Ereignisebene für ein Textprotokoll beschrieben.

  • Error wird auf den Wert des Win32-Fehlercodes festgelegt, ERROR_SERVICE_ALREADY_RUNNING. Der Dezimalwert dieses Fehlercodes ist 1056.

  • MessageStr ist auf TEXT ("Startdienst: Fehler beim Starten des Diensts 'SomeService'") festgelegt.

  • Eine durch Trennzeichen getrennte Parameterliste wird nicht bereitgestellt.

Die Parameter LogToken, Category und LogFlags wirken sich auf den Vorgang von SetupWriteTextLogError auf die gleiche Weise aus, wie diese Parameter den Vorgang von SetupWriteTextLog beeinflussen.

Der folgende Code ruft SetupWriteTextLogError auf, um den Protokolleintrag für dieses Beispiel zu schreiben:

//The LogToken value was previously returned by call to
//SetupGetThreadLogToken or one of the system-defined log token values
DWORD Category = TXTLOG_VENDOR; 
DWORD Flags = TXTLOG_ERROR ;
DWORD ErrorCode = 1056; // The corresponding Win32 error code

SetupWriteTextLog(LogToken, Category, Flags, ErrorCode, TEXT("Start Service: Failed to start service 'SomeService'"),);

Wenn die TXTLOG_VENDOR Ereigniskategorie aktiviert ist und die TXTLOG_ERROR Ereignisebene für das Textprotokoll festgelegt ist, erstellt dieser Code einen Eintrag im Textprotokoll, der wie folgt formatiert wird:

!!!     :  Start Service: Failed to start service 'SomeService' 
!!!   :  Error 1056: An instance of the service is already running.

Beachten Sie, dass SetupWriteTextLogError die Zeichenfolge "Ein instance des Diensts wird bereits ausgeführt." zur Beschreibung des Win32-Fehlers mit dem Wert 1056 bereitstellt.