class WIN32OLE_RECORD (Ruby 4.0 リファレンスマニュアル)

要約

WIN32OLE_RECORDオブジェクトは、OLEオートメーションのVT_RECORD型の値 (構造体)を表します。OLEメソッドの呼び出し結果がVT_RECORD型の場合、 WIN32OLEはWIN32OLE_RECORDオブジェクトを返します。

Ruby 3.2 から、このクラスは WIN32OLE の名前空間下に移動し、WIN32OLE::Record として定義されるようになりました。トップレベル定数 WIN32OLE_RECORD は後方互換のためのエイリアスとして残っていますが、Ruby 3.4 以降は非推奨 (deprecated)です(Warning[:deprecated] が有効なら参照時に警告が表示されます)。

サンプルコード

たとえば、VB.NETで作成したComServerプロジェクトのCOMサーバが、以下のようにtitle（文字列）とcost（整数）の2つのフィールドを持つBook構造体を返すgetBookメソッドを持っているとします。

Imports System.Runtime.InteropServices
Public Class ComClass
    Public Structure Book
        <MarshalAs(UnmanagedType.BStr)> _
        Public title As String
        Public cost As Integer
    End Structure
    Public Function getBook() As Book
        Dim book As New Book
        book.title = "The Ruby Book"
        book.cost = 20
        Return book
    End Function
End Class

このとき、Rubyから次のようにしてgetBookの戻り値を取得できます。

例

require 'win32ole'
obj = WIN32OLE.new('ComServer.ComClass')
book = obj.getBook
book.class # => WIN32OLE::Record
book.title # => "The Ruby Book"
book.cost  # => 20

なお、book.classは常にWIN32OLE::Recordを返します。トップレベル定数 WIN32OLE_RECORDは同じクラスオブジェクトへのエイリアスですが、クラス自体の名前（WIN32OLE::Record.name）は変わりません。

特異メソッド

new(typename, obj) -> WIN32OLE_RECORDRuby 3.0 から[permalink][rdoc][edit]

WIN32OLE_RECORDオブジェクトを生成します。

[PARAM] typename:: 構造体名を文字列またはシンボルで指定します。
[PARAM] obj:: WIN32OLEオブジェクトまたはWIN32OLE_TYPELIBオブジェクトを指定します。typenameで指定した構造体の型情報を取得するために利用します。
[RETURN]: 生成したWIN32OLE_RECORDオブジェクトを返します。
[EXCEPTION] ArgumentError:: typenameがStringまたはSymbolではありません。あるいは obj がWIN32OLEオブジェクトまたはWIN32OLE_TYPELIBオブジェクトのいずれでもありません。
[EXCEPTION] WIN32OLERuntimeError:: objからITypeLibインタフェースの取得に失敗しました。あるいはtypenameに対応する IRecordInfoインタフェースの取得に失敗しました。

VB.NETのComServerプロジェクトで、以下のBook構造体を持つCOMサーバがあるとします。

Imports System.Runtime.InteropServices
Public Class ComClass
    Public Structure Book
        <MarshalAs(UnmanagedType.BStr)> _
        Public title As String
        Public cost As Integer
    End Structure
End Class

このとき、次のようにしてWIN32OLE_RECORDオブジェクトを生成できます。

例

require 'win32ole'
obj = WIN32OLE.new('ComServer.ComClass')
book1 = WIN32OLE_RECORD.new('Book', obj) # => WIN32OLE_RECORDオブジェクト
tlib = obj.ole_typelib
book2 = WIN32OLE_RECORD.new('Book', tlib) # => WIN32OLE_RECORDオブジェクト

インスタンスメソッド

inspect -> StringRuby 3.0 から[permalink][rdoc][edit]

selfが表すOLEの構造体名と各メンバ名、その値を含む文字列を返します。

なお、返す文字列中のクラス名部分は、selfをトップレベル定数 WIN32OLE_RECORD経由で生成した場合であっても、常にWIN32OLE::Record と表示されます。

VB.NETのComServerプロジェクトで作成したCOMサーバの以下のBook構造体に対して、

Imports System.Runtime.InteropServices
Public Class ComClass
    <MarshalAs(UnmanagedType.BStr)> _
    Public title As String
    Public cost As Integer
End Class

例

server = WIN32OLE.new('ComServer.ComClass')
obj = WIN32OLE_RECORD.new('Book', server)
obj.inspect # => "#<WIN32OLE::Record(ComClass) {\"title\" => nil, \"cost\" => nil}>"

method_missing(name, *args) -> objectRuby 3.0 から[permalink][rdoc][edit]

VT_RECORD OLE変数のメンバ名に対応する値を取得、または設定します。

引数がnameだけの場合（book.titleのようにgetterとして未定義メソッドが呼び出された場合）はメンバの値を取得します。引数がname、valの2つの場合（book.title = "..."のようにsetterとして未定義メソッドが呼び出された場合）は、nameの末尾の「=」を取り除いたメンバ名にvalを設定します。指定したメンバ名が存在しない場合はKeyErrorが発生します。

[PARAM] name:: アクセスするメンバ名に対応するメソッド名（シンボル）です。 setterの場合は末尾に「=」が付きます。
[PARAM] args:: setterとして呼び出された場合、設定する値を1つ指定します。 getterとして呼び出された場合は空です。
[RETURN]: getterとして呼び出された場合はメンバの値、setterとして呼び出された場合は設定した値を返します。
[EXCEPTION] KeyError:: 指定したメンバ名がselfに存在しません。

VB.NETのComServerプロジェクトで作成したCOMサーバの以下のBook構造体に対して、

Imports System.Runtime.InteropServices
Public Class ComClass
    Public Structure Book
        <MarshalAs(UnmanagedType.BStr)> _
        Public title As String
        Public cost As Integer
    End Structure
End Class

値の取得・設定は次のようにメンバ名をメソッドとして呼び出すことで行います（実際には、method_missingが呼び出されます）。

例

obj = WIN32OLE.new('ComServer.ComClass')
book = WIN32OLE_RECORD.new('Book', obj)
book.title # => nil ( book.method_missing(:title) が呼び出される )
book.title = "Ruby" # ( book.method_missing(:title=, "Ruby") が呼び出される )

[SEE_ALSO] WIN32OLE_RECORD#ole_instance_variable_get, WIN32OLE_RECORD#ole_instance_variable_set

ole_instance_variable_get(name) -> objectRuby 3.0 から[permalink][rdoc][edit]

VT_RECORD OLE変数のメンバ名に対応する値を取得します。メンバ名が正しくない場合はKeyErrorが発生します。

RubyのObjectが持つメソッドと同名のメンバを持つなど、メンバに WIN32OLE_RECORD#method_missing経由で直接アクセスできない場合に利用します。

[PARAM] name:: 取得するメンバ名を文字列またはシンボルで指定します。
[RETURN]: 指定したメンバの値を返します。
[EXCEPTION] TypeError:: nameがStringまたはSymbolではありません。
[EXCEPTION] KeyError:: 指定したメンバ名がselfに存在しません。

VB.NETのComServerプロジェクトで作成したCOMサーバの以下のComObject構造体（Object#object_idと同名のメンバを持つ）に対して、

Imports System.Runtime.InteropServices
Public Class ComClass
    Public Structure ComObject
        Public object_id As Integer
    End Structure
End Class

以下のようにすると、obj.object_idはRubyのObject#object_idを返してしまうため、代わりにole_instance_variable_getを利用します。

例

server = WIN32OLE.new('ComServer.ComClass')
obj = WIN32OLE_RECORD.new('ComObject', server)
# obj.object_id はRubyのObject#object_idを返してしまう
obj.ole_instance_variable_get(:object_id) # => nil

[SEE_ALSO] WIN32OLE_RECORD#method_missing, WIN32OLE_RECORD#ole_instance_variable_set

ole_instance_variable_set(name, val) -> objectRuby 3.0 から[permalink][rdoc][edit]

VT_RECORD OLE変数のメンバ名に対応する値を設定します。メンバ名が正しくない場合はKeyErrorが発生します。

WIN32OLE_RECORD#method_missing経由でメンバの値を直接設定できない場合に利用します。

[PARAM] name:: 設定するメンバ名を文字列またはシンボルで指定します。
[PARAM] val:: 設定する値を指定します。
[RETURN]: 設定した値を返します。
[EXCEPTION] TypeError:: nameがStringまたはSymbolではありません。
[EXCEPTION] KeyError:: 指定したメンバ名がselfに存在しません。

VB.NETのComServerプロジェクトで作成したCOMサーバの以下のBook構造体の titleメンバに値を設定するには、次のようにします。

Imports System.Runtime.InteropServices
Public Class ComClass
    <MarshalAs(UnmanagedType.BStr)> _
    Public title As String
    Public cost As Integer
End Class

例

server = WIN32OLE.new('ComServer.ComClass')
obj = WIN32OLE_RECORD.new('Book', server)
obj.ole_instance_variable_set(:title, "The Ruby Book")

[SEE_ALSO] WIN32OLE_RECORD#method_missing, WIN32OLE_RECORD#ole_instance_variable_get

to_h -> HashRuby 3.0 から[permalink][rdoc][edit]

selfが表すVT_RECORD値をRubyのHashオブジェクトに変換して返します。

Hashのキーは、VT_RECORD OLE変数のメンバ名、値はその値です。

[RETURN]: VT_RECORD値の各メンバ名と値からなるHashオブジェクトを返します。

VB.NETのComServerプロジェクトで作成したCOMサーバの以下のgetBookメソッドの戻り値に対して、

Imports System.Runtime.InteropServices
Public Class ComClass
    Public Structure Book
        <MarshalAs(UnmanagedType.BStr)> _
        Public title As String
        Public cost As Integer
    End Structure
    Public Function getBook() As Book
        Dim book As New Book
        book.title = "The Ruby Book"
        book.cost = 20
        Return book
    End Function
End Class

WIN32OLE_RECORD#to_hを呼び出すと、以下のようになります。

例

require 'win32ole'
obj = WIN32OLE.new('ComServer.ComClass')
book = obj.getBook
book.to_h # => {"title"=>"The Ruby Book", "cost"=>20}

typename -> StringRuby 3.0 から[permalink][rdoc][edit]

selfが表すVT_RECORD OLE変数の型名（構造体名）を返します。

[RETURN]: VT_RECORD OLE変数の型名を文字列で返します。

例

require 'win32ole'
obj = WIN32OLE.new('ComServer.ComClass')
book = obj.getBook
book.typename # => "Book"

要約

サンプルコード

目次

特異メソッド

インスタンスメソッド