Class: FFI::Pointer

Inherits:
Object show all
Defined in:
lib/puppet/util/windows/api_types.rb

Constant Summary collapse

NULL_HANDLE =
0

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_string_to_wide_string(str, &block) ⇒ Object



23
24
25
26
27
28
29
30
31
32
33
34
# File 'lib/puppet/util/windows/api_types.rb', line 23

def self.from_string_to_wide_string(str, &block)
  str = Puppet::Util::Windows::String.wide_string(str)
  FFI::MemoryPointer.new(:byte, str.bytesize) do |ptr|
    # uchar here is synonymous with byte
    ptr.put_array_of_uchar(0, str.bytes.to_a)

    yield ptr
  end

  # ptr has already had free called, so nothing to return
  nil
end

Instance Method Details

#read_arbitrary_wide_string_up_to(max_char_length = 512, null_terminator = :single_null, encode_options = {}) ⇒ Object

Parameters:

  • max_char_length (Integer) (defaults to: 512)

    Maximum number of wide chars to return (typically excluding NULLs), not bytes

  • null_terminator (Symbol) (defaults to: :single_null)

    Number of number of null wchar characters, not bytes, that determine the end of the string null_terminator = :single_null, then the terminating sequence is two bytes of zero. This is UNIT16 = 0 null_terminator = :double_null, then the terminating sequence is four bytes of zero. This is UNIT32 = 0

  • encode_options (Hash) (defaults to: {})

    Accepts the same option hash that may be passed to String#encode in Ruby



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# File 'lib/puppet/util/windows/api_types.rb', line 70

def read_arbitrary_wide_string_up_to(max_char_length = 512, null_terminator = :single_null, encode_options = {})
  if null_terminator != :single_null && null_terminator != :double_null
    raise _("Unable to read wide strings with %{null_terminator} terminal nulls") % { null_terminator: null_terminator }
  end

  terminator_width = null_terminator == :single_null ? 1 : 2
  reader_method = null_terminator == :single_null ? :get_uint16 : :get_uint32

  # Look for a null terminating characters; if found, read up to that null (exclusive)
  (0...max_char_length - terminator_width).each do |i|
    return read_wide_string(i, Encoding::UTF_8, encode_options) if send(reader_method, (i * 2)) == 0
  end

  # String is longer than the max; read just to the max
  read_wide_string(max_char_length, Encoding::UTF_8, encode_options)
end

#read_com_memory_pointer(&block) ⇒ Object



104
105
106
107
108
109
110
111
112
113
114
115
# File 'lib/puppet/util/windows/api_types.rb', line 104

def read_com_memory_pointer(&block)
  ptr = nil
  begin
    ptr = read_pointer
    yield ptr
  ensure
    FFI::WIN32::CoTaskMemFree(ptr) if ptr && ! ptr.null?
  end

  # ptr has already had CoTaskMemFree called, so nothing to return
  nil
end

#read_handleObject



48
49
50
# File 'lib/puppet/util/windows/api_types.rb', line 48

def read_handle
  type_size == 4 ? read_uint32 : read_uint64
end

#read_wide_string(char_length, dst_encoding = Encoding::UTF_8, encode_options = {}) ⇒ Object



56
57
58
59
60
61
62
63
# File 'lib/puppet/util/windows/api_types.rb', line 56

def read_wide_string(char_length, dst_encoding = Encoding::UTF_8, encode_options = {})
  # char_length is number of wide chars (typically excluding NULLs), *not* bytes
  str = get_bytes(0, char_length * 2).force_encoding('UTF-16LE')
  str.encode(dst_encoding, str.encoding, encode_options)
rescue Exception => e
  Puppet.debug "Unable to convert value #{str.dump} to encoding #{dst_encoding} due to #{e.inspect}"
  raise
end

#read_win32_boolObject



36
37
38
39
40
# File 'lib/puppet/util/windows/api_types.rb', line 36

def read_win32_bool
  # BOOL is always a 32-bit integer in Win32
  # some Win32 APIs return 1 for true, while others are non-0
  read_int32 != FFI::WIN32_FALSE
end

#read_win32_local_pointer(&block) ⇒ Object



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# File 'lib/puppet/util/windows/api_types.rb', line 87

def read_win32_local_pointer(&block)
  ptr = nil
  begin
    ptr = read_pointer
    yield ptr
  ensure
    if ptr && ! ptr.null?
      if FFI::WIN32::LocalFree(ptr.address) != FFI::Pointer::NULL_HANDLE
        Puppet.debug "LocalFree memory leak"
      end
    end
  end

  # ptr has already had LocalFree called, so nothing to return
  nil
end