ReportEventA 函式 (winbase.h)
在指定的事件記錄檔結尾寫入專案。
語法
BOOL ReportEventA(
[in] HANDLE hEventLog,
[in] WORD wType,
[in] WORD wCategory,
[in] DWORD dwEventID,
[in] PSID lpUserSid,
[in] WORD wNumStrings,
[in] DWORD dwDataSize,
[in] LPCSTR *lpStrings,
[in] LPVOID lpRawData
);
參數
[in] hEventLog
事件記錄檔的句柄。 RegisterEventSource 函式會傳回這個句柄。
從具有SP2的 Windows XP 開始,此參數不能是 安全性 記錄檔的句柄。 若要將事件寫入 安全性 記錄檔,請使用 AuthzReportSecurityEvent 函式。
[in] wType
要記錄的事件類型。 此參數可以是下列其中一個值。
如需事件類型的詳細資訊,請參閱 事件類型。
[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,這會傳回下列其中一個擴充錯誤碼。
錯誤碼 | 意義 |
---|---|
|
其中一個參數無效。
如果要記錄的訊息數據太大,則會在 Windows Server 2003 上傳回此錯誤。 如果 dwDataSize 參數大於 261,991 (0x3ff67) ,則 Windows Server 2003 上的 RPC 伺服器會傳回此錯誤。 |
|
記憶體資源不足,無法完成作業。 |
|
陣列界限無效。
如果要記錄的訊息數據太大,就會傳回此錯誤。 在 Windows Vista 和更新版本上,如果 dwDataSize 參數大於 61,440 (0xf000) ,就會傳回此錯誤。 |
|
存根收到不正確的數據。
如果要記錄的訊息數據太大,則會在 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 |