Ruby 3.3 リファレンスマニュアル > ライブラリ一覧 > win32oleライブラリ > WIN32OLEクラス

class WIN32OLE

クラス・モジュールの継承リスト: WIN32OLE < Object < Kernel < BasicObject

要約

OLEオートメーションサーバをRubyで操作するためのクラスです。

Windowsの多くのアプリケーションやライブラリは、COMと呼ばれるAPI群を利用して他のプログラムから操作できます。WIN32OLEがサポートしているのは、 COMのAPIのうち、特にインタープリタ用のインターフェイスであるOLEオートメーション（IDispatchインターフェイス）とそれに付随するリフレクション用のインターフェイスです。

これらのインターフェイスをサポートしている代表的なWindowsアプリケーションに、Office、IE、iTunes、Illustratorがあります。また、WMI、WshShellなどのライブラリを利用してWindowsの情報を操作することも可能です。これらのプログラムをOLEオートメーションサーバと呼びます。

WIN32OLEオブジェクトは、OLEオートメーションサーバが提供するメソッドやプロパティ（Rubyの属性に対応）をスクリプトから呼び出す手段を提供します。呼び出しには、Rubyのオブジェクトと同様にオブジェクトに続けて「.」とメソッド名、必要であれば引数のリストを記述します。最後の引数にHashを指定した場合は、名前付き引数としてキーにパラメータ名、値に引数を指定できます。

サンプルコード

require 'win32ole'

excel = WIN32OLE.new('Excel.Application')
workbook = excel.Workbooks.Open('workbook.xls')
workbook.PrintOut
workbook.Close(:SaveChanges => false)
excel.Quit

なお、OLEオートメーションの仕様ではメソッド名は大文字と小文字を区別しません。そのため、以下のようにOLEオートメーションサーバのメソッド名は小文字で記述しても構いません。

require 'win32ole'

excel = WIN32OLE.new('Excel.Application')
workbook = excel.workbooks.open('workbook.xls')
workbook.printout
workbook.close(:SaveChanges => false)
excel.quit

マルチスレッドでの利用制限

注）以下の記述はWIN32OLEの将来のバージョンの仕様を規定するものではありません。

WIN32OLEはシングルスレッドモードでCOMとインターフェイスします。このため、 ruby 1.9以降のRubyのThreadとネイティブスレッドが1対1で対応する実行環境ではスレッドをまたがる呼び出しはエラーとなります。

excel = WIN32OLE.new('Excel.Application')
Thread.start do
  workbook = excel.Workbooks.Open('workbook.xls') #=> HRESULT error code:0x800401f0
  workbook.PrintOut
  workbook.Close(:SaveChanges => false)
end.join
excel.Quit

発生するエラーはThreadの実行方法によって 0x800401f0（CO_E_NOTINITIALIZED）または0x8001010e（RPC_E_WRONG_THREAD）です。

特異メソッド

定義	説明
`codepage -> Integer`	WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを取得します。
`codepage=(cp) -> nil`	WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを設定します。
`connect(ole) -> WIN32OLE`	現在実行中のOLEオートメーションサーバに接続します。
`const_load(ole, mod = WIN32OLE) -> ()`	OLEオートメーションサーバが保持する定数を読み込み、指定されたモジュールに組み込みます。
`create_guid -> String`	GUID(グローバル一意識別子：Global Unique Identifier)を生成します。
`locale -> Integer`	WIN32OLEがオートメーション呼び出し時に設定するロケール識別子(LCID)を取得します。
`locale=(lcid) -> nil`	WIN32OLEがオートメーション呼び出し時に設定するロケール識別子(LCID)を設定します。
`new(server, host=nil) -> WIN32OLE`	OLEオートメーションサーバを生成します。
`ole_free(aWIN32OLE) -> Integer`	引数で指定したオブジェクトを解放します。
`ole_reference_count(aWIN32OLE) -> Integer`	引数で指定したオブジェクトの現在の参照カウント値を返します。
`ole_show_help(obj, helpcontext = nil) -> ()`	WIN32OLEオブジェクトのヘルプファイルを表示します。

インスタンスメソッド

定義	説明
`self[key...] -> object`	オブジェクトのデフォルトプロパティを参照します。
`self[key...] = value`	オブジェクトのデフォルトプロパティを設定します。
`_getproperty(dispid, args, types) -> object`	DISPIDとパラメータの型を指定してオブジェクトのプロパティを参照します。
`_invoke(dispid, args, types) -> object \| nil`	DISPIDとパラメータの型を指定してオブジェクトのメソッドを呼び出します。
`_setproperty(dispid, args, types) -> ()`	DISPIDとパラメータの型を指定してオブジェクトのプロパティを設定します。
`each {\|i\|...} -> ()`	オブジェクトの列挙インターフェイスを呼び出してアイテム単位にブロックを実行します。
`invoke(name, *args) -> object \| nil`	メソッド名を指定してオブジェクトのメソッドを呼び出します。
`method_missing(id, *args) -> object \| nil`	WIN32OLE#invokeメソッドを実行します。
`ole_activex_initialize -> nil`	ActiveXコントロール用の初期化を行います。
`ole_free -> ()`	selfが参照するCOMオブジェクトを解放します。
`ole_func_methods -> [WIN32OLE_METHOD]`	オブジェクトのファンクション情報をWIN32OLE_METHODの配列として返します。
`ole_get_methods -> [WIN32OLE_METHOD]`	オブジェクトの参照可能プロパティ情報をWIN32OLE_METHODの配列として返します。
`ole_method(method) -> WIN32OLE_METHOD ole_method_help(method) -> WIN32OLE_METHOD`	メソッド名を指定して対応するWIN32OLE_METHODオブジェクトを取得します。
`ole_methods -> [WIN32OLE_METHOD]`	オブジェクトのメソッド情報をWIN32OLE_METHODの配列として返します。
`ole_obj_help -> WIN32OLE_TYPE \| nil ole_type -> WIN32OLE_TYPE \| nil`	WIN32OLE_TYPEオブジェクトを返します。
`ole_put_methods -> [WIN32OLE_METHOD]`	オブジェクトの設定可能プロパティ情報をWIN32OLE_METHODの配列として返します。
`ole_query_interface(iid) -> WIN32OLE`	IID（インターフェイスID）を指定してオブジェクトの別のインターフェイスを持つオブジェクトを取得します。
`ole_respond_to?(name) -> bool`	指定したメソッドをオブジェクトがサポートしているか調べます。
`ole_typelib -> WIN32OLE_TYPELIB`	オブジェクトに対応する型情報ライブラリ（TypeLib）を WIN32OLE_TYPELIBとして返します。
`setproperty(name, val) -> () setproperty(name, args..., val) -> ()`	オブジェクトのプロパティを設定します。

定数

定義	説明
`ARGV -> [object]`	直前のメソッド呼び出しの引数を格納した配列です。
`CP_ACP -> Integer`	Windows既定のANSIコードページ（0）を示します。
`CP_MACCP -> Integer`	Macintoshコードページ（2）を示します。
`CP_OEMCP -> Integer`	OEMコードページ（1）を示します。
`CP_SYMBOL -> Integer`	文字コードの変換にシンボルを利用することを示します（42）。
`CP_THREAD_ACP -> Integer`	現在実行中のスレッドの既定のコードページ（3）を示します。
`CP_UTF7 -> Integer`	文字コードの変換にUTF-7を利用することを示します（65000）。
`CP_UTF8 -> Integer`	文字コードの変換にUTF-8を利用することを示します（65001）。
`LOCALE_SYSTEM_DEFAULT -> Integer`	システム既定のロケールを示すLCID(0x0800)です。WIN32OLEがオートメーションを利用する場合の既定値です。
`LOCALE_USER_DEFAULT -> Integer`	ユーザ既定のロケールを示すLCID(0x0400)です。
`VERSION -> String`	Major.Minor.Patch形式のWIN32OLEのバージョン番号を示す文字列です。

継承したメソッド

! != __id__ __send__ instance_eval instance_exec singleton_method_added singleton_method_removed singleton_method_undefined !~ <=> == === _dump class clone define_singleton_method display enum_for eql? equal? extend freeze frozen? hash initialize initialize_copy inspect instance_of? instance_variable_defined? instance_variable_get instance_variable_set instance_variables is_a? itself marshal_dump marshal_load method methods nil? object_id pretty_inspect pretty_print pretty_print_cycle pretty_print_inspect pretty_print_instance_variables private_methods protected_methods psych_to_yaml public_method public_methods public_send remove_instance_variable respond_to? respond_to_missing? send singleton_class singleton_method singleton_methods tap then to_a to_ary to_hash to_int to_io to_proc to_regexp to_s to_str .yaml_tag ::ARGF ::DATA ::ENV ::RUBY_COPYRIGHT ::RUBY_DESCRIPTION ::RUBY_ENGINE ::RUBY_ENGINE_VERSION ::RUBY_PATCHLEVEL ::RUBY_PLATFORM ::RUBY_RELEASE_DATE ::RUBY_REVISION ::RUBY_VERSION ::SCRIPT_LINES__ ::STDERR ::STDIN ::STDOUT ::TOPLEVEL_BINDING