Class: Puppet::Util::Windows::EventLog

Inherits:
Object
  • Object
show all
Extended by:
FFI::Library
Defined in:
lib/puppet/util/windows.rb,
lib/puppet/util/windows/eventlog.rb

Defined Under Namespace

Classes: EventLogError

Constant Summary collapse

EVENTLOG_ERROR_TYPE =
0x0001
EVENTLOG_WARNING_TYPE =
0x0002
EVENTLOG_INFORMATION_TYPE =
0x0004
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.

0
WIN32_FALSE =
0

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source_name = 'Puppet') ⇒ void

Register an event log handle for the application

Parameters:

  • source_name (String) (defaults to: 'Puppet')

    the name of the event source to retrieve a handle for



33
34
35
36
37
38
39
# File 'lib/puppet/util/windows/eventlog.rb', line 33

def initialize(source_name = 'Puppet')
  @eventlog_handle = RegisterEventSourceW(FFI::Pointer::NULL, wide_string(source_name))
  if @eventlog_handle == NULL_HANDLE
    # TRANSLATORS 'Windows' is the operating system and 'RegisterEventSourceW' is a API call and should not be translated
    raise EventLogError.new(_("RegisterEventSourceW failed to open Windows eventlog"), FFI.errno)
  end
end

Class Method Details

.to_native(level) ⇒ Array

Query event identifier info for a given log level

Parameters:

  • level (Symbol)

    an event log level

Returns:

  • (Array)

    Win API Event ID, Puppet Event ID



93
94
95
96
97
98
99
100
101
102
103
104
# File 'lib/puppet/util/windows/eventlog.rb', line 93

def to_native(level)
  case level
  when :debug, :info, :notice
    [EVENTLOG_INFORMATION_TYPE, 0x01]
  when :warning
    [EVENTLOG_WARNING_TYPE, 0x02]
  when :err, :alert, :emerg, :crit
    [EVENTLOG_ERROR_TYPE, 0x03]
  else
    raise ArgumentError, _("Invalid log level %{level}") % { level: level }
  end
end

Instance Method Details

#closevoid

This method returns an undefined value.

Close this instance’s event log handle



44
45
46
47
48
# File 'lib/puppet/util/windows/eventlog.rb', line 44

def close
  DeregisterEventSource(@eventlog_handle)
ensure
  @eventlog_handle = nil
end

#report_event(args = {}) ⇒ void

This method returns an undefined value.

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

Parameters:

  • args (Hash{Symbol=>Object}) (defaults to: {})

    options to the associated log event



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
# File 'lib/puppet/util/windows/eventlog.rb', line 60

def report_event(args = {})
  unless args[:data].is_a?(String)
    raise ArgumentError, _("data must be a string, not %{class_name}") % { class_name: args[:data].class }
  end

  from_string_to_wide_string(args[:data]) do |message_ptr|
    FFI::MemoryPointer.new(:pointer) do |message_array_ptr|
      message_array_ptr.write_pointer(message_ptr)
      user_sid = FFI::Pointer::NULL
      raw_data = FFI::Pointer::NULL
      raw_data_size = 0
      num_strings = 1
      eventlog_category = 0
      report_result = ReportEventW(@eventlog_handle, args[:event_type],
                                   eventlog_category, args[:event_id], user_sid,
                                   num_strings, raw_data_size, message_array_ptr, raw_data)

      if report_result == WIN32_FALSE
        # TRANSLATORS 'Windows' is the operating system and 'ReportEventW' is a API call and should not be translated
        raise EventLogError.new(_("ReportEventW failed to report event to Windows eventlog"), FFI.errno)
      end
    end
  end
end