Ruby 1.9.3 リファレンスマニュアル > ライブラリ一覧 > win32oleライブラリ > 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 -> Fixnum[permalink][rdoc]WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを 取得します。
OLEオートメーションに利用する文字列はUnicodeでエンコードします。 WIN32OLEはここで示されたコードページを利用してRubyのStringとUnicodeの相 互変換を行います。
ロード時の既定値はEncoding.default_internal、または Encoding.default_internalがnilの場合はEncoding.default_externalによって 求めたエンコーディングに対応するコードページです。もし、該当するコード ページが見つからない場合は、WIN32OLE::CP_ACPを利用します。
WIN32OLE.codepage # => 932 （日本語Windowsの既定値）
codepage=(cp) -> nil[permalink][rdoc]WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを 設定します。
WIN32OLEは、OLEオートメーション呼び出しに利用する文字列のUnicode変換に ここで設定したコードページを利用します。通常、WIN32OLEはロード時の Encoding.default_internalまたはEncoding.default_externalから適切なコー ドページを判断し、それを利用します。したがって、当メソッドを呼び出す必 要があるのは、WIN32OLEをrequireしたスクリプトと異なるエンコーディングを 利用しているスクリプトや、異なるエンコーディングを利用しているファイル から読み込んだ文字列を利用してWIN32OLEを呼び出す場合です。
WIN32OLE.codepage = WIN32OLE::CP_UTF8
connect(ole) -> WIN32OLE[permalink][rdoc]現在実行中のOLEオートメーションサーバに接続します。
connectメソッドは、COMのモニカを利用して、現在実行中のOLEオートメーショ ンサーバを検索し、接続します。接続に成功した場合、該当サーバを操作可能 なWIN32OLEオブジェクトが返ります。
WIN32OLE.connect('Excel.Application') # => WIN32OLE object which represents running Excel.
OLEオートメーションサーバを識別するための文字列。通常「ベンダー名.ア プリケーション名.インターフェイス名」の形式を取ります。レジストリの HKEY_CLASSES_ROOTの「.」で始まらないキーとして登録されます。
OLEオートメーションサーバを含むCOMのクラスを識別するための128ビット GUID。文字列表現は、レジストリのHKEY_CLASSES_ROOT\CLSID下のキーとして登 録されます。
モニカは、URIのようにWindows上のリソースを一意に識別するためのオブジェ クトのインターフェイスで、文字表現を持ちます。詳細については http://msdn.microsoft.com/en-us/library/ms691261(v=VS.85).aspx を参照してください。
const_load(ole, mod = WIN32OLE) -> ()[permalink][rdoc]OLEオートメーションサーバが保持する定数を読み込み、指定されたモジュール に組み込みます。
OLEオートメーションサーバは、定数をクライアントへ提供できます。
const_loadメソッドはこれらの定数を読み込み、指定したモジュールに組み込 むことで参照可能とします。
OLEオートメーションの定数は通常、VBのコード規約に準じて、vbConstantsの ように小文字で始まります。しかし、Rubyの定数は大文字で開始する規則のた め、WIN32OLEによってVbConstantsのように自動的に先頭が大文字化されます。
また、先頭が英字で始まらない定数については、CONSTANTSハッシュに登録され ます。この場合、元の定数名がキーとなります。
module EXCEL_CONST
end
excel = WIN32OLE.new('Excel.Application')
WIN32OLE.const_load(excel, EXCEL_CONST)
puts EXCEL_CONST::XlTop # => -4160
puts EXCEL_CONST::CONSTANTS['_xlDialogChartSourceData'] # => 541
モジュール名を省略した例
WIN32OLE.const_load(excel) puts WIN32OLE::XlTop # => -4160
タイプライブラリ名を指定した例
module MSO
end
WIN32OLE.const_load('Microsoft Office 9.0 Object Library', MSO)
puts MSO::MsoLineSingle # => 1
create_guid -> String[permalink][rdoc]GUID(グローバル一意識別子：Global Unique Identifier)を生成します。
GUIDは、COMのクラス識別子(CLSID)、インターフェイス識別子(IID)など多数の 領域でWindows上のオブジェクトの識別に利用される128ビットの値です。
WIN32OLEが生成するGUIDは以下の形式によるGUIDの文字列表現です。なお00〜 FFはGUIDの先頭からのバイト位置を示します。これはレジストリのキーとして 利用される形式です。
{33221100-5544-7766-8899-AABBCCDDEEFF}
WIN32OLE.create_guid # => "{????????-????-????-????-????????????}"
locale -> Fixnum[permalink][rdoc]WIN32OLEがオートメーション呼び出し時に設定するロケール識別子(LCID)を取 得します。
OLEオートメーションでは、UNIXで利用される"ja_JP"などの国名と言語名を「_」 で接続した文字列ではなく、32ビット整数で示します。32ビットの内訳は上位 16ビットが予約領域で0、下位16ビットが言語ID(LANGID）です。LANGIDは、0〜 9ビットでプライマリ言語ID、10〜15ビットでサブ言語IDを示します。
ロード時の既定値はWIN32OLE::LOCALE_SYSTEM_DEFAULTです。
lcid = WIN32OLE.locale
locale=(lcid) -> nil[permalink][rdoc]WIN32OLEがオートメーション呼び出し時に設定するロケール識別子(LCID)を設 定します。
OLEオートメーションでは、UNIXで利用される"ja_JP"などの国名と言語名を「_」 で接続した文字列ではなく、32ビット整数で示します。32ビットの内訳は上位 16ビットが予約領域で0、下位16ビットが言語ID(LANGID）です。LANGIDは、0〜 9ビットでプライマリ言語ID、10〜15ビットでサブ言語IDを示します。
WIN32OLE.locale = 1033 # set locale English(U.S)
obj = WIN32OLE_VARIANT.new("$100,000", WIN32OLE::VARIANT::VT_CY)
オブジェクトがサポートしていないロケールを設定した場合、オブジェクトのメソッド呼び出し時にDISP_E_UNKNOWNLCID(HRESULT error code:0x8002000C)や、TYPE_E_INVDATAREAD(HRESULT error code:0x80028018)などを理由としたWIN32OLERuntimeError例外となります。ほとんどすべての場合において、既定値を変更する必要はありません。
new(server, host=nil) -> WIN32OLE[permalink][rdoc]OLEオートメーションサーバを生成します。
引数で指定したCLSIDまたはPROGIDを持つOLEオートメーションサーバを生成し ます。生成に成功した場合、該当サーバを操作可能なWIN32OLEオブジェクトが 返ります。
CLSIDおよびPROGIDについてはWIN32OLE.connectを参照してください。
WIN32OLE.new('Excel.Application') # => Excel OLE Automation WIN32OLE object.
WIN32OLE.new('{00024500-0000-0000-C000-000000000046}') # => Excel OLE Automation WIN32OLE object.
ole_free(aWIN32OLE) -> Integer[permalink][rdoc]引数で指定したオブジェクトを解放します。
このメソッドは主にWIN32OLEのデバッグおよびWIN32OLEを利用するミドルウェ アの実装のために用意されています。このため、メソッドの内部動作は不定で す。COMの仕様とWIN32OLEの内部処理に熟知していない場合は使用しないでくだ さい。
ole_reference_count(aWIN32OLE) -> Integer[permalink][rdoc]引数で指定したオブジェクトの現在の参照カウント値を返します。
このメソッドは主にWIN32OLEのデバッグおよびWIN32OLEを利用するミドルウェ アの実装のために用意されています。このため、メソッドの内部動作は不定で す。COMの仕様とWIN32OLEの内部処理に熟知していない場合は使用しないでくだ さい。
ole_show_help(obj, helpcontext = nil) -> ()[permalink][rdoc]WIN32OLEオブジェクトのヘルプファイルを表示します。
Windows標準のヘルプ表示コンポーネントのHHCtrl.OCXを利用して、オブジェク トに関連付けられたヘルプファイル（chmファイル）を表示します。
また、chmファイルのフルパス名を指定して表示させることも可能です。
excel = WIN32OLE.new('Excel.Application')
typeobj = excel.ole_obj_help
WIN32OLE.ole_show_help(typeobj) if typeobj.helpfile
self[key...] -> object[permalink][rdoc]オブジェクトのデフォルトプロパティを参照します。
OLEオートメーションにはデフォルトプロパティというプロパティ名を指定せず にアクセスできるプロパティがあります。
WIN32OLEからデフォルトプロパティにアクセスするには、[]内に必要なキーを 「,」で区切って記述します。シンボルは文字列として扱います。
なおデフォルトプロパティは記述が省略できるプロパティ名に意味がないため、 OLEオートメーション規約ではItemと命名することが決められています。
fsys = WIN32OLE.new('Scripting.FileSystemObject')
fsys.Drives[:c].FreeSpace #=> Cドライブの空き容量
self[key...] = value[permalink][rdoc]オブジェクトのデフォルトプロパティを設定します。
OLEオートメーションにはデフォルトプロパティというプロパティ名を指定せず にアクセスできるプロパティがあります。
WIN32OLEからデフォルトプロパティにアクセスするには、[]内に必要なキーを 記述します。
なおデフォルトプロパティは記述が省略できるプロパティ名には意味がありま せん。このためOLEオートメーション規約では一律にItemと命名することが決め られています。
dict = WIN32OLE.new('Scripting.Dictionary')
dict[:a] = 0x41
dict[:b] = 0x42
dict[:a] #=> 65
dict[:b] #=> 66
_getproperty(dispid, args, types) -> object[permalink][rdoc]DISPIDとパラメータの型を指定してオブジェクトのプロパティを参照します。
アクセスするプロパティのインターフェイスを事前に知っている場合に、 DISPIDとパラメータの型を指定してプロパティを参照します。
このメソッドはCOMアーリーバインディングを利用することで外部プロセスサー バとのラウンドトリップを減らして処理速度を向上させることを目的としたも のです。このため、DLLの形式で型情報（TypeLib）を提供しているサーバに対 してはあまり意味を持ちません。
DISPID_CELLS = 238
include WIN32OLE::VARIANT
excel = WIN32OLE.new('Excel.Application')
puts excel._getproperty(558, [], []) # VisibleプロパティのDISPIDは558
workbook = excel.Workbooks.Add
sheet = workbook.Worksheets[1]
sheet._setproperty(DISPID_CELLS, [1, 2, 'hello'], [VT_I2, VT_I2, VT_BSTR])
puts sheet._getproperty(DISPID_CELLS, [1, 2], [VT_I2, VT_I2]).value #=> 'hello'
workbook.Close(:SaveChanges => false)
excel.Quit
DISPIDはWIN32OLE_METHOD#dispidから取得できます。
[SEE_ALSO] WIN32OLE::VARIANT
_invoke(dispid, args, types) -> object | nil[permalink][rdoc]DISPIDとパラメータの型を指定してオブジェクトのメソッドを呼び出します。
呼び出すメソッドのインターフェイスを事前に知っている場合に、DISPIDとパ ラメータの型を指定してメソッドを呼び出します。
このメソッドは引数の変換方法をプログラマが制御できるようにすることと、 COMアーリーバインディングを利用して外部プロセスサーバとのラウンドトリッ プを減らして処理速度を向上させることを目的としたものです。後者の目的に ついては、DLLの形式で型情報（TypeLib）を提供しているサーバに対してはあ まり意味を持ちません。そのため、型の高精度な制御が不要な場合は、直接メ ソッド名を指定したメソッド呼び出しを行うことを、プログラムの可読性の点 から推奨します。
excel = WIN32OLE.new('Excel.Application')
excel._invoke(302, [], []) # DISPID 302は、Quitメソッド
MFCの制約により、バイト配列の型情報は通常 WIN32OLE::VARIANT::VT_VARIANTとなります。このような場合に、バイト 配列を与えるつもりで
include WIN32OLE::VARIANT obj.method(DISPID, [[0, 1, 2, 3]], [VT_VARIANT])
のように記述すると、単に32ビット整数（VT_I4）の配列が送られることになり 空間効率が低下します。
引数の最終的な型がわかっている場合は、下記の例のように型指定パラメータ には実際の型を指定してください。
include WIN32OLE::VARIANT obj.method(DISPID, [[0, 1, 2, 3]], [VT_BYREF | VT_ARRAY | VT_UI1])
なお、VB6で作成したCOMコンポーネントのパラメータに配列を与える場合は、 WIN32OLE::VARIANT::VT_BYREFの指定が必須です。
DISPIDはWIN32OLE_METHOD#dispidから取得できます。
[SEE_ALSO] WIN32OLE::VARIANT
_setproperty(dispid, args, types) -> ()[permalink][rdoc]DISPIDとパラメータの型を指定してオブジェクトのプロパティを設定します。
アクセスするプロパティのインターフェイスを事前に知っている場合に、 DISPIDとパラメータの型を指定してプロパティを設定します。
このメソッドはCOMアーリーバインディングを利用することで外部プロセスサー バとのラウンドトリップを減らして処理速度を向上させることを目的としたも のです。このため、DLLの形式で型情報（TypeLib）を提供しているサーバに対 してはあまり意味を持ちません。
DISPID_CELLS = 238
include WIN32OLE::VARIANT
excel = WIN32OLE.new('Excel.Application')
puts excel._setproperty(558, # VisibleプロパティのDISPIDは558
[true], [VT_BOOL])
workbook = excel.Workbooks.Add
sheet = workbook.Worksheets[1]
sheet._setproperty(DISPID_CELLS, [1, 2, 'hello'], [VT_I2, VT_I2, VT_BSTR])
puts sheet._getproperty(DISPID_CELLS, [1, 2], [VT_I2, VT_I2]).value #=> 'hello'
workbook.Close(:SaveChanges => false)
excel.Quit
DISPIDはWIN32OLE_METHOD#dispidから取得できます。
[SEE_ALSO] WIN32OLE::VARIANT
each {|i|...} -> ()[permalink][rdoc]オブジェクトの列挙インターフェイスを呼び出してアイテム単位にブロックを 実行します。
OLEオートメーションサーバの中には、コレクション用インターフェイスを持つ ものがあります。eachメソッドは、このようなオブジェクトの列挙メソッドを 呼び出して、アイテム毎のイテレーションを行います。
excel = WIN32OLE.new('Excel.Application')
book = excel.workbooks.add
sheets = book.worksheets(1)
cells = sheets.cells("A1:A5")
cells.each do |cell|
cell.value = 10
end
excel.Quit
invoke(name, *args) -> object | nil[permalink][rdoc]メソッド名を指定してオブジェクトのメソッドを呼び出します。
OLEオートメーションサーバのメソッドを動的に呼び出したい場合に利用します。
なお、OLEオートメーションの仕様により、メソッド名の大文字、小文字は区別 されません。
このリストは、以下の記述と同等です。
excel = WIN32OLE.new('Excel.Application')
workbook = excel.workbooks.Open(:FileName => 'c:\\users\\public\\test.xml',
:ReadOnly => true,
:Password => 'secret')
excel.Quit
method_missing(id, *args) -> object | nil[permalink][rdoc]WIN32OLE#invokeメソッドを実行します。
WIN32OLEのインスタンスに対して、このリファレンスに明記されていないメソッ ドを呼び出した場合、OLEオートメーションサーバのメソッド（プロパティ）呼 び出しと解釈します。
WIN32OLEはOLEオートメーションオブジェクトのメソッド呼び出しを method_missingを利用して実行します。このためWIN32OLEを継承するクラスを 作成してmethod_missingをオーバーライドする場合、superを呼び出してくださ い。
[SEE_ALSO] WIN32OLE#invoke
ole_activex_initialize -> nil[permalink][rdoc]ActiveXコントロール用の初期化を行います。
ole_activex_initializeメソッドは、スクリプト内でActiveXコントロールを利 用できるように、オブジェクトが持つ永続化データを初期化します。
ActiveXコントロール（OCX）は、主にUI用に利用されるOLEオートメーションサー バです。ActiveXコントロールは、IDEを利用した開発時と、プログラムの実行 時の2種類の実行モードを持ちます。これは、開発時の設定を永続化するためで す。
幾つかのActiveXコントロールは、上記の動作を前提に組まれているため、実行 に先だって永続化データの転送をデータの有無と関係なく要求します。この場 合、もし永続化データを初期化しないと、実行時モード状態へ遷移せず、後続 のメソッド呼び出しがすべてエラーとなります。
obj = WIN32OLE.new("ProgID_or_GUID_of_ActiveX_Control")
obj.ole_activex_initialize
obj.method(...)
なお、生成したOLEオートメーションサーバが永続化データの初期化を必要とす るActiveXコントロールか、そうでないかを簡単に区別する方法はありません。 そのため、とりあえず普通にメソッドを呼び出し、その結果 WIN32OLERuntimeErrorが通知され、メッセージにHRESULT 0x8000ffffと示され ている場合にのみ、オブジェクト生成直後に当メソッドを呼び出してみてくだ さい。
また、オブジェクトによっては、当メソッドの呼び出しにより後続のデータを 要求してハングアップする場合があります。その場合は、Ctrl-Cなどによって 実行を中止してください。
ole_free -> ()[permalink][rdoc]selfが参照するCOMオブジェクトを解放します。
selfが参照するCOMオブジェクトのIUnknown::Releaseを呼び出すことで、COMオ ブジェクトを開放します。ole_freeを呼び出した後は、このオブジェクトに対 する操作は行えません。
excel = WIN32OLE.new('Excel.Application')
excel.ole_free # オブジェクトの解放
excel.Quit #=> RuntimeError (failed to get Dispatch Interface)
通常は利用されなくなったWIN32OLEオブジェクトはGCのタイミングで自動的に 解放されるため、当メソッドを呼び出す必要はありません。Officeのような外 部プロセスサーバ呼び出し時に、スクリプト終了後もサーバが解放されない場 合に強制的にサーバを終了するために当メソッドを利用できます。ただし、現 実には途中で生成される子オブジェクトからの逆参照などがあるため、 WIN32OLEがIUnknown::Releaseを呼び出してもオブジェクトが解放されるとは限 りません。
excel = WIN32OLE.new('Excel.Application')
workbook = excel.Workbooks.Open('workbook.xls')
workbook.Close(:SaveChanges => false)
workbook.ole_free
excel.ole_free
# この時点でExcel.EXEは終了しない
上の例では、excel.Workbooks.Openの行で、excel.Workbooksオブジェクトが生 成されています。しかし、後続の処理で該当オブジェクトが解放されていない ため、Workbooksオブジェクトによって参照されているexcelオブジェクトは解 放されません。それに対して下の例では正しく解放されます。
excel = WIN32OLE.new('Excel.Application')
books = excel.Workbooks
workbook = books.Open('workbook.xls')
books.ole_free
workbook.Close(:SaveChanges => false)
workbook.ole_free
excel.ole_free
ole_func_methods -> [WIN32OLE_METHOD][permalink][rdoc]オブジェクトのファンクション情報をWIN32OLE_METHODの配列として返し ます。
ole_func_methodsメソッドは、OLEオートメーションサーバのメソッドのうちファ ンクション（何らかの機能的な操作）に属するものをWIN32OLE_METHODの 配列として返します。
excel = WIN32OLE.new('Excel.Application')
excel.visible = true
excel.ole_func_methods.each do |fun|
if fun.name.upcase == 'QUIT'
excel._invoke(fun.dispid, [], [])
break
end
end
[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_get_methods, WIN32OLE#ole_put_methods
ole_get_methods -> [WIN32OLE_METHOD][permalink][rdoc]オブジェクトの参照可能プロパティ情報をWIN32OLE_METHODの配列として 返します。
ole_get_methodsメソッドは、OLEオートメーションサーバのメソッドのうち読 み取り可能なプロパティをWIN32OLE_METHODの配列として返します。
excel = WIN32OLE.new('Excel.Application')
excel.ole_get_methods.each do |prop|
begin
puts "#{prop.name}=#{excel._getproperty(prop.dispid, [], [])}"
rescue WIN32OLERuntimeError
puts "can't read #{prop.name} property"
end
end
[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_func_methods, WIN32OLE#ole_put_methods
ole_method(method) -> WIN32OLE_METHOD[permalink][rdoc]ole_method_help(method) -> WIN32OLE_METHODメソッド名を指定して対応するWIN32OLE_METHODオブジェクトを取得しま す。
OLEオートメーションの仕様により、メソッド名の大文字、小文字は区別されま せん。
excel = WIN32OLE.new('Excel.Application')
method = excel.ole_method_help('Quit')
ole_methods -> [WIN32OLE_METHOD][permalink][rdoc]オブジェクトのメソッド情報をWIN32OLE_METHODの配列として返します。
ole_methodsメソッドは、OLEオートメーションサーバが提供するすべてのメソッ ドをWIN32OLE_METHODの配列として返します。
excel = WIN32OLE.new('Excel.Application')
methods = excel.ole_methods
[SEE_ALSO] WIN32OLE#ole_func_methods, WIN32OLE#ole_put_methods
ole_obj_help -> WIN32OLE_TYPE | nil[permalink][rdoc]ole_type -> WIN32OLE_TYPE | nilWIN32OLE_TYPEオブジェクトを返します。
WIN32OLE_TYPEオブジェクトは、WIN32OLEオブジェクトの文書情報と型情 報を保持するオブジェクトです。
excel = WIN32OLE.new('Excel.Application')
tobj = excel.ole_obj_help
[SEE_ALSO] WIN32OLE_TYPE
ole_put_methods -> [WIN32OLE_METHOD][permalink][rdoc]オブジェクトの設定可能プロパティ情報をWIN32OLE_METHODの配列として 返します。
ole_put_methodsメソッドは、OLEオートメーションサーバのメソッドのうちプ ロパティ設定メソッドに属するものをWIN32OLE_METHODの配列として返し ます。
excel = WIN32OLE.new('Excel.Application')
properties = excel.ole_put_methods
[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_func_methods, WIN32OLE#ole_get_methods
ole_query_interface(iid) -> WIN32OLE[permalink][rdoc]IID（インターフェイスID）を指定してオブジェクトの別のインターフェイスを 持つオブジェクトを取得します。
オブジェクトが複数のオートメーション用インターフェイスを持つ場合に、当 メソッドを利用して既定のインターフェイスとは異なるインターフェイスを取 得します。
ie = WIN32OLE.new('InternetExplorer.Application')
ie_web_app = ie.ole_query_interface('{0002DF05-0000-0000-C000-000000000046}')
上例のie_web_appは、ieと同じインスタンスとなります。
COMの仕様では1つのインターフェイスについて同じIID問い合わせに対しては常 に同一のインターフェイスを返すことが決められています。
このため、正しく実装されたOLEオートメーションサーバでは本メソッドが意味 を持つことはありません。というのは、2つ以上の異なるWIN32OLEで操作可能な インターフェイスを持つということは、IID_IDispatch（OLEオートメーション のインターフェイスID）を指定した問い合わせに対して異なるインターフェイ スを返すということになるからです。これは、結果的に呼び出し側プログラム がいつでも間違えたインターフェイスを呼び出す可能性を持つということを意 味します。当然、それはサーバ実装のバグです。
問題は、C++のvtblアクセスや.NET FrameworkのCOM Interopのために静的型情 報が必要となることです。このため、一度あるインターフェイスを返すことに 決めた場合、実際に返すインターフェイスが元のインターフェイスを継承して いたとしても、ドキュメント上は異なるインターフェイスとして定義しなけれ ば追加のメソッドが呼び出せません。
たとえば、当メソッドの存在理由である http://www.ruby-forum.com/topic/109954（なお、元のパッチと異な りGUIDの統一フォーマットを利用するように改造されているため、IIDの前後に {}が必要です）には、Solutionオブジェクトに対してSolution2オブジェクトの 取得を依頼するために、必要ということになっています。実際、Solutionプロ パティが返すのは、この場合はSolutionインターフェイスを継承した Solution2インターフェイスです。しかし、Solutionプロパティの型情報は Solutionインターフェイスを返すことになっているため、静的に型を解決して いる場合は、追加のメソッドの呼び出しを記述できません。
しかし、WIN32OLEが利用するIDispatchインターフェイスは、メソッド名による 動的なメソッド検索が行われます。このため、Solutionオブジェクト（しかし その実態はSolution2オブジェクト）に対してSolution2で追加されたメソッド （たとえばGetProjectTemplate）を指定したとしても正しく呼び出せます。つ まり、http://www.ruby-forum.com/topic/109954で例示されているよ うなole_query_interfaceメソッドの呼び出しは不要です。
もし、当メソッドの呼び出しが本当に必要なのであれば、まず、該当するOLEオー トメーションサーバの修正を依頼してください。その実装は正しくありません。
正しく実装されたオブジェクトに対して当メソッドを適用すると、結果として、 同一オブジェクトの参照カウント値を無駄に増加させることになります。
なお、サポートしているインターフェイスのバージョンを調べたい場合に、以 下のような方法で、インターフェイスのバージョンを調べることができます。
def check_solution_version(obj)
[['{CDA7305C-78B6-4D9D-90AD-93EBE71F9341}', 4],
['{DF23915F-FDA3-4DD5-9CAA-2E1372C2BB16}', 3],
['{FA238614-FBB1-4314-A7F7-49AE8BB6C6BA}', 2]].each do |iid, ver|
begin
intf = obj.ole_query_interface(iid)
intf.ole_free
return ver
rescue WIN32OLERuntimeError
end
end
1
end
しかし、ole_query_interfaceのような特異なメソッドを利用するよりも、 WIN32OLE.new('VisualStudio.DTE.8.0') のように生成時にバージョン番号（こ の例では8.0）を指定するほうが良いスタイルです。
また、単に特定のメソッドをサポートしているかどうかを知りたいだけであれ ば、WIN32OLE#ole_respond_to?を利用したダックタイピングをしてくだ さい。
ole_respond_to?(name) -> bool[permalink][rdoc]指定したメソッドをオブジェクトがサポートしているか調べます。
OLEオートメーションサーバが引数で指定した名前のメソッド（プロパティ）を サポートしているかどうかを調べます。
なお、OLEオートメーションの仕様により、メソッド名の大文字、小文字は区別 されません。
excel = WIN32OLE.new('Excel.Application')
excel.ole_respond_to?(:quit) #=> true
excel.ole_respond_to?(:exit) #=> false
ole_typelib -> WIN32OLE_TYPELIB[permalink][rdoc]オブジェクトに対応する型情報ライブラリ（TypeLib）を WIN32OLE_TYPELIBとして返します。
OLEオートメーションではクラス、インターフェイス、メソッド、引数などの型 情報と文書情報を型情報ライブラリとして利用します。型情報ライブラリは独 立したファイル（拡張子tlb）の場合もあれば、オブジェクトのバイナリへリソー スとして埋め込まれている場合があります。
OLEオートメーションでは型情報ライブラリの提供方法を問わずに統一したイン ターフェイスでアプリケーションが参照できるように、オブジェクトの形式 （ITypeInfoインターフェイス）で提供します。WIN32OLEは、このオブジェクト をラップしてWIN32OLE_TYPELIBとして提供します。
excel = WIN32OLE.new('Excel.Application')
tlib = excel.ole_typelib
puts tlib.name # => 'Microsoft Excel 9.0 Object Library'
setproperty(name, val) -> ()[permalink][rdoc]setproperty(name, args..., val) -> ()オブジェクトのプロパティを設定します。
プロパティ名を指定してOLEオートメーションオブジェクトのプロパティ （Rubyの属性に相当）を設定します。
なお、OLEオートメーションの仕様により、プロパティ名の大文字、小文字は区 別されません。
OLEオートメーションのプロパティはRubyの属性と異なり、パラメータを取るこ とができます。
たとえばExcelのWorksheetオブジェクトのCellsプロパティは桁位置と行番号の 2つのパラメータを取ります。
これはVBでは次のように記述できます。
sheet.Cells(1, 1) = sheet.Cells(1, 2) ' セルB1の内容をセルA1へ
Rubyでは上記のコードの右辺をVBと同じく「sheet.Cells(1, 2)」のように記述 できますが、左辺の記述はできません。
そのため、次の例のようにsetpropertyメソッドを利用して、パラメータ付きプ ロパティを設定します。
excel = WIN32OLE.new('Excel.Application')
excel.visible = true
sheet = excel.Workbooks.Add.Worksheets[1]
sheet.setproperty(:Cells, 1, 2, 32)
sheet.setproperty(:Cells, 1, 1, sheet.Cells(1, 2))
ARGV -> [object][permalink][rdoc]直前のメソッド呼び出しの引数を格納した配列です。
OLEオートメーションでは呼び出し先が引数に対して値を設定できます。しかし、 Rubyのメソッド引数は値のみを取るため、そのままでは呼び出し先が設定した 値を参照できません。このような場合、ARGVを参照することで呼び出し先の設 定値を参照できます。
以下のリストは、VBで開発したオブジェクトのメソッド呼び出しを例としてい ます。このメソッド（Accm）は、第1引数で指定した演算を第2引数と第3引数に 適用し、結果を第2引数に設定します。
' VB (OLE Automation server)
Public Sub Accm(ByVal Operator, ByRef Accumulator, ByVal Operand)
If Operator = "*" Then
Accmulator = Accmulator * Operand
Else If Operator = "+" Then
Accmulator = Accmulator + Operand
End If
End Sub
# Ruby
x = 10
obj.Accm '*', x, 11
p x # => 10 …… 呼び出しによって影響を受けない
p WIN32OLE::ARGV # => ['*', 110, 11] …… 結果はARGVの対応する引数に反映される
obj.Accm '+', 10, 11
p WIN32OLE::ARGV # => ['+', 21, 11]
直前のメソッド呼び出しが例外となった場合、ARGVの設定内容は呼び出し前の 状態が保たれます。つまり、WIN32OLE自身がARGVの内容を消去するのは、メソッ ド呼び出しに成功した場合のみです。このため最後のメソッド呼び出しが引数 にオブジェクトを返すタイプのメソッドだった場合、GCにオブジェクトを回収 させるために、呼び出し側でARGVを消去してください。
' VB (OLE Automation server)
Public Sub GetInterface(ByRef obj)
Set Obj = New OleObject
End Sub
# Ruby
obj.GetInterface nil # 引数の数を合わせるためダミー引数を指定
WIN32OLE::ARGV.clear # 通常は、後続のメソッド呼び出しによって消去される
CP_ACP -> Fixnum[permalink][rdoc]Windows既定のANSIコードページ（0）を示します。
CP_MACCP -> Fixnum[permalink][rdoc]Macintoshコードページ（2）を示します。
CP_OEMCP -> Fixnum[permalink][rdoc]OEMコードページ（1）を示します。
CP_SYMBOL -> Fixnum[permalink][rdoc]文字コードの変換にシンボルを利用することを示します（42）。
CP_THREAD_ACP -> Fixnum[permalink][rdoc]現在実行中のスレッドの既定のコードページ（3）を示します。
Windowsのコードページはスレッド毎に異なる値を設定できます。
CP_UTF7 -> Fixnum[permalink][rdoc]文字コードの変換にUTF-7を利用することを示します（65000）。
CP_UTF8 -> Fixnum[permalink][rdoc]文字コードの変換にUTF-8を利用することを示します（65001）。
LOCALE_SYSTEM_DEFAULT -> Fixnum[permalink][rdoc]システム既定のロケールを示すLCID(0x0800)です。WIN32OLEがオートメーショ ンを利用する場合の既定値です。
LOCALE_USER_DEFAULT -> Fixnum[permalink][rdoc]ユーザ既定のロケールを示すLCID(0x0400)です。
VERSION -> String[permalink][rdoc]Major.Minor.Patch形式のWIN32OLEのバージョン番号を示す文字列です。