ReportEventW-Funktion (winbase.h)
Schreibt einen Eintrag am Ende des angegebenen Ereignisprotokolls.
Syntax
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
);
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 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 sind quellenspezifische 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 die Sicherheits-ID des aktuellen Benutzers. Dieser Parameter kann NULL sein, wenn die Sicherheits-ID nicht erforderlich ist.
[in] wNumStrings
Die Anzahl der Einfügezeichenfolgen im Array, auf das der lpStrings-Parameter verweist. Der Wert 0 (null) gibt an, dass keine Zeichenfolgen vorhanden sind.
[in] dwDataSize
Die Anzahl der Bytes der ereignisspezifischen Rohdaten (Binärdaten), 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 NULL-beendeten Zeichenfolgen enthält, die mit der 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 32.000 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 ist, ist der Rückgabewert ungleich null, was angibt, dass der Eintrag in das Protokoll geschrieben wurde.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf, wodurch einer der folgenden erweiterten Fehlercodes zurückgegeben wird.
| Fehlercode | Bedeutung |
|---|---|
|
Einer der Parameter ist ungültig.
Dieser Fehler wird unter Windows Server 2003 zurückgegeben, wenn die zu protokollierenden 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. |
|
Es sind unzureichende Arbeitsspeicherressourcen verfügbar, um den Vorgang abzuschließen. |
|
Die Arraygrenzen sind ungültig.
Dieser Fehler wird zurückgegeben, wenn die zu protokollierenden 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 fehlerhafte Daten empfangen.
Dieser Fehler wird unter Windows XP zurückgegeben, wenn die zu protokollierenden 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 Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Diese Funktion wird verwendet, um ein Ereignis zu protokollieren. Der Eintrag wird an das Ende des konfigurierten Protokolls für die Quelle geschrieben, die durch den hEventLog-Parameter identifiziert wird. 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 im LpUserSid-Parameter angeben.
Es gibt unterschiedliche Größenbeschränkungen für die Größe der Nachrichtendaten, die abhängig von der Windows-Version protokolliert werden können, die sowohl vom Client, auf dem die Anwendung ausgeführt wird, als auch vom Server, auf dem die Nachricht protokolliert wird, verwendet wird. Der Server wird durch den parameter lpUNCServerName bestimmt, der an die RegisterEventSource-Funktion übergeben wird. Bei Überschreitung des Größenlimits, die von der Windows-Version abhängen, werden verschiedene Fehler zurückgegeben.
Wenn die Zeichenfolge, die Sie protokollieren, %n enthält, wobei n ein ganzzahliger Wert ist (z. B. %1), behandelt die Ereignisanzeige ihn als Einfügezeichenfolge. Da eine IPv6-Adresse diese Zeichenfolge enthalten kann, müssen Sie einen Formatbezeichner (! S!) , um eine Ereignismeldung zu protokollieren, die eine IPv6-Adresse enthält. Dieser Spezifizierer weist den Formatierungscode an, die Zeichenfolge wörtlich zu verwenden und keine weiteren Erweiterungen durchzuführen (z. B. "Meine IPv6-Adresse ist: %1! S!").
Beispiele
Ein Beispiel finden Sie unter Melden eines Ereignisses.
Hinweis
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 |
|---|---|
| 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 (Windows.h einschließen) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |