EventLog Category

The functions in the EventLog category manage the event log and provide a mechanism for reading and reporting events.

Function	Description
NetElfBackupEventLog	Saves the specified event log to a backup file.
NetElfClearEventLog	Clears the specified event log and optionally saves the current copy of the log file to a backup file.
NetElfCloseEventLog	Closes the specified event log.
NetElfCloseEventLog\ Detail	Closes a handle of an event log record detail information.
NetElfDeregisterEvent\ Source	Closes a handle returned by the NetElfRegisterEventSource function
NetElfEventLogGetInfo	Retrieves information about the event log configuration.
NetElfEventLogSetInfo	Sets the event log configuration information.
NetElfGetNumberOf\ EventLogRecords	Retrieves the number of records in the specified event log.
NetElfGetOldestEvent\ LogRecord	Retrieves the absolute record number of the oldest record in the specified event log.
NetElfOpenBackup\ EventLog	Opens a handle of a backup event log.
NetElfOpenEventLog	Opens a handle of an event log.
NetElfOpenEventLog\ Detail	Opens a handle of an event log record detail information.
NetElfReadEventLog	Reads a whole number of entries from the specified event log.
NetElfReadEventLog\ Detail	Retrieves a detailed information for the event log record (the error message string corresponding to the error number contained in the event log record).
NetElfRegisterEvent\ Source	Returns a handle that can be used with the NetElfReportEvent function to log an event.
NetElfReportEvent	Writes an entry at the end of the specified event log.

Advanced Server keeps records of errors, logon activities, and other significant events. These records are stored in event logs which can be viewed and managed using EventLog API functions.

Every Advanced Server computer has three logs in which events are recorded — system, security (audit), and application.

System and application logs are available for viewing to all users. Security logs are accessible only to system administrators.

NetElfOpenEventLog returns a handle of an event log from a specified source. This handle can then be used with the following APIs:

NetElfBackupEventLog to save the event log to a backup file.

NetElfClearEventLog to clear the event log.

NetElfGetNumberOfEventLogRecords to retrieve the number of records in the event log.

NetElfGetOldestEventLogRecord to retrieve the number of the oldest record in the event log.

NetElfReadEventLog to read entries from the event log.

After the handling of the event log is completed, NetElfCloseEventLog should be called to close the opened event log.

NetElfBackupEventLog currently can back up the event logs only to the files on the local server.

NetElfOpenBackupEventLog function returns the handle of a specified backup event log. This handle then can be used in the same calls as a regular event log handle.

NetElfRegisterEventSource function returns a handle that can be used with NetElfReportEvent for reporting event. After reporting is finished, NetElfDeregisterEventSource should be called to close this handle.

NetElfReportEvent cannot be used to write an event to a security log in Advanced Server.

NetElfOpenEventLogDetail opens a handle of an event log detail information from the specified source, which then can be used in the calls to NetElfReadEventLogDetail to obtain the actual error messages corresponding to the error numbers contained in the event log records returned from the calls to NetElfReadEventLog.

NetElfReadEventLogDetail will retrieve the message for the given error message number and perform the substitution of the strings from the event log record into the message. NetElfCloseEventLogDetail should be called to close this handle.

The NetElfOpenEventLogDetail, NetElfReadEventLogDetail, and NetElfCloseEventLogDetail functions are local-only; they reference the local message files to retrieve the requested information. NetElfReadEventLogDetail will return only the error information known to the local server.

NetElfEventLogGetInfo and NetEventLogSetInfo functions retrieve and set the configuration information for the event log, such as the maximum event log size and the retention period for the event log records.

EventLog Category Data Structures

The level parameter controls the level of information provided to or returned from NetElfEventLogGetInfo and NetElfEventLogSetInfo. Currently, only level 1 data structure is used.

NetElfReadEventLog returns information in form of EVENTLOGRECORD data structures. EVENTLOGRECORD data structures can be used as parameters to NetElfReadEventLogDetail.

Event Log Information (level 1)

The EVENTLOG_INFO_1 data structure has the following format:

typedef struct _Eventlog_Info_1 {

DWORD MaxSize;

DWORD Retention;

} EVENTLOG_INFO_1, *PEVENTLOG_INFO_1;

Within this structure, the following parameters have been defined:

MaxSize specifies maximum allowed size of the event log file in kilobytes.

Retention specifies how lo+ng events should stay in event log before overwriting.

Event Log Record Data Structure

The EVENTLOGRECORD data structure has the following format:

typedef struct _EVENTLOGRECORD {

DWORD Length;

DWORD Reserved;

DWORD RecordNumber;

DWORD TimeGenerated;

DWORD TimeWritten;

DWORD EventID;

WORD EventType;

WORD NumStrings;

WORD EventCategory;

WORD ReservedFlags;

DWORD ClosingRecordNumber;

DWORD StringOffset;

DWORD UserSidLength;

DWORD UserSidOffset;

DWORD DataLength;

DWORD DataOffset;

//

// Then follow:

//

// TCHAR SourceName[]

// TCHAR Computername[]

// SID UserSid

// TCHAR Strings[]

// BYTE Data[]

// CHAR Pad[]

// DWORD Length;

//

} EVENTLOGRECORD;

Within this structure, the following parameters have been defined:

Length specifies the length, in bytes, of this event record. Note that this value is stored at both ends of the entry to ease moving forward or backward through the log. The length includes any pad bytes inserted at the end of the record for DWORD alignment.

Reserved

RecordNumber contains a record number that can be used with the EVENTLOG_SEEK_READ flag passed in a call to the NetElfReadEventLog function to begin reading at a specified record.

TimeGenerated specifies the time at which this entry was submitted. This time is measured in the number of seconds elapsed since 00:00:00 January 1, 1970.

TimeWritten specifies the time at which this entry was received by the service to be written to the log file. This time is measured in the number of seconds elapsed since 00:00:00 January 1, 1970.

EventID identifies the event. This is specific to the source that generated the event log entry, and is used, together with SourceName, to identify a message in a message file that is presented to the user while viewing the log.

EventType specifies the type of event. It can be one of the following values:

Value	Meaning
EVENTLOG_ERROR_TYPE	Error event
EVENTLOG_WARNING_TYPE	Warning event
EVENTLOG_INFORMATION_TYPE	Information event
EVENTLOG_AUDIT_SUCCESS	Success Audit event
EVENTLOG_AUDIT_FAILURE	Failure Audit event

NumStrings specifies the number of strings present in the log (at the position indicated by StringOffset). These strings are merged into the message before it is displayed to the user.

EventCategory specifies a source-specific sub category for the event.

ReservedFlags - reserved.

ClosingRecordNumber - reserved.

StringOffset specifies the offset of the strings within this event log entry.

UserSidLength specifies the length, in bytes, of the UserSid member. This value can be zero if no security identifier was provided.

UserSidOffset specifies the offset of the security identifier within the event record.

DataLength specifies the length, in bytes, of the event-specific data (at the position indicated by DataOffset).

DataOffset specifies the offset of the event-specific information within this log. This information could be something specific (a disk driver might log the number of retries, for example), followed by binary information specific to the event being logged and to the source that generated the entry.

SourceName contains the variable-length null-terminated string specifying the name of the source (application, service, driver, subsystem) that generated the entry. This is the name used to retrieve from the registry the name of the file containing the message strings for this source. It is used, together with the event identifier, to get the message string that describes this event.

Computername contains the variable-length null-terminated string specifying the name of the computer that generated this event. There may also be some pad bytes after this field to ensure that the UserSid is aligned on a DWORD boundary.

UserSid specifies the security identifier of the active user at the time this event was logged. This member may be empty if the UserSidLength member is zero.

The defined members are followed by the replacement strings for the message identified by the event identifier, the binary information, some pad bytes to make sure the full entry is on a DWORD boundary, and finally the length of the log entry again. Because the strings and the binary information can be of any length, no structure members are defined to reference them.

The event identifier together with SourceName and a language identifier identify a message string that describes the event in more detail. The strings are used as replacement strings and are merged into the message string to make a complete message. The message strings are contained in a message file specified in the source entry in the registry.

The binary information is information that is specific to the event. It could be a dump of an invalid packet that was received from the network, a dump of all the structures in a program (when the data area was detected to be corrupt), and so on. This information should be useful to the writer of the application in tracking down bugs or unauthorized breaks into the application.