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

class WIN32OLE

クラスの継承リスト: WIN32OLE < Object < Kernel

要約

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

目次

特異メソッド

codepage codepage= connect const_load new ole_free ole_reference_count ole_show_help

インスタンスメソッド

[] []= _getproperty _invoke _setproperty each invoke method_missing ole_activex_initialize ole_free ole_func_methods ole_get_methods ole_method ole_method_help ole_methods ole_obj_help ole_type ole_put_methods setproperty

定数

ARGV CP_ACP CP_MACCP CP_OEMCP CP_SYMBOL CP_THREAD_ACP CP_UTF7 CP_UTF8 LOCALE_SYSTEM_DEFAULT LOCALE_USER_DEFAULT VERSION

特異メソッド

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を利用します。

[RETURN]

WIN32OLEがオートメーション呼び出しの文字列変換に利用するコード ページを返します。

WIN32OLE.codepage   # => 932 （日本語Windowsの既定値）

codepage=(cp) -> nil[permalink][rdoc]

WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを 設定します。

WIN32OLEは、OLEオートメーション呼び出しに利用する文字列のUnicode変換に ここで設定したコードページを利用します。通常、WIN32OLEはロード時の Encoding.default_internalまたはEncoding.default_externalから適切なコー ドページを判断し、それを利用します。したがって、当メソッドを呼び出す必 要があるのは、WIN32OLEをrequireしたスクリプトと異なるエンコーディングを 利用しているスクリプトや、異なるエンコーディングを利用しているファイル から読み込んだ文字列を利用してWIN32OLEを呼び出す場合です。

[PARAM] cp:

コードページを指定します。

WIN32OLE.codepage = WIN32OLE::CP_UTF8

connect(ole) -> WIN32OLE[permalink][rdoc]

現在実行中のOLEオートメーションサーバに接続します。

connectメソッドは、COMのモニカを利用して、現在実行中のOLEオートメーショ ンサーバを検索し、接続します。接続に成功した場合、該当サーバを操作可能 なWIN32OLEオブジェクトが返ります。

[PARAM] ole:

接続対象のサーバを示すPROGID、CLSIDまたはモニカ（別名）を指定します。

[RETURN]

ole引数で特定されるWIN32OLEオブジェクトを返します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

WIN32OLE.connect('Excel.Application') # => WIN32OLE object which represents running Excel.

PROGID

OLEオートメーションサーバを識別するための文字列。通常「ベンダー名.ア プリケーション名.インターフェイス名」の形式を取ります。レジストリの HKEY_CLASSES_ROOTの「.」で始まらないキーとして登録されます。

CLSID

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メソッドはこれらの定数を読み込み、指定したモジュールに組み込 むことで参照可能とします。

[PARAM] ole:

定数を読み込む対象のWIN32OLEオブジェクトまたはタイプライブラ リ名（文字列）を指定します。

[PARAM] mod:

定数を定義する対象のモジュールを指定します。省略時は WIN32OLEに組み込まれます。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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

new(server, host=nil) -> WIN32OLE[permalink][rdoc]

OLEオートメーションサーバを生成します。

引数で指定したCLSIDまたはPROGIDを持つOLEオートメーションサーバを生成し ます。生成に成功した場合、該当サーバを操作可能なWIN32OLEオブジェクトが 返ります。

CLSIDおよびPROGIDについてはWIN32OLE.connectを参照してください。

[PARAM] server:

OLEオートメーションサーバを示すPROGIDまたはCLSIDを文字列 で指定します。

[PARAM] host:

サーバを生成するホストのホスト名またはIPアドレスを文字列で 指定します。省略時は現在スクリプトを実行中のホストで生成し ます。

[RETURN]

hostで指定したホスト上のserver引数で指定したWIN32OLEオブジェク トを返します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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の内部処理に熟知していない場合は使用しないでくだ さい。

[PARAM] aWIN32OLE:

解放するWIN32OLEオブジェクト。

[RETURN]

Releaseの戻り値。COMの仕様上は現在のオブジェクトの参照カウント 値を示します。

ole_reference_count(aWIN32OLE) -> Integer[permalink][rdoc]

引数で指定したオブジェクトの現在の参照カウント値を返します。

このメソッドは主にWIN32OLEのデバッグおよびWIN32OLEを利用するミドルウェ アの実装のために用意されています。このため、メソッドの内部動作は不定で す。COMの仕様とWIN32OLEの内部処理に熟知していない場合は使用しないでくだ さい。

[PARAM] aWIN32OLE:

参照カウント値を求めるWIN32OLEオブジェクト。

[RETURN]

AddRef呼び出し後のReleaseの戻り値。COMの仕様上は現在のオブジェ クトの参照カウント値を示します。

ole_show_help(obj, helpcontext = nil) -> ()[permalink][rdoc]

WIN32OLEオブジェクトのヘルプファイルを表示します。

Windows標準のヘルプ表示コンポーネントのHHCtrl.OCXを利用して、オブジェク トに関連付けられたヘルプファイル（chmファイル）を表示します。

また、chmファイルのフルパス名を指定して表示させることも可能です。

[PARAM] obj:

WIN32OLE_TYPEオブジェクトまたはWIN32OLE_METHODオ ブジェクト。直接ヘルプファイルのフルパス名を指定することも可 能です。

[PARAM] helpcontext:

obj引数にWIN32OLE_TYPEオブジェクトまたは WIN32OLE_METHODオブジェクトを指定した場合は、こ れらのオブジェクトの設定値を利用するため指定不要です。 obj引数にヘルプファイルのフルパス名を設定した場合は 0を指定してください。

[EXCEPTION] RuntimeError:

オブジェクトが関連するヘルプファイルを持たない場合 (no helpfile of `オブジェクト名') や、ヘルプファイル がインストールされていない場合 (failed to open help file `ファイル名') に通知します。

excel = WIN32OLE.new('Excel.Application')
typeobj = excel.ole_obj_help
WIN32OLE.ole_show_help(typeobj) if typeobj.helpfile

インスタンスメソッド

self[name] -> object[permalink][rdoc]

self[name, param...] -> object

オブジェクトのプロパティを参照します。

注意： このメソッドはRuby-1.9以降で動作が変わります。Ruby-1.9ではプロパ ティ名をメソッド名としたメソッド呼び出し形式で記述してください。

[]の中にWIN32OLEオブジェクトのプロパティ名を指定することで、オブジェク トをHashのように扱ってプロパティ値を参照します。

パラメータ付きプロパティの場合は、プロパティ名に続けて引数を「,」で区切っ て列記します。

なお、OLEオートメーションの仕様により、プロパティ名の大文字、小文字は区 別されません。

[PARAM] name:

プロパティ名を文字列で指定します。

[PARAM] param:

プロパティが引数を取る場合に指定します。

[RETURN]

プロパティ値を返します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しま した。理由はメッセージのHRESULTを調べてくだ さい。

excel = WIN32OLE.new('Excel.Application')
visible = excel['visible'] #=> false

上記のコードは以下と同等です。

excel = WIN32OLE.new('Excel.Application')
visible = excel.visible  #=> false

self[name] = value[permalink][rdoc]

self[name, param...] = value

オブジェクトのプロパティを設定します。

注意： このメソッドはRuby-1.9以降で動作が変わります。Ruby-1.9では WIN32OLE#setpropertyを利用してください。

[]でプロパティ名を指定したプロパティに値を設定します。

パラメータ付きプロパティの場合は、プロパティ名に続けて引数を「,」で区切っ て列記します。

なお、OLEオートメーションの仕様により、プロパティ名の大文字、小文字は区 別されません。

[PARAM] name:

プロパティ名を文字列で指定します。

[PARAM] param:

プロパティが引数を取る場合に指定します。

[PARAM] value:

プロパティに設定する値を指定します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

OLEオートメーションのプロパティはRubyの属性と異なり、パラメータを取るこ とができます。

たとえばExcelのWorksheetオブジェクトのCellsプロパティは桁位置と行番号の 2つのパラメータを取ります。

これはVBでは次のように記述できます。

sheet.Cells(1, 1) = sheet.Cells(1, 2) ' セルB1の内容をセルA1へ

Rubyでは上記のコードの右辺をVBと同じく「sheet.Cells(1, 2)」のように記述 できますが、左辺の記述はできません。

そのため、次の例のように[]=メソッドを利用して、パラメータ付きプロパティ を設定します。

excel = WIN32OLE.new('Excel.Application')
excel.visible = true
sheet = excel.Workbooks.Add.Worksheets(1)
sheet['Cells', 1, 2] = 321
sheet['Cells', 1, 1] = sheet['Cells', 1, 2] #== sheet['Cells', 1, 1] = sheet.Cells(1, 2)

_getproperty(dispid, args, types) -> object[permalink][rdoc]

DISPIDとパラメータの型を指定してオブジェクトのプロパティを参照します。

アクセスするプロパティのインターフェイスを事前に知っている場合に、 DISPIDとパラメータの型を指定してプロパティを参照します。

[PARAM] dispid:

プロパティのDISPID（メソッドを一意に特定する数値）を指定 します。

[PARAM] args:

プロパティが引数を取る場合に配列で指定します。引数の順序は 最左端の引数のインデックスを0とします。引数が不要な場合は空 配列を指定します。

[PARAM] types:

プロパティが引数を取る場合に配列で引数の型を指定します。引 数の順序は最左端の引数のインデックスを0とします。型の指定 には、WIN32OLE::VARIANTの定数を利用します。引数が不 要な場合は空配列を指定します。

このメソッドはCOMアーリーバインディングを利用することで外部プロセスサー バとのラウンドトリップを減らして処理速度を向上させることを目的としたも のです。このため、DLLの形式で型情報（TypeLib）を提供しているサーバに対 してはあまり意味を持ちません。

[RETURN]

プロパティ値を返します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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）を提供しているサーバに対してはあ まり意味を持ちません。そのため、型の高精度な制御が不要な場合は、直接メ ソッド名を指定したメソッド呼び出しを行うことを、プログラムの可読性の点 から推奨します。

[PARAM] dispid:

メソッドのDISPID（メソッドを一意に特定する数値）を指定し ます。

[PARAM] args:

メソッドの引数を配列で指定します。引数の順序は最左端の引数 のインデックスを0とします。引数が不要な場合は空配列を指定し ます。

[PARAM] types:

メソッドの引数の型を配列で指定します。引数の順序は最左端の 引数のインデックスを0とします。型の指定には、 WIN32OLE::VARIANTの定数を利用します。引数が不要な場 合は空配列を指定します。

[RETURN]

メソッドの返り値。ただし返り値を持たないメソッドの場合はnil。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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）を提供しているサーバに対 してはあまり意味を持ちません。

[PARAM] dispid:

プロパティのDISPID（メソッドを一意に特定する数値）を指定 します。

[PARAM] args:

引数を配列で指定します。引数の順序は最左端の引数のインデッ クスを0とします。プロパティに対する設定値は最右端の要素です。

[PARAM] types:

プロパティの引数の型を配列で指定します。引数の順序は最左端 の引数のインデックスを0とします。型の指定には、 WIN32OLE::VARIANTの定数を利用します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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メソッドは、このようなオブジェクトの列挙メソッドを 呼び出して、アイテム毎のイテレーションを行います。

[PARAM] i:

コレクション内のアイテム

[EXCEPTION] WIN32OLERuntimeError:

selfが列挙インターフェイスをサポートしてい ない場合に通知します。

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オートメーションの仕様により、メソッド名の大文字、小文字は区別 されません。

[PARAM] name:

メソッド名を文字列で指定します。

[PARAM] args:

メソッドの引数を指定します。また、最後の引数にHashを 与えることで、名前付き引数を指定できます。この場合、キーに 文字列でパラメータ名、値に引数を指定します。

[RETURN]

メソッドの返り値。ただし返り値を持たないメソッドの場合はnil。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。 excel = WIN32OLE.new('Excel.Application') workbook = excel.workbooks.invoke('Open', 'FileName' => 'c:\\users\\public\\test.xml', 'ReadOnly' => true, 'Password' => 'secret') excel.invoke('Quit')

このリストは、以下の記述と同等です。

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オートメーションサーバのメソッド（プロパティ）呼 び出しと解釈します。

[PARAM] id:

メソッド名をシンボルで指定します。

[PARAM] args:

メソッドの引数を指定します。

[RETURN]

メソッドの返り値。ただし返り値を持たないメソッドの場合はnil。

[EXCEPTION] RuntimeError:

idが有効なシンボルではありません。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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コントロールは、上記の動作を前提に組まれているため、実行 に先だって永続化データの転送をデータの有無と関係なく要求します。この場 合、もし永続化データを初期化しないと、実行時モード状態へ遷移せず、後続 のメソッド呼び出しがすべてエラーとなります。

[EXCEPTION] WIN32OLERuntimeError:

オブジェクトが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の 配列として返します。

[RETURN]

WIN32OLE_METHODの配列。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

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の配列として返します。

[RETURN]

WIN32OLE_METHODの配列。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

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オートメーションの仕様により、メソッド名の大文字、小文字は区別されま せん。

[PARAM] method:

メソッド情報を取り出す対象のメソッド名を文字列で指定します。

[RETURN]

WIN32OLE_METHODオブジェクト。

[EXCEPTION] WIN32OLERuntimeError:

指定したメソッド名が未定義あるいは型情報ラ イブラリ(TypeLib)が提供されていない場合など に発生します。

excel = WIN32OLE.new('Excel.Application')
method = excel.ole_method_help('Quit')

ole_methods -> [WIN32OLE_METHOD][permalink][rdoc]

オブジェクトのメソッド情報をWIN32OLE_METHODの配列として返します。

ole_methodsメソッドは、OLEオートメーションサーバが提供するすべてのメソッ ドをWIN32OLE_METHODの配列として返します。

[RETURN]

WIN32OLE_METHODの配列。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

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 | nil

WIN32OLE_TYPEオブジェクトを返します。

WIN32OLE_TYPEオブジェクトは、WIN32OLEオブジェクトの文書情報と型情 報を保持するオブジェクトです。

[RETURN]

オブジェクトに関連するWIN32OLE_TYPEオブジェクトを返します。 オブジェクトがドキュメント情報を持たない場合はnilを返します。

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の配列として返し ます。

[RETURN]

WIN32OLE_METHODの配列。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
properties = excel.ole_put_methods

[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_func_methods, WIN32OLE#ole_get_methods

setproperty(name, val) -> ()[permalink][rdoc]

setproperty(name, args..., val) -> ()

オブジェクトのプロパティを設定します。

プロパティ名を指定してOLEオートメーションオブジェクトのプロパティ （Rubyの属性に相当）を設定します。

なお、OLEオートメーションの仕様により、プロパティ名の大文字、小文字は区 別されません。

[PARAM] name:

プロパティ名を文字列で指定します。

[PARAM] val:

プロパティに設定する値を指定します。

[PARAM] args:

集合的なプロパティに対する設定項目を特定するための引数を指 定します。

[EXCEPTION] WIN32OLERuntimeError:

オートメーションサーバの呼び出しに失敗しました。 理由はメッセージのHRESULTを調べてください。

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のバージョン番号を示す文字列です。