class Puppet::Util::Windows::EventLog

Constants

EVENTLOG_ERROR_TYPE: msdn.microsoft.com/en-us/library/windows/desktop/aa363679(v=vs.85).aspx
EVENTLOG_INFORMATION_TYPE
EVENTLOG_WARNING_TYPE
EventLogError: represents an error resulting from a Win32 error code
NULL_HANDLE: These are duplicate definitions from Puppet::Util::Windows::ApiTypes, established here so this class can be standalone from Puppet, and public so we can reference them in tests.
WIN32_FALSE

Public Class Methods

new(source_name = 'Puppet') click to toggle source

Register an event log handle for the application @param source_name [String] the name of the event source to retrieve a handle for @return [void] @api public

   # File lib/puppet/util/windows/eventlog.rb
32 def initialize(source_name = 'Puppet')
33   @eventlog_handle = RegisterEventSourceW(FFI::Pointer::NULL, wide_string(source_name))
34   if @eventlog_handle == NULL_HANDLE
35     #TRANSLATORS 'Windows' is the operating system and 'RegisterEventSourceW' is a API call and should not be translated
36     raise EventLogError.new(_("RegisterEventSourceW failed to open Windows eventlog"), FFI.errno)
37   end
38 end

Also aliased as: open

open(source_name = 'Puppet')

Feels more natural to do Puppet::Util::Window::EventLog.open(“MyApplication”)

Alias for: new

to_native(level) click to toggle source

Query event identifier info for a given log level @param level [Symbol] an event log level @return [Array] Win API Event ID, Puppet Event ID @api public

    # File lib/puppet/util/windows/eventlog.rb
 91 def to_native(level)
 92   case level
 93   when :debug,:info,:notice
 94     [EVENTLOG_INFORMATION_TYPE, 0x01]
 95   when :warning
 96     [EVENTLOG_WARNING_TYPE, 0x02]
 97   when :err,:alert,:emerg,:crit
 98     [EVENTLOG_ERROR_TYPE, 0x03]
 99   else
100     raise ArgumentError, _("Invalid log level %{level}") % { level: level }
101   end
102 end

Public Instance Methods

close() click to toggle source

Close this instance's event log handle @return [void] @api public

   # File lib/puppet/util/windows/eventlog.rb
43 def close
44   DeregisterEventSource(@eventlog_handle)
45 ensure
46   @eventlog_handle = nil
47 end

report_event(args = {}) click to toggle source

Report an event to this instance's event log handle. Accepts a string to

report (:data => <string>) and event type (:event_type => Integer) and id

(:event_id => Integer) as returned by to_native. The additional arguments to ReportEventW seen in this method aren't exposed - though ReportEventW technically can accept multiple strings as well as raw binary data to log, we accept a single string from Puppet::Util::Log

@param args [Hash{Symbol=>Object}] options to the associated log event @return [void] @api public

   # File lib/puppet/util/windows/eventlog.rb
59 def report_event(args = {})
60   unless args[:data].is_a?(String)
61     raise ArgumentError, _("data must be a string, not %{class_name}") % { class_name: args[:data].class }
62   end
63   from_string_to_wide_string(args[:data]) do |message_ptr|
64     FFI::MemoryPointer.new(:pointer) do |message_array_ptr|
65       message_array_ptr.write_pointer(message_ptr)
66       user_sid = FFI::Pointer::NULL
67       raw_data = FFI::Pointer::NULL
68       raw_data_size = 0
69       num_strings = 1
70       eventlog_category = 0
71       report_result = ReportEventW(@eventlog_handle, args[:event_type],
72         eventlog_category, args[:event_id], user_sid,
73         num_strings, raw_data_size, message_array_ptr, raw_data)
74 
75       if report_result == WIN32_FALSE
76         #TRANSLATORS 'Windows' is the operating system and 'ReportEventW' is a API call and should not be translated
77         raise EventLogError.new(_("ReportEventW failed to report event to Windows eventlog"), FFI.errno)
78       end
79     end
80   end
81 end

Private Instance Methods

from_string_to_wide_string(str) { |ptr| ... } click to toggle source

Private duplicate of Puppet::Util::Windows::ApiTypes::from_string_to_wide_string Not for use outside of EventLog! - Use Puppet::Util::Windows instead @api private

    # File lib/puppet/util/windows/eventlog.rb
137 def from_string_to_wide_string(str, &block)
138   str = wide_string(str)
139   FFI::MemoryPointer.from_wide_string(str) { |ptr| yield ptr }
140 
141   # ptr has already had free called, so nothing to return
142   nil
143 end

wide_string(str) click to toggle source

Private duplicate of Puppet::Util::Windows::String::wide_string Not for use outside of EventLog! - use Puppet::Util::Windows instead @api private

    # File lib/puppet/util/windows/eventlog.rb
127 def wide_string(str)
128   # if given a nil string, assume caller wants to pass a nil pointer to win32
129   return nil if str.nil?
130 
131   str.encode('UTF-16LE')
132 end