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 für das Ereignisprotokoll. Die RegisterEventSource--Funktion gibt dieses Handle zurück.
Ab Windows XP mit SP2 kann dieser Parameter kein Handle für das Security-Protokoll sein. Um ein Ereignis in das Security-Protokoll zu schreiben, verwenden Sie die AuthzReportSecurityEvent--Funktion.
[in] wType
Der Typ des zu protokollierenden Ereignisses. Dieser Parameter kann einer der folgenden Werte sein:
Weitere Informationen zu Ereignistypen finden Sie unter Ereignistypen.
[in] wCategory
Die Ereigniskategorie. Dies sind quellspezifische Informationen; die Kategorie einen beliebigen Wert aufweisen kann. 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- werden, wenn der Sicherheitsbezeichner nicht erforderlich ist.
[in] wNumStrings
Die Anzahl der einzufügenden Zeichenfolgen im Array, auf die durch den parameter lpStrings verwiesen wird. Ein Wert von Null gibt an, dass keine Zeichenfolgen vorhanden sind.
[in] dwDataSize
Die Anzahl der Bytes von ereignisspezifischen rohen (binären) Daten, die in das Protokoll geschrieben werden sollen. Wenn dieser Parameter null ist, sind keine ereignisspezifischen Daten vorhanden.
[in] lpStrings
Ein Zeiger auf einen Puffer, der ein Array von mit Null beendeten Zeichenfolgen enthält, die mit der Nachricht zusammengeführt werden, bevor die Ereignisanzeige die Zeichenfolge für den 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 32 KB 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 ist, ist der Rückgabewert ungleich Null, der angibt, dass der Eintrag in das Protokoll geschrieben wurde.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie zum Abrufen erweiterter Fehlerinformationen GetLastErrorauf, der eine 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 Arbeitsspeicherressourcen 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. Unter 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. |
Bemerkungen
Diese Funktion wird verwendet, um ein Ereignis zu protokollieren. Der Eintrag wird am Ende des konfigurierten Protokolls für die durch den 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. Damit die Funktion den Benutzernamen hinzufügen kann, müssen Sie die SID des Benutzers in der 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 dem Server, auf dem die Nachricht protokolliert wird. Der Server wird durch den lpUNCServerName Parameter bestimmt, der an die RegisterEventSource--Funktion übergeben wird. Es werden verschiedene Fehler zurückgegeben, wenn der Größengrenzwert überschritten wird, der von der Windows-Version abhängt.
Wenn die von Ihnen protokollierte Zeichenfolge %nenthält, wobei n ein ganzzahliger Wert ist (z. B. %1), behandelt die Ereignisanzeige sie als Einfügezeichenfolge. Da eine IPv6-Adresse diese Zeichenfolge enthalten kann, müssen Sie einen Formatbezeichner (! S!) zum Protokollieren einer Ereignisnachricht, 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 Ereignis-.
Anmerkung
Der winbase.h-Header definiert ReportEvent als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 Professional [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winbase.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |