Win32OLE(0.3.0)リファレンス

いまだにRDに慣れてないので、変かも。

Win32OLEで助田さん(=Suketa)のサイトで触れられていない機能についての記述。

なんか、オブジェクトブラウザが作れそうなほど充実してるような。 ほとんどの追加機能は、タイプライブラリ内の情報取得メソッドだ。

使い方

require 'win32ole'

ロードは全部小文字(win32ole)。クラス名は全部大文字(WIN32OLE)。ライブラリ名はucc(Win32OLE)。とバラエティに富んでいるので注意が必要かも。

ole_free (クラスメソッド)

もし参照カウンタが0より大きければIUnknown::Release()を呼び出す。 非常に危険なメソッドなので、呼ばないほうが良いとartonは考える。 が、必要があるから実装されているのではある。

使い方

obj = WIN32OLE.new "Foo.Bar"
obj.foo
WIN32OLE.ole_free obj

ole_reference_count (クラスメソッド)

参照カウンタの現在の値を得る。 内部的にはIUnknown::AddRef()を呼び出し、すぐにIUnknown::Release()を呼び出しその 戻り値を返すという実装である。 現実問題としては、IUnknown::Release()に対して参照カウンタの現在値を返すのは必須で はないため、必ずしも正しい値が得られるという保証はない。

例えばActiveScriptRubyのラッパオブジェクトの実装は常に1を返すわけだが、内部で
オブジェクトのライフタイム管理をやってるから、それで良かったりする。

setproperty

引数付きプロパティの設定メソッド。 例えばVBであれば、

obj.item("ハッシュだな") = newValue

と書けるわけだが、Rubyの文法だとこういう書き方は出来ない。かと言って、メソッド呼び出し として書くこともできない(PROPERTYGETのほうを優先する)ので、

obj.setproperty('item', 'ハッシュだな', newValue)

といように使用する。

ole_methods

オブジェクトが持つメソッドを列挙する。引数は、メソッドに()を付加するか(2を指定する)、プロパティ設定に=を付加するか(1を指定する)またはそれらの全部を付加するか( 3を指定する。省略時のデフォルト)。ちなみに指定可能な定数は、WIN32OLE::APPEND_xxxx という名称で定義されている(下のほうに出てるよ)。

使い方

o = WIN32OLE.new('Microsoft.XMLDOM')
o.ole_methods.each do |name|
  p name
end
=>
"QueryInterface()"
"AddRef()"
"Release()"
"GetTypeInfoCount()"
...続く

ole_get_methods

ole_methodsのうち取得プロパティ([propget])のみを列挙する。

ole_put_methods

ole_methodsのうち設定プロパティ([propput])のみを列挙する。ole_methodsと異なり引数省略時のデフォルト は、=を付加しない。

ole_func_methods

ole_methodsのうち、メソッドのみを列挙する。ole_methodsと異なり引数省略時のデフォルト は、()を付加しない。

ole_method

次項ole_method_helpのエイリアス。

ole_method_help

ITypeInfoからメソッドの情報を取得してハッシュを返す。

o = WIN32OLE.new('Microsoft.XMLDOM')
p o.ole_method('loadXML')
=>
{dispid"=>63, "oVft"=>260, "cParams"=>1, 
 "helpstring"=>"load the document from a sring", 
 "name"=>"loadXML", "cParamsOpt"=>0, "cScodes"=>0,
 "params"=>[["BSTR","IN"]]
}

キーの意味は以下の通り。

dispid ディスパッチID(メンバーID)
helpstring メソッド属性値のヘルプ文字列
cParams 引数の数。
cParamsOpt オプション引数の数。-1の場合は、メソッドがvararg属性であることを示す。
oVft VTBLのオフセット(0の場合はDispinterface)
name もちろんメソッド名そのもの
params 各パラメータの属性を示す配列の配列。属性には、ポインタ、配列といった情報と
       向き(IN,OUT,INOUT)、型が示される。

詳細はOLEオートメーションのリファレンスを参照してくれ。FUNCDESC構造体だ。

ole_obj_help

これはタイプライブラリ自身の属性などのHashを返す。

o = WIN32OLE.new('Microsoft.XMLDOM')
p o.ole_obj_help
=>
{"wMinorVerNum"=>0, "typekind"=>4, "helpstring"=>"", 
 "name"=>"IXMLDOMDocument", "cFuncs"=>76, "cVars"=>0, "wMajorVerNum"=>0}

バージョン情報は場合によっては嬉しいかも知れない。ADOだよ。 cFuncsは該当オブジェクトのメソッド(プロパティ含む)の数。 これも詳細はOLEオートメーションのリファレンスを参照。こっちはTYPEATTR構造体だ。 (キーと値は適宜取捨選択されているから、対応表が必要か?)

_invoke

アーリーバインディングされたメソッド呼び出し専用メソッド

自分でディスパッチIDを調べて直接使用しても悪くは無いが、自動的にラッパクラスを生成するためにolegen.rbというスクリプトが提供されている。

使い方

x._invoke dispid, args, types

特殊なタイプ

MFCは腐っているのでVT_ARRAY | VT_UI1つまり、バイト配列をクラスウィザードから指定できない。そのため、KBなどでVARIANTにラップすることが推奨されている。その結果、型情報が有効とならないため、せっかくアーリーバインディングしても

x._invoke dispid, [[1,2,3]], [VT_VARIANT]

となって、おもしろくない(つまり、エラーとなる−−デフォルトの変換が行われてバリアント配列を渡すことになる−−つまり型エラーとなるからだ)。 このような場合、

x._invoke dispid, [[1,2,3]], [VT_ARRAY | VT_UI1]

と記述すると、Win32OLEはバイト配列を作成し、OLEAUTがバイト配列のバリアントとして呼び出しを行うため、正しく処理される。

VERSION

Win32OLEのバージョンを示す文字列を返す。

APPEND_NONE

この定数は、ole_methodsなどの引数に使用可能。メソッドの()付加などを抑制する。

obj.ole_methods(WIN32OLE::APPEND_NONE).each do |x|
 ...

APPEND_EQUAL

この定数は、ole_methodsなどの引数に使用可能。設定プロパティに=を付加する。

APPEND_BRACKET

この定数は、ole_methodsなどの引数に使用可能。メソッドに()を付加する。

だが、これは、APPEND_PARENTHESIS(長いのでEmacs風にAPPEND_PARENか? open-parenとか使うし)の間違いのような。最初、インデクサに[]を付けるフラグだと思ったぞ。

APPEND_ALL

APPEND_EQUAL | APPEND_BRACKET

ARGV

最後にオブジェクトのメソッド呼び出しに利用した引数の配列。 何に使うかというと、[in,out]VARIANT*な、要するに引数に対する参照渡し(嫌な訳語だ) に対する戻り値を取得するのに利用する。

例)IDLの記述が

[id(x), helpstring("第1引数と第2引数でなんかの計算をして結果を第1引数に戻す。
メソッドの戻り値はオーバーフローが発生したかどうかを示すブール値")]
HRESULT Calc([in,out]VARIANT* x, [in]long y, [out, retval]VARIANT_BOOL* OverFlow);

である場合に、

if obj.Calc(8, 19) == false
  puts "result=#{WIN32OLE::ARGV[0]}"
end

というように使用する。

WIN32OLE::VARIANT

このモジュールは、OLE Early Bindingに使用する定数用。 VT_I2などの、wtypes.hでVARENUMとして定義された定数を取り込んでいる。 意味的にはOLEオートメーション互換型だけでよいのだが、多少の救済のために、UI2,UI4なども取り込んでいる。

更新記録

2001-6-18:ole_put_methodsとole_func_methodsが入れ替わってたので修正-arton

2001-9-17:ole_method_helpの修正、VARIANTの追加-arton

2001-9-18:_invokeの追加-arton

2001-12-15:クラスメソッドの明示-arton

メモ

Win32OLE の制作過程

<URL:http://homepage1.nifty.com/markey/ruby/win32ole/>



The RWiki