ReportEventA-Funktion (winbase.h)
Schreibt einen Eintrag am Ende des angegebenen Ereignisprotokolls.
Syntax
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
);
Parameter
[in] hEventLog
Ein Handle zum Ereignisprotokoll. Die RegisterEventSource-Funktion gibt diesen Handle zurück.
Ab Windows XP mit SP2 kann dieser Parameter kein Handle für das Sicherheitsprotokoll sein. Verwenden Sie die Funktion AuthzReportSecurityEvent, um ein Ereignis in das Sicherheitsprotokoll zu schreiben.
[in] wType
Der Typ des zu protokollierenden Ereignisses. Dieser Parameter kann einen der folgenden Werte annehmen.
Weitere Informationen zu Ereignistypen finden Sie unter Ereignistypen.
[in] wCategory
Die Ereigniskategorie. Dies ist quellspezifische Informationen; die Kategorie kann einen beliebigen Wert haben. Weitere Informationen finden Sie unter Ereigniskategorien.
[in] dwEventID
Der Ereignisbezeichner. Der Ereignisbezeichner gibt den Eintrag in der Nachrichtendatei an, die der Ereignisquelle zugeordnet ist. Weitere Informationen finden Sie unter Ereignisbezeichner.
[in] lpUserSid
Ein Zeiger auf den Sicherheitsbezeichner des aktuellen Benutzers. Dieser Parameter kann NULL sein, wenn der Sicherheitsbezeichner nicht erforderlich ist.
[in] wNumStrings
Die Anzahl der eingefügten Zeichenfolgen im Array, auf die der lpStrings-Parameter verweist. Ein Wert von Null gibt an, dass keine Zeichenfolgen vorhanden sind.
[in] dwDataSize
Die Anzahl der Bytes von ereignisspezifischen unformatierten (binären) Daten, die in das Protokoll geschrieben werden sollen. Wenn dieser Parameter null ist, ist keine ereignisspezifischen Daten vorhanden.
[in] lpStrings
Ein Zeiger auf einen Puffer, der ein Array mit null-beendeten Zeichenfolgen enthält, die in die Nachricht zusammengeführt werden, bevor Ereignisanzeige die Zeichenfolge dem Benutzer anzeigt. Dieser Parameter muss ein gültiger Zeiger (oder NULL) sein, auch wenn wNumStrings null ist. Jede Zeichenfolge ist auf 31.839 Zeichen beschränkt.
Vor Windows Vista: Jede Zeichenfolge ist auf 32K-Zeichen beschränkt.
[in] lpRawData
Ein Zeiger auf den Puffer, der die Binärdaten enthält. Dieser Parameter muss ein gültiger Zeiger (oder NULL) sein, auch wenn der dwDataSize-Parameter null ist.
Rückgabewert
Wenn die Funktion erfolgreich verläuft, ist der Rückgabewert nonzero, der angibt, dass der Eintrag in das Protokoll geschrieben wurde.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Rufen Sie getLastError auf, um erweiterte Fehlerinformationen abzurufen, die einen der folgenden erweiterten Fehlercodes zurückgibt.
| Fehlercode | Bedeutung |
|---|---|
|
Einer der Parameter ist ungültig.
Dieser Fehler wird unter Windows Server 2003 zurückgegeben, wenn die zu protokollierten Nachrichtendaten zu groß sind. Dieser Fehler wird vom RPC-Server unter Windows Server 2003 zurückgegeben, wenn der dwDataSize-Parameter größer als 261.991 (0x3ff67) ist. |
|
Unzureichende Speicherressourcen sind verfügbar, um den Vorgang abzuschließen. |
|
Die Arraygrenzen sind ungültig.
Dieser Fehler wird zurückgegeben, wenn die zu protokollierten Nachrichtendaten zu groß sind. Bei Windows Vista und höher wird dieser Fehler zurückgegeben, wenn der dwDataSize-Parameter größer als 61.440 (0xf000) ist. |
|
Der Stub hat schlechte Daten erhalten.
Dieser Fehler wird unter Windows XP zurückgegeben, wenn die zu protokollierten Nachrichtendaten zu groß sind. Dieser Fehler wird vom RPC-Server unter Windows XP zurückgegeben, wenn der dwDataSize-Parameter größer als 262.143 (0x3ffff) ist. |
|
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Diese Funktion wird verwendet, um ein Ereignis zu protokollieren. Der Eintrag wird am Ende des konfigurierten Protokolls für die vom hEventLog-Parameter identifizierte Quelle geschrieben. Die ReportEvent-Funktion fügt die Zeit, die Länge des Eintrags und die Offsets hinzu, bevor der Eintrag im Protokoll gespeichert wird. Um die Funktion zum Hinzufügen des Benutzernamens zu aktivieren, müssen Sie die SID des Benutzers im lpUserSid-Parameter angeben.
Es gibt unterschiedliche Größenbeschränkungen für die Größe der Nachrichtendaten, die abhängig von der Version von Windows protokolliert werden können, die vom Client verwendet wird, auf dem die Anwendung ausgeführt wird, und den Server, auf dem die Nachricht protokolliert wird. Der Server wird durch den lpUNCServerName-Parameter bestimmt, der an die RegisterEventSource-Funktion übergeben wird. Unterschiedliche Fehler werden zurückgegeben, wenn der Größengrenzwert überschritten wird, der von der Version von Windows abhängt.
Wenn die protokollierte Zeichenfolge %n enthält, wobei n ein ganzzahliger Wert ist (z. B. %1), behandelt die Ereignisanzeige sie als Einfügezeichenfolge. Da eine IPv6-Adresse diese Zeichensequenz enthalten kann, müssen Sie einen Formatbezeichner (! S!) um eine Ereignismeldung zu protokollieren, die eine IPv6-Adresse enthält. Dieser Bezeichner weist den Formatierungscode an, die Zeichenfolge buchstäblich zu verwenden und keine weiteren Erweiterungen auszuführen (z. B. "meine IPv6-Adresse lautet: %1! S!").
Beispiele
Ein Beispiel finden Sie unter Melden eines Ereignisses.
Hinweis
Der Winbase.h-Header definiert ReportEvent als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der codierungsneutralen Aliase mit Code, der nicht codierungsneutral ist, kann zu Übereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbase.h (enthalten Windows.h) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |