reportEventW 函式 (winbase.h)

發行項
03/13/2024

在指定的事件記錄檔結尾寫入專案。

語法

BOOL ReportEventW(
  [in] HANDLE  hEventLog,
  [in] WORD    wType,
  [in] WORD    wCategory,
  [in] DWORD   dwEventID,
  [in] PSID    lpUserSid,
  [in] WORD    wNumStrings,
  [in] DWORD   dwDataSize,
  [in] LPCWSTR *lpStrings,
  [in] LPVOID  lpRawData
);

參數

[in] hEventLog

事件記錄檔的句柄。 RegisterEventSource 函式會傳回這個句柄。

從具有SP2的 Windows XP 開始，此參數不能是 安全性 記錄檔的句柄。若要將事件寫入 安全性 記錄檔，請使用 AuthzReportSecurityEvent 函式。

[in] wType

要記錄的事件類型。此參數可以是下列其中一個值。

值	意義
EVENTLOG_SUCCESS 0x0000	資訊事件
EVENTLOG_AUDIT_FAILURE 0x0010	失敗稽核事件
EVENTLOG_AUDIT_SUCCESS 0x0008	成功稽核事件
EVENTLOG_ERROR_TYPE 0x0001	錯誤事件
EVENTLOG_INFORMATION_TYPE 0x0004	資訊事件
EVENTLOG_WARNING_TYPE 0x0002	警告事件

如需事件類型的詳細資訊，請參閱事件類型。

[in] wCategory

事件類別目錄。這是來源特定資訊;類別可以有任何值。如需詳細資訊，請參閱事件類別。

[in] dwEventID

事件識別項。事件標識子會指定與事件來源相關聯的訊息檔中的專案。如需詳細資訊，請參閱事件標識符。

[in] lpUserSid

目前使用者安全性標識碼的指標。如果不需要安全性標識碼，此參數可以是 NULL 。

[in] wNumStrings

lpStrings 參數指向之陣列中的插入字串數目。值為零表示沒有字串存在。

[in] dwDataSize

要寫入記錄檔的事件特定原始 (二進位) 位元元組數目。如果此參數為零，則沒有任何事件特定的數據存在。

[in] lpStrings

緩衝區的指標，其中包含在事件檢視器向用戶顯示字串之前，合併至訊息的 Null 終止字串陣列。即使 wNumStrings 為零，此參數必須是有效的指標 (或 NULL) 。每個字串限制為31,839個字元。

在 Windows Vista 之前： 每個字串限制為32K個字元。

[in] lpRawData

緩衝區的指標，其中包含二進位數據。此參數必須是有效的指標 (或 NULL) ，即使 dwDataSize 參數為零也一樣。

傳回值

如果函式成功，則傳回值為非零，表示專案已寫入記錄。

如果此函式失敗，則傳回值為零。若要取得擴充錯誤資訊，請呼叫 GetLastError，這會傳回下列其中一個擴充錯誤碼。

錯誤碼	意義
ERROR_INVALID_PARAMETER	其中一個參數無效。如果要記錄的訊息數據太大，則會在 Windows Server 2003 上傳回此錯誤。如果 dwDataSize 參數大於 261,991 (0x3ff67) ，則 Windows Server 2003 上的 RPC 伺服器會傳回此錯誤。
ERROR_NOT_ENOUGH_MEMORY	記憶體資源不足，無法完成作業。
RPC_S_INVALID_BOUND	陣列界限無效。如果要記錄的訊息數據太大，就會傳回此錯誤。在 Windows Vista 和更新版本上，如果 dwDataSize 參數大於 61,440 (0xf000) ，就會傳回此錯誤。
RPC_X_BAD_STUB_DATA	存根收到不正確的數據。如果要記錄的訊息數據太大，則會在 Windows XP 上傳回此錯誤。如果 dwDataSize 參數大於 262,143 (0x3ffff) ，則 Windows XP 上的 RPC 伺服器會傳回此錯誤。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

此函式可用來記錄事件。專案會寫入 hEventLog 參數所識別來源的已設定記錄檔結尾。 ReportEvent 函式會新增時間、專案的長度和位移，再將專案儲存在記錄檔中。若要讓函式新增用戶名稱，您必須在 lpUserSid 參數中提供使用者的 SID。

根據執行應用程式所在的用戶端所使用的 Windows 版本，以及記錄訊息的伺服器，訊息數據的大小有不同的大小限制。伺服器是由傳遞至 RegisterEventSource 函式的 lpUNCServerName 參數所決定。當超過視 Windows 版本而定的大小限制時，會傳回不同的錯誤。

如果您記錄的字串包含 %n，其中 n 是整數值 (，例如 %1) ，則事件查看器會將它視為插入字串。因為 IPv6 位址可以包含這個字元序列，所以您必須提供格式規範 (！S！) 記錄包含 IPv6 位址的事件訊息。此規範會指示格式化程式代碼以常值方式使用字串，而不會執行任何進一步的擴充 (，例如：「我的 IPv6 位址是： %1！S!") 。

範例

如需範例，請參閱報告事件。

注意

winbase.h 標頭會將 ReportEvent 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Advapi32.lib
Dll	Advapi32.dll