type=class
superclass=Object
included=
extended=
library=win32ole
aliases=
aliasof=

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）
です。
