Class | Win32::EventLog |
In: |
lib/win32/eventlog.rb
|
Parent: | Object |
The EventLog class encapsulates an Event Log source and provides methods for interacting with that source.
VERSION | = | '0.4.6' | ||
FORWARDS_READ | = | EVENTLOG_FORWARDS_READ | Aliased read flags | |
BACKWARDS_READ | = | EVENTLOG_BACKWARDS_READ | ||
SEEK_READ | = | EVENTLOG_SEEK_READ | ||
SEQUENTIAL_READ | = | EVENTLOG_SEQUENTIAL_READ | ||
SUCCESS | = | EVENTLOG_SUCCESS | Aliased event types | |
ERROR | = | EVENTLOG_ERROR_TYPE | ||
WARN | = | EVENTLOG_WARNING_TYPE | ||
INFO | = | EVENTLOG_INFORMATION_TYPE | ||
AUDIT_SUCCESS | = | EVENTLOG_AUDIT_SUCCESS | ||
AUDIT_FAILURE | = | EVENTLOG_AUDIT_FAILURE | ||
BUFFER_SIZE | = | 1024 * 64 | ||
MAX_SIZE | = | 256 | ||
MAX_STRINGS | = | 16 | ||
BASE_KEY | = | "SYSTEM\\CurrentControlSet\\Services\\EventLog\\" | ||
EventLogStruct | = | Struct.new('EventLogStruct', :record_number, :time_generated, :time_written, :event_id, :event_type, :category, :source, :computer, :user, :string_inserts, :description | The EventLogStruct encapsulates a single event log record. |
new | -> | open |
file | [R] | The name of the file used in the EventLog.open_backup method. This is set to nil if the file was not opened using the EventLog.open_backup method. |
server | [R] | The name of the server which the event log is reading from. |
source | [R] | The name of the event log source. This will typically be ‘Application’, ‘System’ or ‘Security’, but could also refer to a custom event log source. |
Adds an event source to the registry. The following are valid keys:
Of these keys, only key_name is mandatory. An ArgumentError is raised if you attempt to use an invalid key. If supported_types is not specified then the following value is used:
EventLog::ERROR | EventLog::WARN | EventLog::INFO
The event_message_file and category_message_file are typically, though not necessarily, the same file. See the documentation on .mc files for more details.
Opens a handle to the new EventLog source on server, or the local machine if no host is specified. Typically, your source will be ‘Application, ‘Security’ or ‘System’, although you can specify a custom log file as well.
If a custom, registered log file name cannot be found, the event logging service opens the ‘Application’ log file. This is the behavior of the underlying Windows function, not my own doing.
Nearly identical to EventLog.open, except that the source is a backup file and not an event source (and there is no default).
This class method is nearly identical to the EventLog#read instance method, except that it takes a source and server as the first two arguments.
Clears the EventLog. If backup_file is provided, it backs up the event log to that file first.
Closes the EventLog handle. Automatically closed for you if you use the block form of EventLog.new.
Yields an EventLogStruct every time a record is written to the event log. Unlike EventLog#tail, this method breaks out of the block after the event.
Raises an Error if no block is provided.
Returns the absolute record number of the oldest record. Note that this is not guaranteed to be 1 because event log records can be overwritten.
EventLog#read(flags=nil, offset=0) EventLog#read(flags=nil, offset=0){ |log| … }
Iterates over each record in the event log, yielding a EventLogStruct for each record. The offset value is only used when used in conjunction with the EventLog::SEEK_READ flag. Otherwise, it is ignored. If no flags are specified, then the default flags are:
EventLog::SEQUENTIAL_READ | EventLog::FORWARDS_READ
Note that, if you‘re performing a SEEK_READ, then the offset must refer to a record number that actually exists. The default of 0 may or may not work for your particular event log.
The EventLogStruct struct contains the following members:
record_number # Fixnum time_generated # Time time_written # Time event_id # Fixnum event_type # String category # String source # String computer # String user # String or nil description # String or nil string_inserts # An array of Strings or nil
If no block is given the method returns an array of EventLogStruct‘s.
EventLog#report_event(key => value, …)
Writes an event to the event log. The following are valid keys:
source # Event log source name. Defaults to "Application" event_id # Event ID (defined in event message file) category # Event category (defined in category message file) data # String that is written to the log event_type # Type of event, e.g. EventLog::ERROR, etc.
The event_type keyword is the only mandatory keyword. The others are optional. Although the source defaults to "Application", I recommend that you create an application specific event source and use that instead. See the ‘EventLog.add_event_source’ method for more details.
The event_id and category values are defined in the message file(s) that you created for your application. See the tutorial.txt file for more details on how to create a message file.
An ArgumentError is raised if you attempt to use an invalid key.
Yields an EventLogStruct every time a record is written to the event log, once every frequency seconds. Unlike EventLog#notify_change, this method does not break out of the block after the event. The read frequency is set to 5 seconds by default.
Raises an Error if no block is provided.
The delay between reads is due to the nature of the Windows event log. It is not really designed to be tailed in the manner of a Unix syslog, for example, in that not nearly as many events are typically recorded. It‘s just not designed to be polled that heavily.