Information about Message Files¶ ↑
Each event source should register message files that contain description strings for each event identifier, event category, and parameter. Register these files in the EventMessageFile, CategoryMessageFile, and ParameterMessageFile registry values for the event source.
You can create one message file that contains descriptions for the event identifiers, categories, and parameters, or create three separate message files. Several applications can share the same message file.
You should typically create message files as resource-only DLLs. They are smaller and faster than ordinary DLLs.
What does a .mc file look like?¶ ↑
A .mc file is just a plain text file that is parsed by the “mc” utility to generate a header and, ultimately, a .dll file. Here is a quick sample. Note that there must be a newline after the last '.' at the bottom. The ';' character denotes a comment.
; foo.mc MessageId=0x1 SymbolicName=CATEGORY_ERROR Language=English error .
MessageId=0x2 SymbolicName=CATEGORY_WARNING Language=English warning .
MessageId=0x3 Severity=Error SymbolicName=FOO_ERROR Language=English Error: %1 .
How to generate a .dll file from a .mc file¶ ↑
To turn this file into a .dll you have two options. The first is to use the command line utilities. Follow these steps:
1) mc filename.mc 2) rc -r -fo filename.res filename.rc 3) link -dll -noentry -out:filename.dll filename.res
Your other option is to use the win32-mc library, which is a simple wrapper for the above commands, and is included with this library. You now have a dll that you can associate with your event source (i.e. the one you associate with your application). You can also take a look at the C header file that .mc generates and use that in your own extensions if you like.
After this you'll need to register your event source and associate the .dll file with it. To do that, use the EventLog.add_event_source method. Be sure to specify the number of categories manually - it is not calculated automatically by the OS.
Returning to the .mc file, the example I used actually creates two categories, “error” and “warning”, and one event message. The numbers you assign here create corresponding (though not identical) values in the header file that is generated. It is the values found in the header file that you pass to the EventLog#report_event method for the category or event id. Here's the relevant data from the foo.h file (using foo.mc above):
define CATEGORY_ERROR 0x00000001L define CATEGORY_WARNING 0x00000002L define FOO_ERROR 0xC0000003L
In the case of categories, that number is the name number that shows up in the “category” field in the Event Viewer. In the case of event message files, it is the text that shows up in the event description.
The “data” field is what replaces “%1” as an actual text string in the event log, sort of like a printf format specifier, except that it's always a string.
Registering an event source¶ ↑
First, create the .dll file from the .mc file. Then register that .dll file for an event source we'll call “foo”. You can name the .dll file anything you like, but for sanity's sake I recommend keeping the same as the event source name.
require 'win32/eventlog' include Win32
dll_file = 'c:\wherever\foo.dll'
EventLog.add_event_source(
:source => 'Application', :key_name => 'foo', :category_count => 2, :event_message_file => dll_file, :category_message_file => dll_file
)
After you run this, you can run 'regedit' and see that your event source has been inserted into the registry. You can find it under:
HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesEventLogApplication.
Writing to the event source¶ ↑
Now that our event source 'foo' is registered, we can begin writing event log data for it. Here's an example of how you use it:
require 'win32/eventlog' include Win32
EventLog.open('Application') do |log|
log.report_event( :source => 'foo', :event_type => EventLog::WARN, :category => '0x00000002L'.hex, :event_id => '0x00000003L'.hex, :data => 'I'm warning you!' )
end
Note the values used for the 'category' and 'event_id' keys. Those are the values that were generated automatically in the foo.h file that I showed you above. You'll have to manually inspect the header file that's generated to determine which values you should be using.
You can now open your event log viewer and look at the message. You can get to your event log viewer via Start -> Control Panel -> Administrative Tools -> Event Viewer. You should see a warning message with the category “warning” and an event id of '3'. If you right click on that entry and select “properties”, you can see the event description is “Warning: I'm warning you!”.
More Info¶ ↑
For more information visit the following URL's:
msdn.microsoft.com/library/default.asp?url=/library/en-us/tools/tools/message_text_file_syntax.asp
msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/message_files.asp
msdn.microsoft.com/library/default.asp?url=/library/en-us/tools/tools/header_section.asp