共用方式為

呼叫 SetupWriteTextLogError

  • 發行項

SetupWriteTextLogError 會將 SetupAPI 特定錯誤或 Win32 錯誤的相關資訊寫入 SetupAPI 文字記錄檔。 SetupWriteTextLogError 會將兩個連續專案寫入文字記錄檔：第一個專案包含與 SetupWriteTextLog 所寫入格式相同的資訊，而第二個專案會記錄對應的錯誤碼和使用者易記的錯誤描述。

若要呼叫 SetupWriteTextLogError，應用程式會提供用來呼叫 SetupWriteTextLog 的相同資訊，此外，還會提供 SetupAPI 特定錯誤或 Win32 錯誤的值。

SetupWriteTextLogError 會以下列格式寫入第一個記錄專案：

entry_prefix time_stamp類別 ****indentation formatted-message

SetupWriteTextLogError 會以下列格式寫入第二個記錄專案：

entry_prefix time_stamp類別 **縮排**Error：error-number error-description

其中：

  • entry_prefix、時間戳記、類別、縮排和格式化訊息欄位與文字記錄區段本文格式中所述的欄位相同。

  • 錯誤號碼欄位包含錯誤號碼。

  • error-description欄位包含錯誤的使用者易記描述。

下列範例示範應用程式通常如何呼叫 SetupWriteTextLogError ，以記錄有關文字記錄檔中錯誤的資訊。 範例中使用的錯誤是系統啟動錯誤。 應用程式會呼叫 SetupWriteTextLogError，並提供下列參數值：

  • LogToken 是透過呼叫 SetupGetThreadLogToken 取得的記錄權杖值，或是記錄權杖中所述的其中一個系統定義記錄 權杖值。

  • 類別 設定為 TXTLOG_VENDOR，表示記錄專案是由廠商提供的應用程式所建立。 事件類別目錄會在 啟用文字記錄檔的事件類別中說明。

  • LogFlags 設定為 TXTLOG_ERROR。 此範例不包含時間戳記或變更縮排深度。 目前的縮排深度先前設定為五個單空格文字空間。 如需如何變更縮排深度的資訊，請參閱 撰寫縮排記錄專案。 設定 文字記錄檔的事件層級中會說明事件層級。

  • Error 設定為 Win32 錯誤碼的值，ERROR_SERVICE_ALREADY_RUNNING。 此錯誤碼的十進位值為 1056。

  • MessageStr 設定為 TEXT (「啟動服務：無法啟動服務 'SomeService'」) 。

  • 未提供逗號分隔參數清單。

LogToken、Category和LogFlags參數會以與這些參數相同的方式影響SetupWriteTextLogError的作業，會影響SetupWriteTextLog的作業。

下列程式碼會呼叫 SetupWriteTextLogError 來寫入此範例的記錄專案：

//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'"),);

如果已啟用TXTLOG_VENDOR事件類別目錄，而且已針對文字記錄檔設定TXTLOG_ERROR事件層級，則此程式碼會在文字記錄中建立專案，其格式如下：

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

請注意 ，SetupWriteTextLogError 提供字串「服務實例已在執行中」，以描述值為 1056 的 Win32 錯誤。