[EVTLIB]: Allow specifying a memory allocation tag when freeing the allocated buffers...
[reactos.git] / reactos / sdk / lib / evtlib / evtlib.h
1 /*
2 * PROJECT: ReactOS EventLog File Library
3 * LICENSE: GPL - See COPYING in the top level directory
4 * FILE: sdk/lib/evtlib/evtlib.h
5 * PURPOSE: Provides functionality for reading and writing
6 * EventLog files in the NT <= 5.2 (.evt) format.
7 * PROGRAMMERS: Copyright 2005 Saveliy Tretiakov
8 * Michael Martin
9 * Hermes Belusca-Maito
10 */
11
12 #ifndef __EVTLIB_H__
13 #define __EVTLIB_H__
14
15 #pragma once
16
17 /* PSDK/NDK Headers */
18 // #define WIN32_NO_STATUS
19 // #include <windef.h>
20 // #include <winbase.h>
21 // #include <winnt.h>
22
23 #define NTOS_MODE_USER
24 #include <ndk/rtlfuncs.h>
25
26 #ifndef ROUND_DOWN
27 #define ROUND_DOWN(n, align) (((ULONG)n) & ~((align) - 1l))
28 #endif
29
30 #ifndef ROUND_UP
31 #define ROUND_UP(n, align) ROUND_DOWN(((ULONG)n) + (align) - 1, (align))
32 #endif
33
34 /*
35 * Our file format will be compatible with NT's
36 */
37 #define MAJORVER 1
38 #define MINORVER 1
39 #define LOGFILE_SIGNATURE 0x654c664c // "LfLe"
40
41 /*
42 * Flags used in the logfile header
43 */
44 #define ELF_LOGFILE_HEADER_DIRTY 1
45 #define ELF_LOGFILE_HEADER_WRAP 2
46 #define ELF_LOGFILE_LOGFULL_WRITTEN 4
47 #define ELF_LOGFILE_ARCHIVE_SET 8
48
49 /*
50 * On-disk event log structures (log file header, event record and EOF record).
51 * NOTE: Contrary to what MSDN claims, both the EVENTLOGHEADER and EVENTLOGEOF
52 * structures are absent from winnt.h .
53 */
54
55 #include <pshpack4.h> // pshpack1
56
57 // ELF_LOGFILE_HEADER
58 typedef struct _EVENTLOGHEADER
59 {
60 ULONG HeaderSize;
61 ULONG Signature;
62 ULONG MajorVersion;
63 ULONG MinorVersion;
64 ULONG StartOffset;
65 ULONG EndOffset;
66 ULONG CurrentRecordNumber;
67 ULONG OldestRecordNumber;
68 ULONG MaxSize;
69 ULONG Flags;
70 ULONG Retention;
71 ULONG EndHeaderSize;
72 } EVENTLOGHEADER, *PEVENTLOGHEADER;
73
74
75 /* Those flags and structure are defined in winnt.h */
76 #ifndef _WINNT_
77
78 /* EventType flags */
79 #define EVENTLOG_SUCCESS 0
80 #define EVENTLOG_ERROR_TYPE 1
81 #define EVENTLOG_WARNING_TYPE 2
82 #define EVENTLOG_INFORMATION_TYPE 4
83 #define EVENTLOG_AUDIT_SUCCESS 8
84 #define EVENTLOG_AUDIT_FAILURE 16
85
86 typedef struct _EVENTLOGRECORD
87 {
88 ULONG Length; /* Length of full record, including the data portion */
89 ULONG Reserved;
90 ULONG RecordNumber;
91 ULONG TimeGenerated;
92 ULONG TimeWritten;
93 ULONG EventID;
94 USHORT EventType;
95 USHORT NumStrings; /* Number of strings in the 'Strings' array */
96 USHORT EventCategory;
97 USHORT ReservedFlags;
98 ULONG ClosingRecordNumber;
99 ULONG StringOffset;
100 ULONG UserSidLength;
101 ULONG UserSidOffset;
102 ULONG DataLength; /* Length of the data portion */
103 ULONG DataOffset; /* Offset from beginning of record */
104 /*
105 * Length-varying data:
106 *
107 * WCHAR SourceName[];
108 * WCHAR ComputerName[];
109 * SID UserSid; // Must be aligned on a DWORD boundary
110 * WCHAR Strings[];
111 * BYTE Data[];
112 * CHAR Pad[]; // Padding for DWORD boundary
113 * ULONG Length; // Same as the first 'Length' member at the beginning
114 */
115 } EVENTLOGRECORD, *PEVENTLOGRECORD;
116
117 #endif // _WINNT_
118
119
120 // ELF_EOF_RECORD
121 typedef struct _EVENTLOGEOF
122 {
123 ULONG RecordSizeBeginning;
124 ULONG Ones;
125 ULONG Twos;
126 ULONG Threes;
127 ULONG Fours;
128 ULONG BeginRecord;
129 ULONG EndRecord;
130 ULONG CurrentRecordNumber;
131 ULONG OldestRecordNumber;
132 ULONG RecordSizeEnd;
133 } EVENTLOGEOF, *PEVENTLOGEOF;
134
135 #define EVENTLOGEOF_SIZE_FIXED (5 * sizeof(ULONG))
136 C_ASSERT(EVENTLOGEOF_SIZE_FIXED == FIELD_OFFSET(EVENTLOGEOF, BeginRecord));
137
138 #include <poppack.h>
139
140
141 typedef struct _EVENT_OFFSET_INFO
142 {
143 ULONG EventNumber;
144 ULONG EventOffset;
145 } EVENT_OFFSET_INFO, *PEVENT_OFFSET_INFO;
146
147 #define TAG_ELF ' flE'
148 #define TAG_ELF_BUF 'BflE'
149
150 struct _EVTLOGFILE;
151
152 typedef PVOID
153 (NTAPI *PELF_ALLOCATE_ROUTINE)(
154 IN SIZE_T Size,
155 IN ULONG Flags,
156 IN ULONG Tag
157 );
158
159 typedef VOID
160 (NTAPI *PELF_FREE_ROUTINE)(
161 IN PVOID Ptr,
162 IN ULONG Flags,
163 IN ULONG Tag
164 );
165
166 typedef NTSTATUS
167 (NTAPI *PELF_FILE_READ_ROUTINE)(
168 IN struct _EVTLOGFILE* LogFile,
169 IN PLARGE_INTEGER FileOffset,
170 OUT PVOID Buffer,
171 IN SIZE_T Length,
172 OUT PSIZE_T ReadLength OPTIONAL
173 );
174
175 typedef NTSTATUS
176 (NTAPI *PELF_FILE_WRITE_ROUTINE)(
177 IN struct _EVTLOGFILE* LogFile,
178 IN PLARGE_INTEGER FileOffset,
179 IN PVOID Buffer,
180 IN SIZE_T Length,
181 OUT PSIZE_T WrittenLength OPTIONAL
182 );
183
184 typedef NTSTATUS
185 (NTAPI *PELF_FILE_SET_SIZE_ROUTINE)(
186 IN struct _EVTLOGFILE* LogFile,
187 IN ULONG FileSize,
188 IN ULONG OldFileSize
189 );
190
191 typedef NTSTATUS
192 (NTAPI *PELF_FILE_FLUSH_ROUTINE)(
193 IN struct _EVTLOGFILE* LogFile,
194 IN PLARGE_INTEGER FileOffset,
195 IN ULONG Length
196 );
197
198 typedef struct _EVTLOGFILE
199 {
200 PELF_ALLOCATE_ROUTINE Allocate;
201 PELF_FREE_ROUTINE Free;
202 PELF_FILE_SET_SIZE_ROUTINE FileSetSize;
203 PELF_FILE_WRITE_ROUTINE FileWrite;
204 PELF_FILE_READ_ROUTINE FileRead;
205 PELF_FILE_FLUSH_ROUTINE FileFlush;
206
207 EVENTLOGHEADER Header;
208 ULONG CurrentSize; /* Equivalent to the file size, is <= MaxSize and can be extended to MaxSize if needed */
209 UNICODE_STRING FileName;
210 PEVENT_OFFSET_INFO OffsetInfo;
211 ULONG OffsetInfoSize;
212 ULONG OffsetInfoNext;
213 BOOLEAN ReadOnly;
214 } EVTLOGFILE, *PEVTLOGFILE;
215
216
217 NTSTATUS
218 NTAPI
219 ElfCreateFile(
220 IN OUT PEVTLOGFILE LogFile,
221 IN PUNICODE_STRING FileName OPTIONAL,
222 IN ULONG FileSize,
223 IN ULONG MaxSize,
224 IN ULONG Retention,
225 IN BOOLEAN CreateNew,
226 IN BOOLEAN ReadOnly,
227 IN PELF_ALLOCATE_ROUTINE Allocate,
228 IN PELF_FREE_ROUTINE Free,
229 IN PELF_FILE_SET_SIZE_ROUTINE FileSetSize,
230 IN PELF_FILE_WRITE_ROUTINE FileWrite,
231 IN PELF_FILE_READ_ROUTINE FileRead,
232 IN PELF_FILE_FLUSH_ROUTINE FileFlush); // What about Seek ??
233
234 NTSTATUS
235 NTAPI
236 ElfReCreateFile(
237 IN PEVTLOGFILE LogFile);
238
239 // NTSTATUS
240 // ElfClearFile(PEVTLOGFILE LogFile);
241
242 NTSTATUS
243 NTAPI
244 ElfBackupFile(
245 IN PEVTLOGFILE LogFile,
246 IN PEVTLOGFILE BackupLogFile);
247
248 NTSTATUS
249 NTAPI
250 ElfFlushFile(
251 IN PEVTLOGFILE LogFile);
252
253 VOID
254 NTAPI
255 ElfCloseFile( // ElfFree
256 IN PEVTLOGFILE LogFile);
257
258 NTSTATUS
259 NTAPI
260 ElfReadRecord(
261 IN PEVTLOGFILE LogFile,
262 IN ULONG RecordNumber,
263 OUT PEVENTLOGRECORD Record,
264 IN SIZE_T BufSize, // Length
265 OUT PSIZE_T BytesRead OPTIONAL,
266 OUT PSIZE_T BytesNeeded OPTIONAL);
267
268 NTSTATUS
269 NTAPI
270 ElfWriteRecord(
271 IN PEVTLOGFILE LogFile,
272 IN PEVENTLOGRECORD Record,
273 IN SIZE_T BufSize);
274
275 ULONG
276 NTAPI
277 ElfGetOldestRecord(
278 IN PEVTLOGFILE LogFile);
279
280 ULONG
281 NTAPI
282 ElfGetCurrentRecord(
283 IN PEVTLOGFILE LogFile);
284
285 ULONG
286 NTAPI
287 ElfGetFlags(
288 IN PEVTLOGFILE LogFile);
289
290 #if DBG
291 VOID PRINT_HEADER(PEVENTLOGHEADER Header);
292 #endif
293
294 #endif /* __EVTLIB_H__ */