win32ole-ffi 0.1.0

data/lib/win32ole/ffi/fiddle_compat.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+
+# Backports, for JRuby's older Fiddle FFI backends, behaviours this
+# implementation relies on and newer fiddle already has. JRuby 9.4 ships
+# fiddle 1.1.4, 10.0 ships 1.1.6, and 10.1 ships 1.1.8, which needs none of
+# this. CRuby's C fiddle has always behaved this way.
+if RUBY_ENGINE == 'jruby'
+  class WIN32OLE
+    module FiddleCompat
+      FIDDLE_VERSION = Gem::Version.new(Fiddle::VERSION)
+
+      # fiddle 1.1.6: an Integer address passed for a VOIDP argument.
+      module IntegerVoidp
+        def call(*args, &block)
+          @args.each_with_index do |type, i|
+            args[i] = Fiddle::Pointer.new(args[i]) if type == Fiddle::TYPE_VOIDP && args[i].is_a?(Integer)
+          end
+          super
+        end
+      end
+
+      # fiddle 1.1.8: a closure's pointer arguments as Fiddle::Pointer, not FFI::Pointer.
+      module FiddlePointerArgs
+        def call(*args)
+          super(*args.map { |v| v.is_a?(FFI::Pointer) ? Fiddle::Pointer.new(v) : v })
+        end
+      end
+
+      # fiddle 1.1.8: Pointer.to_ptr(a_string) with room for the NUL written
+      # after the bytes (older ones malloc only bytesize, overrunning the heap).
+      module StringToPtr
+        def to_ptr(value)
+          return super unless value.is_a?(String)
+
+          new(FFI::MemoryPointer.from_string(value), value.bytesize)
+        end
+        alias [] to_ptr
+      end
+
+      Fiddle::Function.prepend(IntegerVoidp) if FIDDLE_VERSION < Gem::Version.new('1.1.6')
+      if FIDDLE_VERSION < Gem::Version.new('1.1.8')
+        Fiddle::Closure::BlockCaller.prepend(FiddlePointerArgs)
+        Fiddle::Pointer.singleton_class.prepend(StringToPtr)
+      end
+    end
+  end
+end

data/lib/win32ole/ffi/method.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'win32ole/ffi/win32'
+require 'win32ole/ffi/typeinfo'
+require 'win32ole/ffi/param'
+
+class WIN32OLE
+  class Method
+    W = Win32
+    TI = TypeInfo
+    private_constant :W, :TI
+
+    FUNCFLAG_FRESTRICTED = 0x1
+    FUNCFLAG_FHIDDEN = 0x40 # per MEMBERID/FUNCFLAGS, distinct from TYPEFLAG's own 0x10
+    FUNCFLAG_FNONBROWSABLE = 0x400
+
+    # Mirrors ext/win32ole/win32ole_method.c's folemethod_initialize:
+    # WIN32OLE::Method.new(oletype, method_name) searches oletype's own
+    # funcs first, then (since a coclass like "Shell" has none of its own
+    # -- its methods live on the interfaces it implements) one level of
+    # its implemented types, case-insensitively by name (COM method names
+    # are case-insensitive).
+    def self.new(oletype, method)
+      raise TypeError, '1st argument should be WIN32OLE::Type object' unless oletype.is_a?(WIN32OLE::Type)
+
+      method = check_string!(method)
+      owner_ptr = oletype.itypeinfo_ptr
+      index = func_index_in(owner_ptr, method)
+      return from_typeinfo_ptr(owner_ptr, index) if index
+
+      # ole_method_sub(self, pTypeInfo, pRefTypeInfo, ...): a match on an
+      # implemented type records oletype as the owner (for #event?).
+      # initialize only reads ref_ptr synchronously, so it is released here
+      # either way.
+      TI.each_impl_type(owner_ptr) do |_flags, ref_ptr|
+        begin
+          ref_index = func_index_in(ref_ptr, method)
+          return from_typeinfo_ptr(ref_ptr, ref_index, owner_ptr) if ref_index
+        ensure
+          TI.release(ref_ptr)
+        end
+      end
+      raise WIN32OLE::RuntimeError, "not found #{method}"
+    end
+
+    def self.check_string!(val)
+      return val if val.is_a?(::String)
+      return val.to_str if val.respond_to?(:to_str)
+
+      raise TypeError, "no implicit conversion of #{val.class} into String"
+    end
+    private_class_method :check_string!
+
+    # Index of the FUNCDESC in itypeinfo_ptr whose name matches
+    # case-insensitively, or nil.
+    def self.func_index_in(itypeinfo_ptr, name)
+      (TI.type_attr_value(itypeinfo_ptr, :cFuncs) || 0).times do |i|
+        funcdesc_out = ("\x00" * W::PTR_SIZE).b
+        next if W.failed?(TI.func_desc_fn(itypeinfo_ptr).call(itypeinfo_ptr, i, funcdesc_out))
+
+        funcdesc_ptr = funcdesc_out.unpack1(W::PACK_PTR)
+        memid = TI::FUNCDESC.new(funcdesc_ptr).memid
+        TI.release_func_desc_fn(itypeinfo_ptr).call(itypeinfo_ptr, funcdesc_ptr)
+
+        fname = TI.member_name(itypeinfo_ptr, memid)
+        return i if fname && fname.casecmp?(name)
+      end
+      nil
+    end
+    private_class_method :func_index_in
+
+    # owner_ptr is the coclass whose implemented type itypeinfo_ptr is
+    # (olemethoddata's pOwnerTypeInfo), or nil for a type's own function.
+    def self.from_typeinfo_ptr(itypeinfo_ptr, index, owner_ptr = nil)
+      allocate.tap { |method| method.send(:initialize, itypeinfo_ptr, index, owner_ptr) }
+    end
+
+    def initialize(itypeinfo_ptr, index, owner_ptr = nil)
+      funcdesc_out = ("\x00" * W::PTR_SIZE).b
+      hr = TI.func_desc_fn(itypeinfo_ptr).call(itypeinfo_ptr, index, funcdesc_out)
+      if W.failed?(hr)
+        raise WIN32OLE::QueryInterfaceError, W.query_interface_error_message('GetFuncDesc', W.hr_hex(hr))
+      end
+      funcdesc_ptr = funcdesc_out.unpack1(W::PACK_PTR)
+      funcdesc = TI::FUNCDESC.new(funcdesc_ptr)
+
+      @memid = funcdesc.memid
+      @invkind = funcdesc.invkind
+      @dispid = funcdesc.memid
+      @offset_vtbl = funcdesc.oVft
+      @size_params = funcdesc.cParams
+      @size_opt_params = funcdesc.cParamsOpt
+      @func_flags = funcdesc.wFuncFlags
+      @return_vt = funcdesc.ret_tdesc_vt
+      @return_type_detail = TI.typedesc_details(
+        itypeinfo_ptr, funcdesc_ptr + TI.offsetof(TI::FUNCDESC, 'ret_tdesc_union_ptr')
+      )
+
+      @name, param_names = read_names(itypeinfo_ptr, @memid, funcdesc.cParams)
+      # folemethod_event / folemethod_event_interface, computed now because
+      # neither ITypeInfo* is retained past construction.
+      @event = owner_ptr ? TI.method_event?(owner_ptr, index, @name) : false
+      @event_interface = @event ? TI.type_name(itypeinfo_ptr) : nil
+      @helpstring, @help_context, @helpfile = read_documentation(itypeinfo_ptr, @memid)
+
+      # lprgelemdescParam is a POINTER FIELD inside FUNCDESC — its value is
+      # the address of a contiguous array of cParams ELEMDESC structs, not
+      # an offset into FUNCDESC itself.
+      elemdesc_array_ptr = funcdesc.lprgelemdescParam
+      # MRI builds one Param per name GetNames actually returned beyond the
+      # member's own name (param_names.length), not per FUNCDESC.cParams —
+      # for a property-put method, GetNames returns only the property name
+      # (cParams=1 but zero param names), so cParams would otherwise build a
+      # spurious nameless Param.
+      @params = Array.new(param_names.length) do |i|
+        elemdesc_ptr = elemdesc_array_ptr + i * TI::ELEMDESC.size
+        WIN32OLE::Param.from_elemdesc(itypeinfo_ptr, elemdesc_ptr, param_names[i])
+      end
+
+      TI.release_func_desc_fn(itypeinfo_ptr).call(itypeinfo_ptr, funcdesc_ptr)
+    end
+
+    def name
+      @name
+    end
+    alias to_s name
+
+    def return_type
+      @return_type_detail.last
+    end
+
+    def return_vtype
+      @return_vt
+    end
+
+    def return_type_detail
+      @return_type_detail.dup
+    end
+
+    def invoke_kind
+      TI.invoke_kind_name(@invkind)
+    end
+
+    def invkind
+      @invkind
+    end
+
+    def visible?
+      (@func_flags & (FUNCFLAG_FRESTRICTED | FUNCFLAG_FHIDDEN | FUNCFLAG_FNONBROWSABLE)) == 0
+    end
+
+    def dispid
+      @dispid
+    end
+
+    def helpstring
+      @helpstring
+    end
+
+    def helpfile
+      @helpfile
+    end
+
+    def helpcontext
+      @help_context
+    end
+
+    def offset_vtbl
+      @offset_vtbl
+    end
+
+    def size_params
+      @size_params
+    end
+
+    def size_opt_params
+      @size_opt_params
+    end
+
+    def params
+      @params
+    end
+
+    def inspect
+      "#<WIN32OLE::Method:#{name}>"
+    end
+
+    def event?
+      @event
+    end
+
+    def event_interface
+      @event_interface
+    end
+
+    private
+
+    def read_names(itypeinfo_ptr, memid, cparams)
+      # GetNames(MEMBERID memid, BSTR *rgBstrNames, UINT cMaxNames, UINT *pcNames)
+      # rgBstrNames[0] is the member's own name; rgBstrNames[1..] are param names.
+      max_names = cparams + 1
+      names_out = ("\x00" * (max_names * W::PTR_SIZE)).b
+      count_out = ("\x00" * 4).b
+      get_names_fn(itypeinfo_ptr).call(itypeinfo_ptr, memid, names_out, max_names, count_out)
+      count = count_out.unpack1('L')
+      bstrs = names_out.unpack(W::PACK_PTR * count)
+      strings = bstrs.map { |b| W.bstr_to_s(b) }
+      bstrs.each { |b| W.sys_free_string.call(b) unless b.zero? }
+      [strings[0], strings[1..] || []]
+    end
+
+    def get_names_fn(itypeinfo_ptr)
+      @@get_names_fns ||= {}
+      @@get_names_fns[W.vtable_address(itypeinfo_ptr)] ||= W.vtable_function(
+        itypeinfo_ptr, TI::ITYPEINFO_VTBL[:GetNames],
+        [W::VOIDP, W::LONG, W::VOIDP, W::DWORD, W::VOIDP], W::LONG
+      )
+    end
+
+    def read_documentation(itypeinfo_ptr, memid)
+      name_out = ("\x00" * W::PTR_SIZE).b
+      docstring_out = ("\x00" * W::PTR_SIZE).b
+      helpcontext_out = ("\x00" * 4).b
+      helpfile_out = ("\x00" * W::PTR_SIZE).b
+      TI.documentation_fn_for_typeinfo(itypeinfo_ptr).call(
+        itypeinfo_ptr, memid, name_out, docstring_out, helpcontext_out, helpfile_out
+      )
+      name_bstr = name_out.unpack1(W::PACK_PTR)
+      docstring_bstr = docstring_out.unpack1(W::PACK_PTR)
+      helpfile_bstr = helpfile_out.unpack1(W::PACK_PTR)
+      helpstring = W.bstr_to_s(docstring_bstr) || '' # C's WC2VSTR(NULL) is '', not nil
+      helpfile = W.bstr_to_s(helpfile_bstr) || ''
+      [name_bstr, docstring_bstr, helpfile_bstr].each { |b| W.sys_free_string.call(b) unless b.zero? }
+      [helpstring, helpcontext_out.unpack1('L'), helpfile]
+    end
+  end
+end

data/lib/win32ole/ffi/param.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'win32ole/ffi/win32'
+require 'win32ole/ffi/typeinfo'
+
+class WIN32OLE
+  class Param
+    W = Win32
+    TI = TypeInfo
+    private_constant :W, :TI
+
+    PARAMFLAG_FIN = 0x1
+    PARAMFLAG_FOUT = 0x2
+    PARAMFLAG_FRETVAL = 0x8
+    PARAMFLAG_FOPT = 0x10
+    PARAMFLAG_FHASDEFAULT = 0x20
+    PARAMDESCEX_DEFAULT_VALUE_OFFSET = 8
+
+    # ext/win32ole/win32ole_param.c's foleparam_initialize: the n-th
+    # (1-based) parameter of a WIN32OLE::Method.
+    def self.new(olemethod, n)
+      raise TypeError, '1st parameter must be WIN32OLE::Method object' unless olemethod.is_a?(WIN32OLE::Method)
+      raise TypeError, "no implicit conversion of #{n.class} into Integer" unless n.is_a?(::Integer)
+
+      params = olemethod.params
+      raise IndexError, "index of param must be in 1..#{params.size}" unless (1..params.size).cover?(n)
+
+      params[n - 1]
+    end
+
+    def self.from_elemdesc(itypeinfo_ptr, elemdesc_ptr, name)
+      allocate.tap { |param| param.send(:initialize, itypeinfo_ptr, elemdesc_ptr, name) }
+    end
+
+    def initialize(itypeinfo_ptr, elemdesc_ptr, name)
+      @name = name
+      elemdesc = TI::ELEMDESC.new(elemdesc_ptr)
+      @type_detail = TI.typedesc_details(
+        itypeinfo_ptr, elemdesc_ptr.to_i + TI.offsetof(TI::ELEMDESC, 'tdesc_union_ptr')
+      )
+      @param_flags = elemdesc.wParamFlags
+      # Read the default value now, not lazily: PARAMDESCEX lives inside the
+      # owning Method's FUNCDESC, which the Method releases (ReleaseFuncDesc)
+      # right after all of its Params are constructed. Holding the raw
+      # pointer past this point and dereferencing it later (e.g. from a
+      # public #default call) would be a use-after-free.
+      @default = read_default(elemdesc.paramdescex_ptr)
+    end
+
+    def name
+      @name
+    end
+    alias to_s name
+
+    def ole_type
+      @type_detail.last
+    end
+
+    def ole_type_detail
+      @type_detail.dup
+    end
+
+    def input?
+      (@param_flags & PARAMFLAG_FIN) != 0
+    end
+
+    def output?
+      (@param_flags & PARAMFLAG_FOUT) != 0
+    end
+
+    def optional?
+      (@param_flags & PARAMFLAG_FOPT) != 0
+    end
+
+    def retval?
+      (@param_flags & PARAMFLAG_FRETVAL) != 0
+    end
+
+    def default
+      @default
+    end
+
+    # ext/win32ole/win32ole_param.c's foleparam_inspect: the default value,
+    # not the type, follows the name -- and only when there is one.
+    def inspect
+      detail = @default.nil? ? name : "#{name}=#{@default.inspect}"
+      "#<WIN32OLE::Param:#{detail}>"
+    end
+
+    private
+
+    def read_default(paramdescex_ptr)
+      return nil unless (@param_flags & PARAMFLAG_FHASDEFAULT) != 0
+      return nil if paramdescex_ptr.to_i.zero?
+
+      # PARAMDESCEX is { ULONG cBytes; VARIANTARG varDefaultValue; } -- a
+      # VARIANT holds a DOUBLE/LONGLONG, so it is 8-byte aligned and starts
+      # at offset 8 (cBytes plus 4 bytes of padding), not right after cBytes.
+      variant_bytes = Fiddle::Pointer.new(paramdescex_ptr)[PARAMDESCEX_DEFAULT_VALUE_OFFSET, W::VARIANT_SIZE]
+      vt, payload = W.unpack_variant(variant_bytes)
+      case W.variant_ruby_type(vt)
+      when :i4 then W.unpack_i4(payload)
+      when :i8 then W.unpack_i8(payload)
+      when :r8 then W.unpack_r8(payload)
+      when :bool then W.unpack_bool(payload)
+      when :bstr then W.bstr_to_s(W.unpack_pointer(payload))
+      else nil
+      end
+    end
+  end
+end

data/lib/win32ole/ffi/record.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'fiddle'
+require 'win32ole/ffi/win32'
+require 'win32ole/ffi/typeinfo'
+
+class WIN32OLE
+  class Record
+    W = Win32
+    TI = TypeInfo
+    private_constant :W, :TI
+
+    # Full slot table transcribed from oaidl.h, kept for documentation
+    # completeness (only the six below have a Fiddle::Function bound; the
+    # rest are unused).
+    IRECORDINFO_VTBL = {
+      RecordInit: 3, RecordClear: 4, RecordCopy: 5, GetGuid: 6, GetName: 7,
+      GetSize: 8, GetTypeInfo: 9, GetField: 10, GetFieldNoCopy: 11,
+      PutField: 12, PutFieldNoCopy: 13, GetFieldNames: 14, IsMatchingType: 15,
+      RecordCreate: 16, RecordCreateCopy: 17, RecordDestroy: 18
+    }.freeze
+
+    def self.record_init_fn(pri)
+      @record_init_fns ||= {}
+      @record_init_fns[W.vtable_address(pri)] ||= W.vtable_function(
+        pri, IRECORDINFO_VTBL[:RecordInit], [W::VOIDP, W::VOIDP], W::LONG
+      )
+    end
+
+    def self.get_name_fn(pri)
+      @get_name_fns ||= {}
+      @get_name_fns[W.vtable_address(pri)] ||= W.vtable_function(
+        pri, IRECORDINFO_VTBL[:GetName], [W::VOIDP, W::VOIDP], W::LONG
+      )
+    end
+
+    def self.get_size_fn(pri)
+      @get_size_fns ||= {}
+      @get_size_fns[W.vtable_address(pri)] ||= W.vtable_function(
+        pri, IRECORDINFO_VTBL[:GetSize], [W::VOIDP, W::VOIDP], W::LONG
+      )
+    end
+
+    def self.get_field_no_copy_fn(pri)
+      @get_field_no_copy_fns ||= {}
+      @get_field_no_copy_fns[W.vtable_address(pri)] ||= W.vtable_function(
+        pri, IRECORDINFO_VTBL[:GetFieldNoCopy], [W::VOIDP, W::VOIDP, W::VOIDP, W::VOIDP, W::VOIDP], W::LONG
+      )
+    end
+
+    def self.put_field_fn(pri)
+      @put_field_fns ||= {}
+      @put_field_fns[W.vtable_address(pri)] ||= W.vtable_function(
+        pri, IRECORDINFO_VTBL[:PutField], [W::VOIDP, W::DWORD, W::VOIDP, W::VOIDP, W::VOIDP], W::LONG
+      )
+    end
+
+    def self.get_field_names_fn(pri)
+      @get_field_names_fns ||= {}
+      @get_field_names_fns[W.vtable_address(pri)] ||= W.vtable_function(
+        pri, IRECORDINFO_VTBL[:GetFieldNames], [W::VOIDP, W::VOIDP, W::VOIDP], W::LONG
+      )
+    end
+
+    def self.get_record_info_from_type_info_fn
+      @get_record_info_from_type_info_fn ||= Fiddle::Function.new(
+        W.oleaut32['GetRecordInfoFromTypeInfo'], [W::VOIDP, W::VOIDP], W::LONG, W::STDCALL
+      )
+    end
+
+    def initialize(typename, oleobj)
+      typename = typename.to_s
+      itypelib_ptr = resolve_itypelib_ptr(oleobj)
+      pri = find_record_info(itypelib_ptr, typename)
+      unless pri
+        raise WIN32OLE::RuntimeError, "fail to query IRecordInfo interface for `#{typename}'"
+      end
+
+      set_record_info(pri, nil)
+    end
+
+    def to_h
+      @fields
+    end
+
+    def typename
+      @typename
+    end
+
+    def inspect
+      "#<WIN32OLE::Record:#{@typename}>"
+    end
+
+    def method_missing(name, *args)
+      sname = name.to_s
+      case args.size
+      when 0 then @fields.fetch(sname)
+      when 1
+        key = sname.end_with?('=') ? sname[0..-2] : sname
+        @fields.fetch(key) # raises KeyError before writing, matching MRI
+        @fields[key] = args.first
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @fields.key?(name.to_s.sub(/=\z/, '')) || super
+    end
+
+    def ole_instance_variable_get(name)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise TypeError, 'wrong argument type (expected String or Symbol)'
+      end
+
+      @fields.fetch(name.to_s)
+    end
+
+    def ole_instance_variable_set(name, val)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise TypeError, 'wrong argument type (expected String or Symbol)'
+      end
+
+      key = name.to_s
+      @fields.fetch(key)
+      @fields[key] = val
+    end
+
+    VT_RECORD_BODY_SIZE = W::PTR_SIZE * 2 # BRECORD: { PVOID pvRecord; IRecordInfo *pRecInfo; }
+
+    def to_variant_bytes
+      size_out = ("\x00" * 4).b
+      hr = self.class.get_size_fn(@pri).call(@pri, size_out)
+      raise WIN32OLE::RuntimeError, "failed to get size for allocation of VT_RECORD object: #{W.hr_hex(hr)}" if W.failed?(hr)
+
+      # Port of ole_rec2variant (win32ole_record.c:101-103): free the
+      # previously-allocated buffer (if any) before replacing it, so a
+      # Record marshaled more than once doesn't leak one native buffer per
+      # call. The freed/replaced pointer lives in @finalizer_state, the same
+      # mutable Hash the GC finalizer (install_finalizer/self.finalizer)
+      # reads from -- so the finalizer always frees whatever buffer is
+      # current, without ever being re-registered.
+      Fiddle.free(@finalizer_state[:buffer_ptr]) if @finalizer_state[:buffer_ptr]
+
+      size = size_out.unpack1('L')
+      buffer_ptr = Fiddle::Pointer.malloc(size)
+      @finalizer_state[:buffer_ptr] = buffer_ptr
+      hr = self.class.record_init_fn(@pri).call(@pri, buffer_ptr.to_i)
+      raise WIN32OLE::RuntimeError, "failed to initialize VT_RECORD object: #{W.hr_hex(hr)}" if W.failed?(hr)
+
+      @fields.each do |name, val|
+        next if val.nil?
+
+        # Port of hash2olerec (win32ole_record.c:73-81): free the temporary
+        # VARIANT's own BSTR (there VariantClear, here to_free) right
+        # after PutField copies it, not batched at the end.
+        to_free = []
+        var_bytes = WIN32OLE.ruby_value_to_variant_bytes(val, to_free)
+        hr = self.class.put_field_fn(@pri).call(
+          @pri, W::DISPATCH_PROPERTYPUT, buffer_ptr.to_i, W.wstr(name), W.native_pointer_for(var_bytes)
+        )
+        to_free.each(&:call)
+        raise WIN32OLE::RuntimeError, "failed to putfield of `#{name}': #{W.hr_hex(hr)}" if W.failed?(hr)
+      end
+
+      body = [buffer_ptr.to_i, @pri].pack("#{W::PACK_PTR}2")
+      W.pack_variant(W::VT_RECORD, body)
+    end
+
+    def self.from_irecordinfo_and_buffer(pri, prec)
+      allocate.tap { |rec| rec.send(:set_record_info, pri, prec) }
+    end
+
+    private
+
+    def resolve_itypelib_ptr(oleobj)
+      case oleobj
+      when WIN32OLE::TypeLib
+        oleobj.instance_variable_get(:@ptr)
+      when WIN32OLE
+        oleobj.ole_typelib.instance_variable_get(:@ptr)
+      else
+        raise TypeError, "2nd argument should be WIN32OLE object or WIN32OLE::TypeLib object, got #{oleobj.class}"
+      end
+    end
+
+    # Port of recordinfo_from_itypelib (win32ole_record.c:29-59): linear-scan
+    # the typelib's own members for a name match (GetDocumentation), same
+    # already-open-typelib walk TypeLib#ole_types performs -- NOT a walk of
+    # the registry's TypeLib tree. Every non-matching
+    # ITypeInfo* GetTypeInfo AddRef'd along the way must be Released, or
+    # the scan leaks a reference per member it skips past.
+    def find_record_info(itypelib_ptr, typename)
+      count = TI.type_info_count_fn(itypelib_ptr).call(itypelib_ptr)
+      count.times do |i|
+        ti_out = ("\x00" * W::PTR_SIZE).b
+        next if W.failed?(TI.type_info_fn(itypelib_ptr).call(itypelib_ptr, i, ti_out))
+
+        itypeinfo_ptr = ti_out.unpack1(W::PACK_PTR)
+        name_out = ("\x00" * W::PTR_SIZE).b
+        TI.documentation_fn_for_typeinfo(itypeinfo_ptr).call(itypeinfo_ptr, -1, name_out, nil, nil, nil)
+        name_bstr = name_out.unpack1(W::PACK_PTR)
+        name = W.bstr_to_s(name_bstr)
+        W.sys_free_string.call(name_bstr) unless name_bstr.zero?
+
+        if name == typename
+          pri_out = ("\x00" * W::PTR_SIZE).b
+          hr = self.class.get_record_info_from_type_info_fn.call(itypeinfo_ptr, pri_out)
+          release_itypeinfo(itypeinfo_ptr)
+          return W.failed?(hr) ? nil : pri_out.unpack1(W::PACK_PTR)
+        end
+        release_itypeinfo(itypeinfo_ptr)
+      end
+      nil
+    end
+
+    def release_itypeinfo(itypeinfo_ptr)
+      W.vtable_function(itypeinfo_ptr, 2, [W::VOIDP], W::DWORD).call(itypeinfo_ptr)
+    end
+
+    # Shared by .new (prec = nil, every field starts nil) and
+    # .from_irecordinfo_and_buffer
+    # (prec = a real native buffer, fields read via GetFieldNoCopy). Ports
+    # olerecord_set_ivar (win32ole_record.c:122-169).
+    def set_record_info(pri, prec)
+      @pri = pri
+      # Mutable state the GC finalizer closure (below) shares a reference
+      # to -- #to_variant_bytes mutates buffer_ptr in place on
+      # every call. install_finalizer must run exactly once per instance
+      # (set_record_info itself only ever runs once, from .new or
+      # .from_irecordinfo_and_buffer): ObjectSpace.define_finalizer is
+      # additive, so re-registering here would run two finalizers at GC
+      # time and double-Release @pri.
+      @finalizer_state = { pri: pri, buffer_ptr: nil }
+      install_finalizer
+
+      name_out = ("\x00" * W::PTR_SIZE).b
+      if self.class.get_name_fn(pri).call(pri, name_out).zero?
+        bstr = name_out.unpack1(W::PACK_PTR)
+        @typename = W.bstr_to_s(bstr)
+        W.sys_free_string.call(bstr) unless bstr.zero?
+      end
+
+      count_out = ("\x00" * 4).b
+      hr = self.class.get_field_names_fn(pri).call(pri, count_out, nil)
+      count = count_out.unpack1('L')
+      @fields = {}
+      return if W.failed?(hr) || count.zero?
+
+      names_out = ("\x00" * (count * W::PTR_SIZE)).b
+      count_out = [count].pack('L')
+      self.class.get_field_names_fn(pri).call(pri, count_out, names_out)
+      bstrs = names_out.unpack(W::PACK_PTR * count)
+
+      bstrs.each do |bstr|
+        name = W.bstr_to_s(bstr)
+        val = nil
+        if prec
+          var_out = ("\x00" * W::VARIANT_SIZE).b
+          pdata_out = ("\x00" * W::PTR_SIZE).b
+          hr = self.class.get_field_no_copy_fn(pri).call(pri, prec, bstr, var_out, pdata_out)
+          val = WIN32OLE.variant_bytes_to_ruby_value(var_out) if hr.zero?
+        end
+        @fields[name] = val
+        W.sys_free_string.call(bstr) unless bstr.zero?
+      end
+    end
+
+    def install_finalizer
+      release_fn = W.vtable_function(@pri, 2, [W::VOIDP], W::DWORD)
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@finalizer_state, release_fn))
+    end
+
+    # state is the same Hash to_variant_bytes mutates in place -- read
+    # state[:pri]/state[:buffer_ptr] fresh here (at GC time), never close
+    # over a value frozen when the proc was created, or a buffer allocated
+    # after this finalizer was installed would never be freed.
+    # The Release is OLE_FREE, deferred on a thread without OLE (as on
+    # JRuby; see WIN32OLE.finalizer); the buffer is freed right away.
+    def self.finalizer(state, release_fn)
+      proc do
+        pri = state[:pri]
+        W.release_on_ole_thread { release_fn.call(pri) } unless pri.nil? || pri.zero?
+        buffer_ptr = state[:buffer_ptr]
+        Fiddle.free(buffer_ptr) if buffer_ptr
+      end
+    end
+  end
+end