libwin32-0.26 > 0.1502 との差分

Win32::OLE 0.1502 と 0.26 の差分

11
22=encoding euc-jp
33
4
45=head1 NAME
56
6=begin original
7Win32::OLE - OLEオートメーション拡張
78
8Win32::OLE - OLE Automation extensions
9
10=end original
11
12Win32::OLE - OLE オートメーション拡張
13
149=head1 SYNOPSIS
1510
1611 $ex = Win32::OLE->new('Excel.Application') or die "oops\n";
1712 $ex->Amethod("arg")->Bmethod->{'Property'} = "foo";
1813 $ex->Cmethod(undef,undef,$Arg3);
1914 $ex->Dmethod($RequiredArg1, {NamedArg1 => $Value1, NamedArg2 => $Value2});
2015
2116 $wd = Win32::OLE->GetObject("D:\\Data\\Message.doc");
2217 $xl = Win32::OLE->GetActiveObject("Excel.Application");
2318
2419=head1 DESCRIPTION
2520
26=begin original
21このモジュールはPerlからのOLEオートメーションへのインターフェースを提供します。
22OLEオートメーションはVisualBasicのようなスクリプトの能力を提供し、強力な拡張性とPerlスクリプトから数多くのWin32アプリケーションを制御する能力を提供します。
2723
28This module provides an interface to OLE Automation from Perl.
24Win32::OLEモジュールはIDispatchインターフェースを独占的に使用します。 カスタムOLEインターフェースにアクセスすることはできません。 OLEインベントとOCXは現在のところサポートされていません。
29OLE Automation brings VisualBasic like scripting capabilities and
30offers powerful extensibility and the ability to control many Win32
31applications from Perl scripts.
3225
33=end original
26実際には、これはもはや厳密には正しくありません。 このモジュールはOLEイベントをB<アルファ>レベルでサポートをしています。 これはあまりテストされていませんし、インタフェース仕様は将来変更される可能性があります。
3427
35このモジュールは Perl からの OLE オートメーションへのインターフェースを
36提供します。
37OLE オートメーションは VisualBasic のようなスクリプトの能力を提供し、
38強力な拡張性と Perl スクリプトから数多くの Win32 アプリケーションを
39制御する能力を提供します。
40
41=begin original
42
43The Win32::OLE module uses the IDispatch interface exclusively. It is
44not possible to access a custom OLE interface. OLE events and OCX's are
45currently not supported.
46
47=end original
48
49Win32::OLE モジュールはもっぱら IDispatch インターフェースを使用します。
50カスタム OLE インターフェースにアクセスすることはできません。
51OLE インベントと OCX には現在のところ対応していません。
52
53=begin original
54
55Actually, that's no longer strictly true. This module now contains
56B<ALPHA> level support for OLE events. This is largely untested and the
57specific interface might still change in the future.
58
59=end original
60
61実際には、これは厳密には正しくありません。
62このモジュールは OLE イベントに B<アルファ> レベルで対応しています。
63これはあまりテストされていませんし、インタフェース仕様は将来
64変更される可能性があります。
65
6628=head2 Methods
6729
68(メソッド)
69
7030=over 8
7131
7232=item Win32::OLE->new(PROGID[, DESTRUCTOR])
7333
74=begin original
34new() クラス・メソッドはOLEオートメーション・オブジェクトの新しいインスタンスを開始します。
35このオブジェクトのリファレンスか、もし作成が失敗すればundefを返します。
7536
76The new() class method starts a new instance of an OLE Automation object.
37PROGID 引数は必要なアプリケーションのI<OLEプログラムID>またはI<クラスID>でなければなりません。 オプションのDESTRUCTORにはDESTROYのようなメソッドを指定します。 これはCODEリファレンスまたはOLEメソッド名の入った文字列のどちらかにすることができます。 これはPerlプログラムが死ぬ(die)するときに、OLEアプリケーションをきれいに終らせるために使われます。
77It returns a reference to this object or C<undef> if the creation failed.
7838
79=end original
39DCOMを通じてリモート・サーバーにオブジェクトを作成するためには、PROGIDのところに配列リファレンスを使うことができます。 参照される配列にはマシン名とI<プログラムID>またはI<クラスID>が入らなければなりません。 例えば:
8040
81new() クラスメソッドは OLE オートメーションオブジェクトの新しい
82インスタンスを開始します。
83このオブジェクトのリファレンスか、もし作成が失敗すれば C<undef> を返します。
84
85=begin original
86
87The PROGID argument must be either the OLE I<program id> or the I<class id>
88of the required application. The optional DESTRUCTOR specifies a DESTROY-like
89method. This can be either a CODE reference or a string containing an OLE
90method name. It can be used to cleanly terminate OLE applications in case the
91Perl program dies.
92
93=end original
94
95PROGID 引数は必要なアプリケーションの OLE I<プログラム ID> または
96I<クラス ID> でなければなりません。
97オプションの DESTRUCTOR には DESTROY のようなメソッドを指定します。
98これは CODE リファレンスまたは OLE メソッド名の入った文字列のどちらかに
99することができます。
100これは Perl プログラムが die するときに、OLE アプリケーションを
101きれいに終らせるために使われます。
102
103=begin original
104
105To create an object via DCOM on a remote server you can use an array
106reference in place of PROGID. The referenced array must contain the
107machine name and the I<program id> or I<class id>. For example:
108
109=end original
110
111DCOM を通じてリモートサーバーにオブジェクトを作成するためには、PROGID の
112ところに配列リファレンスを使えます。
113参照される配列にはマシン名と I<プログラム ID> または I<クラス ID> が
114入らなければなりません。
115例えば:
116
11741 my $obj = Win32::OLE->new(['my.machine.com', 'Program.Id']);
11842
119=begin original
43PROGIDがI<プログラムID>であれば、Win32::OLEはローカルに対応するI<クラスID>を解決しようとします。 もしローカルにI<プログラムID>が登録されていなければ、リモート・レジストリが問い合わせられます。 これはローカルなプロセスがリモート・レジストリに読み込みアクセスをもっているときにのみ成功します。 もっとも安全な（そしても最も速い)方法は、C<クラスID>を直接指定することです。
12044
121If the PROGID is a I<program id> then Win32::OLE will try to resolve the
122corresponding I<class id> locally. If the I<program id> is not registered
123locally then the remote registry is queried. This will only succeed if
124the local process has read access to the remote registry. The safest
125(and fastest) method is to specify the C<class id> directly.
126
127=end original
128
129PROGID が I<プログラム ID> であれば、Win32::OLE はローカルに対応する
130I<クラス ID> を解決しようとします。
131もしローカルに I<プログラム ID> が登録されていなければ、リモートレジストリが
132問い合わせられます。
133これはローカルなプロセスがリモートレジストリに読み込みアクセスを
134もっているときにのみ成功します。
135もっとも安全な(そしても最も速い)方法は、C<クラス ID> を直接指定することです。
136
13745=item Win32::OLE->EnumAllObjects([CALLBACK])
13846
139=begin original
47このクラス・メソッドは現在存在するWin32::OLEオブジェクトの数を返します。 オプションで各オブジェクトへのCALLBACK関数を呼ぶこともできます:
14048
141This class method returns the number Win32::OLE objects currently in
142existance. It will call the optional CALLBACK function for each of
143these objects:
144
145=end original
146
147このクラスメソッドは現在存在する Win32::OLE オブジェクトの数を返します。
148オプションで各オブジェクトへの CALLBACK 関数を呼ぶこともできます:
149
15049 $Count = Win32::OLE->EnumAllObjects(sub {
15150 my $Object = shift;
15251 my $Class = Win32::OLE->QueryObjectType($Object);
15352 printf "# Object=%s Class=%s\n", $Object, $Class;
15453 });
15554
156=begin original
55EnumAllObjects() メソッドは主にデバッグのためのツールです。 これは例えば、すべての外部コメンクションが適切に破壊されているかをチェックするためにENDブロックに入れて使うことができます。
15756
158The EnumAllObjects() method is primarily a debugging tool. It can be
159used e.g. in an END block to check if all external connections have
160been properly destroyed.
161
162=end original
163
164EnumAllObjects() メソッドは主にデバッグのためのツールです。
165これは例えば、すべての外部コメンクションが適切に破壊されているかを
166チェックするために END ブロックに入れて使えます。
167
16857=item Win32::OLE->FreeUnusedLibraries()
16958
170=begin original
59FreeUnusedLibraries() クラス・メソッドは使われていないOLEリソースのすべてをアンロードします。 これらは破壊されたすべての存在しているオブジェクトのクラスのライブラリです。 オブジェクト・ライブラリのアンロードは、長時間とても多くのB<異なる>オブジェクトを繰り返し、インスタンス生成するプロセスを実行したときにだけ本当に重要です。
17160
172The FreeUnusedLibraries() class method unloads all unused OLE
61Visual Basicで実装されたオブジェクトはこの機能についてバグを持っているかもしれないことに注意してください; 実際に彼らのクリーンアップ・コードを実行するまではアンロード可能にすることを拒みます。 その時点でDLLをアンロードすることは典型的には、アクセス・バイオレーションを発生させます。 この問題の可能性はSpinMessageLoop() メソッドを呼び出し、2,3秒sleep()することにより減らすことができます。
173resources. These are the libraries of those classes of which all
174existing objects have been destroyed. The unloading of object
175libraries is really only important for long running processes that
176might instantiate a huge number of B<different> objects over time.
17762
178=end original
179
180FreeUnusedLibraries() クラスメソッドは全ての使われていない OLE リソースを
181アンロードします。
182これらは存在しているオブジェクトのすべてが破壊されたクラスのライブラリです。
183オブジェクトライブラリのアンロードは、長時間とても多くの B<異なる>
184オブジェクトを繰り返し、インスタンス生成するプロセスを実行したときにだけ
185本当に重要です。
186
187=begin original
188
189Be aware that objects implemented in Visual Basic have a buggy
190implementation of this functionality: They pretend to be unloadable
191while they are actually still running their cleanup code. Unloading
192the DLL at that moment typically produces an access violation. The
193probability for this problem can be reduced by calling the
194SpinMessageLoop() method and sleep()ing for a few seconds.
195
196=end original
197
198Visual Basic で実装されたオブジェクトはこの機能についてバグを
199持っているかもしれないことに注意してください。
200実際に彼らのクリーンアップコードを実行するまではアンロード可能に
201することを拒みます。
202その時点でDLLをアンロードすることは典型的には、アクセスバイオレーションを
203発生させます。
204この問題の可能性は SpinMessageLoop() メソッドを呼び出し、2, 3秒
205sleep() することにより減らすことができます。
206
20763=item Win32::OLE->GetActiveObject(CLASS[, DESTRUCTOR])
20864
209=begin original
65GetActiveObject() クラスメソッドは指定されたOLEオートメーション・サーバーの動いているインスタンスへのOLEリファレンスを返します。 もしサーバーが現在アクティブでなければ、C<undef>を返します。 そのクラス登録さえもしていなければ、croakします。 オプションのDESTRUCTORメソッドはメソッド名、あるいはコード・リファレンスをとります。 このオブジェクトへの最後のリファレンスが失われるときに実行されます。 一般的にあなたが起動したのではないアプリケーションを止めることは一般的にはC<無作法>だと考えられます。
21066
211The GetActiveObject() class method returns an OLE reference to a
212running instance of the specified OLE automation server. It returns
213C<undef> if the server is not currently active. It will croak if
214the class is not even registered. The optional DESTRUCTOR method takes
215either a method name or a code reference. It is executed when the last
216reference to this object goes away. It is generally considered C<impolite>
217to stop applications that you did not start yourself.
218
219=end original
220
221GetActiveObject() クラスメソッドは指定された OLE オートメーションサーバーの
222動いているインスタンスへの OLE リファレンスを返します。
223もしサーバーが現在アクティブでなければ、C<undef> を返します。
224そのクラス登録さえもしていなければ、croak します。
225オプションの DESTRUCTOR メソッドはメソッド名、あるいはコードリファレンスを
226とります。
227このオブジェクトへの最後のリファレンスが失われるときに実行されます。
228一般的にあなたが起動したのではないアプリケーションを止めることは
229一般的には無作法だと考えられます。
230
23167=item Win32::OLE->GetObject(MONIKER[, DESTRUCTOR])
23268
233=begin original
69GetObject() クラスメソッドは指定されたオブジェクトへのOLEリファレンスを返します。 そのオブジェクトはパス名で指定され、オプションで後ろにエクスクラメーション・マーク '!'によって区切られた追加の要素サブコンポーネントがつきます。 オプションのDESTRUCTOR引数はnew() やGetActiveObject()と同じ意味を持ちます。
23470
235The GetObject() class method returns an OLE reference to the specified
236object. The object is specified by a pathname optionally followed by
237additional item subcomponent separated by exclamation marks '!'. The
238optional DESTRUCTOR argument has the same semantics as the DESTRUCTOR in
239new() or GetActiveObject().
240
241=end original
242
243GetObject() クラスメソッドは指定されたオブジェクトへの OLE リファレンスを
244返します。
245そのオブジェクトはパス名で指定され、オプションで後ろに
246エクスクラメーションマーク '!'によって区切られた追加の要素
247サブコンポーネントがつきます。
248オプションの DESTRUCTOR 引数は new() や GetActiveObject() と
249同じ意味を持ちます。
250
25171=item Win32::OLE->Initialize([COINIT])
25272
253=begin original
73Initialize() クラス・メソッドはPerlスレッドのための代わりのアパートメント・モデルを指定するために使うことができます。 これは最初のOLEオブジェクトが作成されるB<前に>呼ばれなければなりません。 もしC<Win32::OLE::Const>モジュールが使われていれば、Initialize() メソッドの呼出しは最初のC<Win32::OLE::Const>モジュールのためのC<use>ステートメントの前のBEGINブロックでされなければなりません。
25474
255The Initialize() class method can be used to specify an alternative
75COINITへの正しい値は以下の通りです:
256apartment model for the Perl thread. It must be called B<before> the
257first OLE object is created. If the C<Win32::OLE::Const> module is
258used then the call to the Initialize() method must be made from a BEGIN
259block before the first C<use> statement for the C<Win32::OLE::Const>
260module.
26176
262=end original
77 Win32::OLE::COINIT_APARTMENTTHREADED - 単一スレッド
263
264Initialize() クラスメソッドは Perl スレッドのための代わりの
265アパートメントモデルを指定するために使えます。
266これは最初の OLE オブジェクトが作成される B<前> に呼ばれなければなりません。
267もし C<Win32::OLE::Const> モジュールが使われていれば、Initialize() メソッドの
268呼び出しは最初の C<Win32::OLE::Const> モジュールのための C<use>
269ステートメントの前の BEGIN ブロックでされなければなりません。
270
271=begin original
272
273Valid values for COINIT are:
274
275=end original
276
277COINTへの正しい値は以下の通りです:
278
279=begin original
280
281 Win32::OLE::COINIT_APARTMENTTHREADED - single threaded
282 Win32::OLE::COINIT_MULTITHREADED - the default
283 Win32::OLE::COINIT_OLEINITIALIZE - single threaded, additional OLE stuff
284
285=end original
286
287 Win32::OLE::COINIT_APARTMENTTHREADED - シングルスレッド
28878 Win32::OLE::COINIT_MULTITHREADED - デフォルト
289 Win32::OLE::COINIT_OLEINITIALIZE - シングルスレッド、追加の OLE 機能
79 Win32::OLE::COINIT_OLEINITIALIZE - 単一スレッド、追加のOLE機能
29080
291=begin original
81COINIT_OLEINITIALIZE はOLEオブジェクトが、通常のCOMサブシステムでは利用できない、追加のOLEコンパウンド・ドキュメント技術を使っているさいに、ときおり必要になります（例えばMAPIセッションはこれが必要なようです）。
82COINIT_OLEINITIALIZE と COINIT_APARTMENTTHREADED は隠れたトップ・レベル・ウィンドウとPerlプロセスのためのメッセージ・キューを作成します。 これは他のアプリケーションとの問題を発生させるかもしれません;というのもPerlは通常そのメッセージ・キューを処理しないからです。 つまりアプリケーション間で同期型通信（DDEイニシエーションのような）を使っているプログラムはPerlが他のOLEメソッド呼出し/プロパティ・アクセスをおこすか、終了するまで止まってしまうかもしれません。
83これは InstallShieldセットアップやシェル関連から発生する多くの事柄にあてはまります。 デフォルトのCOINIT_MULTITHREADEDモデルを使うことができないのであれば、C<Win32::OLE-E<gt>SpinMessageLoop> と C<Win32::OLE-E<gt>Uninitialize> メソッドを使ってみてください。
29284
293COINIT_OLEINITIALIZE is sometimes needed when an OLE object uses
294additional OLE compound document technologies not available from the
295normal COM subsystem (for example MAPI.Session seems to require it).
296Both COINIT_OLEINITIALIZE and COINIT_APARTMENTTHREADED create a hidden
297top level window and a message queue for the Perl process. This may
298create problems with other application, because Perl normally doesn't
299process its message queue. This means programs using synchronous
300communication between applications (such as DDE initiation), may hang
301until Perl makes another OLE method call/property access or terminates.
302This applies to InstallShield setups and many things started to shell
303associations. Please try to utilize the C<Win32::OLE-E<gt>SpinMessageLoop>
304and C<Win32::OLE-E<gt>Uninitialize> methods if you can not use the default
305COINIT_MULTITHREADED model.
306
307=end original
308
309COINIT_OLEINITIALIZE は OLE オブジェクトが、通常の COM サブシステムでは
310利用できない、追加の OLE コンパウンドドキュメント技術を使っているさいに、
311ときおり必要になります(例えば MAPI セッションはこれが必要なようです)。
312COINIT_OLEINITIALIZE と COINIT_APARTMENTTHREADED は隠れたトップレベル
313ウィンドウと Perl プロセスのためのメッセージキューを作成します。
314これは他のアプリケーションとの問題を発生させるかもしれません。
315というのも Perl は通常そのメッセージキューを処理しないからです。
316つまりアプリケーション間で同期型通信(DDE イニシエーションのような)を
317使っているプログラムは Perl が他の OLE メソッド呼び出し/プロパティアクセスを
318おこすか、終了するまで止まってしまうかもしれません。
319これは InstallShield セットアップやシェル関連から発生する多くの事柄に
320あてはまります。
321デフォルトの COINIT_MULTITHREADED モデルを使うことができないのであれば、
322C<Win32::OLE-E<gt>SpinMessageLoop> と C<Win32::OLE-E<gt>Uninitialize>
323メソッドをを使ってみてください。
324
32585=item OBJECT->Invoke(METHOD[, ARGS])
32686
327=begin original
87Invoke() オブジェクト・メソッドはOLEメソッドを呼び出す代替方法です。 これは通常C<$OBJECT->METHOD(@ARGS)>と同じです。 この関数は METHOD名にPerl変数名として正しくない文字（例えば外国の文字）が入っているときに使わなければなりません。 もしデフォルトのメソッドがライブラリで名前を与えられていなくても、そのオブジェクトのデフォルトのメソッドを呼び出すために使うことができます。 この場合には<undef>またはC<''>をメソッド名として使います。 OLEオブジェクト・ネイティブのInvoke()メソッドを（もしそのようなものがあったとして）呼び出すためには、以下のようにします:
32888
329The Invoke() object method is an alternate way to invoke OLE
330methods. It is normally equivalent to C<$OBJECT->METHOD(@ARGS)>. This
331function must be used if the METHOD name contains characters not valid
332in a Perl variable name (like foreign language characters). It can
333also be used to invoke the default method of an object even if the
334default method has not been given a name in the type library. In this
335case use <undef> or C<''> as the method name. To invoke an OLE objects
336native Invoke() method (if such a thing exists), please use:
337
338=end original
339
340Invoke() オブジェクトメソッドは OLE メソッドを呼び出す代替方法です。
341これは通常 C<$OBJECT-E<gt>METHOD(@ARGS)> と同じです。
342この関数は METHOD 名に Perl 変数名として正しくない文字 (例えば外国の文字) が
343入っているときに使わなければなりません。
344もしデフォルトのメソッドがライブラリで名前を与えられていなくても、その
345オブジェクトのデフォルトのメソッドを呼び出すために使えます。
346この場合には C<undef> または C<''> をメソッド名として使います。
347OLE オブジェクトネイティブの Invoke() メソッドを (もしそのようなものが
348あったとして) 呼び出すためには、以下のようにします:
349
35089 $Object->Invoke('Invoke', @Args);
35190
35291=item Win32::OLE->LastError()
35392
354=begin original
93LastError() クラス・メソッドは最後に記録されたOLEエラーを返します。 これはC<$!>変数のように２つの値を持ちます:数値コンテキストではそれはエラー番号を返し、文字列コンテキストではそれはエラーメッセージを返します。 エラー番号は符号付きのHRESULTの値です。 符号なしの16進定数を符号付きの HRESULTに変換するためには L<HRESULT(ERROR)>関数を使ってください。
35594
356The LastError() class method returns the last recorded OLE
95最後のOLEエラーは、後の正常なOLE呼出しによって自動的にリセットされます。 数値は明示的に呼び出すことによって設定することができます（それは文字列の値を捨てます）:
357error. This is a dual value like the C<$!> variable: in a numeric
358context it returns the error number and in a string context it returns
359the error message. The error number is a signed HRESULT value. Please
360use the L<HRESULT(ERROR)> function to convert an unsigned hexadecimal
361constant to a signed HRESULT.
36296
363=end original
364
365LastError() クラスメソッドは最後に記録された OLE エラーを返します。
366これは C<$!> 変数のように二つの値を持ちます: 数値コンテキストでは
367エラー番号を返し、文字列コンテキストではエラーメッセージを返します。
368エラー番号は符号付きの HRESULT の値です。
369符号なしの 16 進定数を符号付きの HRESULT に変換するためには
370L<HRESULT(ERROR)> 関数を使ってください。
371
372=begin original
373
374The last OLE error is automatically reset by a successful OLE
375call. The numeric value can also explicitly be set by a call (which will
376discard the string value):
377
378=end original
379
380最後の OLE エラーは、後の正常な OLE 呼び出しによって自動的にリセットされます。
381数値は明示的に呼び出すことによって設定することができます(それは文字列の値を
382捨てます):
383
38497 Win32::OLE->LastError(0);
38598
38699=item OBJECT->LetProperty(NAME,ARGS,VALUE)
387100
388=begin original
101Win32::OLEでは、ハッシュの書き方を使ったプロパティ設定はVisual BasicのC<Set>と同じです（I<参照渡し>による代入）:
389102
390In Win32::OLE property assignment using the hash syntax is equivalent
391to the Visual Basic C<Set> syntax (I<by reference> assignment):
392
393=end original
394
395Win32::OLE では、ハッシュの書き方を使ったプロパティ設定は Visual Basic の
396Set と同じです(I<リファレンスによる> 代入):
397
398103 $Object->{Property} = $OtherObject;
399104
400=begin original
105はこのVisual Basic ステートメントに対応します:
401106
402corresponds to this Visual Basic statement:
403
404=end original
405
406これは以下の Visual Basic ステートメントに対応します:
407
408107 Set Object.Property = OtherObject
409108
410=begin original
109以下のようなVisual Basic C<Let> ステートメントのI<値渡し>による扱いを得るには:
411110
412To get the I<by value> treatment of the Visual Basic C<Let> statement
413
414=end original
415
416Visual Basic の C<Let> ステートメントの I<値による> 扱いを得るには:
417
418111 Object.Property = OtherObject
419112
420=begin original
113PerlではLetProperty() オブジェクト・メソッドを使わなければなりません:
421114
422you have to use the LetProperty() object method in Perl:
423
424=end original
425
426Perl では LetProperty() オブジェクトメソッドを使う必要があります:
427
428115 $Object->LetProperty($Property, $OtherObject);
429116
430=begin original
431
432LetProperty() also supports optional arguments for the property assignment.
433See L<OBJECT->SetProperty(NAME,ARGS,VALUE)> for details.
434
435=end original
436
437117LetProperty() はプロパティ設定のためのオプションの引数もサポートしています。
438詳しくは L<OBJECT-E<gt>SetProperty(NAME,ARGS,VALUE)> を参照してください。
118詳しくはL<OBJECT->SetProperty(NAME,ARGS,VALUE)>を参照してください。
439119
440120=item Win32::OLE->MessageLoop()
441121
442=begin original
122MessageLoop() クラス・メソッドは標準のWindowsメッセージループを実行し、QuitMessageLoop() クラスメソッドが呼ばれるまで、メッセージを処理します。 これはOLEイベントを待つために使われます。
443123
444The MessageLoop() class method will run a standard Windows message
445loop, dispatching messages until the QuitMessageLoop() class method is
446called. It is used to wait for OLE events.
447
448=end original
449
450MessageLoop() クラスメソッドは標準の Windows メッセージループを実行し、
451QuitMessageLoop() クラスメソッドが呼ばれるまで、メッセージを処理します。
452これは OLE イベントを待つために使われます。
453
454124=item Win32::OLE->Option(OPTION)
455125
456=begin original
126Option() クラス・メソッドはL<Module Options>を検査し、変更するために使うことができます。 1つだけ引数を指定すると、そのオプションの値を取り出します:
457127
458The Option() class method can be used to inspect and modify
459L<Module Options>. The single argument form retrieves the value of
460an option:
461
462=end original
463
464Option() クラスメソッドは L<Module Options> を検査し、変更するために
465使えます。
466一つだけ引数を指定すると、そのオプションの値を取り出します:
467
468128 my $CP = Win32::OLE->Option('CP');
469129
470=begin original
130一回の呼出しで複数のオプションを同時に設定することもできます:
471131
472A single call can be used to set multiple options simultaneously:
473
474=end original
475
476一回の呼び出しで複数のオプションを同時に設定することもできます。
477
478132 Win32::OLE->Option(CP => CP_ACP, Warn => 3);
479133
480134=item Win32::OLE->QueryObjectType(OBJECT)
481135
482=begin original
136QueryObjectType() クラス・メソッドはタイプ・ライブラリ名とオブジェクト・クラス名のリストを返します。 スカラ・コンテキストではクラス名だけを返します。 タイプ情報が使えなければ、C<undef>を返します。
483137
484The QueryObjectType() class method returns a list of the type library
485name and the objects class name. In a scalar context it returns the
486class name only. It returns C<undef> when the type information is not
487available.
488
489=end original
490
491QueryObjectType() クラスメソッドはタイプライブラリ名と
492オブジェクトクラス名のリストを返します。
493スカラコンテキストではそれはクラス名だけを返します。
494タイプ情報が使えなければ、C<undef> を返します。
495
496138=item Win32::OLE->QuitMessageLoop()
497139
498=begin original
140QuitMessageLoop() クラス・メソッドは（ユーザー・レベルで）"Quit"メッセージを現在のスレッド・メッセージ・ループにポストします。 QuitMessageLoop() は典型的にはイベント・ハンドラから呼ばれます。 MessageLoop() クラス・メソッドは、この"Quit"メソッドを受け取ると、戻ります。
499141
500The QuitMessageLoop() class method posts a (user-level) "Quit" message
501to the current threads message loop. QuitMessageLoop() is typically
502called from an event handler. The MessageLoop() class method will
503return when it receives this "Quit" method.
504
505=end original
506
507QuitMessageLoop() クラスメソッドは(ユーザーレベルで) "Quit" メッセージを
508現在のスレッドメッセージループにポストします。
509QuitMessageLoop() は典型的にはイベントハンドラから呼ばれます。
510MessageLoop() クラスメソッドは、この "Quit" メソッドを受け取ると、戻ります。
511
512142=item OBJECT->SetProperty(NAME,ARGS,VALUE)
513143
514=begin original
144SetProperty() メソッドはハッシュの書き方をサポートしていないプロパティを引数の値に変更することができます。 以下のハッシュ形式は:
515145
516The SetProperty() method allows to modify properties with arguments,
517which is not supported by the hash syntax. The hash form
518
519=end original
520
521SetProperty() メソッドはハッシュの書き方をサポートしていないプロパティを
522引数の値に変更できます。
523ハッシュ形式は以下の通りです
524
525146 $Object->{Property} = $Value;
526147
527=begin original
148これは以下のものと同じです:
528149
529is equivalent to
530
531=end original
532
533これは以下のものと同じです
534
535150 $Object->SetProperty('Property', $Value);
536151
537=begin original
538
539Arguments must be specified between the property name and the new value:
540
541=end original
542
543152引数はプロパティ名と新しい値の間に指定されなければなりません:
544153
545154 $Object->SetProperty('Property', @Args, $Value);
546155
547=begin original
156新しい値はSetProperty()への最後の引数でなければならないので、この関数で"名前付き引数"の書き方を使うことはできません。
548157
549It is not possible to use "named argument" syntax with this function
158このメソッドはSetProperty()と呼ばれるネイティブなOLEオブジェクト・メソッドを隠してしまいます。
550because the new value must be the last argument to SetProperty().
159そのネイティブなメソッドはInvoke() メソッドを使って呼び出すことができます:
551160
552=end original
553
554新しい値は SetProperty() への最後の引数でなければならないので、この関数で
555「名前付き引数」の書き方を使うことはできません。
556
557=begin original
558
559This method hides any native OLE object method called SetProperty().
560The native method will still be available through the Invoke() method:
561
562=end original
563
564このメソッドは SetProperty() と呼ばれるネイティブな OLE オブジェクト
565メソッドを隠してしまいます。
566そのネイティブなメソッドは Invoke() メソッドを使って呼び出すことができます:
567
568161 $Object->Invoke('SetProperty', @Args);
569162
570163=item Win32::OLE->SpinMessageLoop
571164
572=begin original
165このクラス・メソッドはすべてのメッセージ・キューに保留されているメッセージを取り出し、対応するWindowsプロシ?ジャーに処理させます。 このメソッドはCOINIT_MULTITHREADEDモデルを使っていないときにだけ必要になります。
166すべてのOLEメソッド呼出しとプロパティ・アクセスは自動的にメッセージ・キューを処理します。
573167
574This class method retrieves all pending messages from the message queue
575and dispatches them to their respective window procedures. Calling this
576method is only necessary when not using the COINIT_MULTITHREADED model.
577All OLE method calls and property accesses automatically process the
578message queue.
579
580=end original
581
582このクラスメソッドはすべてのメッセージキューに保留されている
583メッセージを取り出し、対応する Windows プロシ−ジャーに処理させます。
584このメソッドは COINIT_MULTITHREADED モデルを使っていないときにだけ
585必要になります。
586すべての OLE メソッド呼び出しとプロパティアクセスは自動的に
587メッセージキューを処理します。
588
589168=item Win32::OLE->Uninitialize
590169
591=begin original
170Uninitialize() クラス・メソッドはOLEサブシステムを消去します。 これは単一スレッド分離のためのOLEによって作られた隠れたトップ・レベル・ウィンドウも破壊します。 これを呼び出した後には、すべてのOLEオブジェクトが無効になります!
171Uninitialize()でOLEを終了させた後、再びInitialize() クラス・メソッドを異なる分離モデルで呼び出すことは可能です。
592172
593The Uninitialize() class method uninitializes the OLE subsystem. It
594also destroys the hidden top level window created by OLE for single
595threaded apartments. All OLE objects will become invalid after this call!
596It is possible to call the Initialize() class method again with a different
597apartment model after shutting down OLE with Uninitialize().
598
599=end original
600
601Uninitialize() クラスメソッドは OLE サブシステムの反初期化をします。
602これはシングルスレッド分離のための OLE によって作られた隠れた
603トップレベルウィンドウを破壊もします。
604これを呼び出した後には、すべての OLE オブジェクトが不適切になります!
605Uninitialize() で OLE を終了させた後、再び Initialize() クラスメソッドを
606異なる分離モデルで呼び出すことは可能です。
607
608173=item Win32::OLE->WithEvents(OBJECT[, HANDLER[, INTERFACE]])
609174
610=begin original
175このクラス・メソッドはOBJECTによって指定されたイベントの発火を有効化および無効化できます。 HANDLERが指定されなければ、イベントは接続されません。 いくつかのオブジェクトではWin32::OLEは自動的に正しいイベント・インターフェースを判定できません。 その場合、 INTERFACE引数はOBJECTのCOCLASS名またはイベントDISPATCHインターフェースの名前のどちらかが入っていなければなりません。 Win32::OLEイベント・サポートの詳細な説明については下記のL<Events>セクションをお読みださい。
611176
612This class method enables and disables the firing of events by the
613specified OBJECT. If no HANDLER is specified, then events are
614disconnected. For some objects Win32::OLE is not able to
615automatically determine the correct event interface. In this case the
616INTERFACE argument must contain either the COCLASS name of the OBJECT
617or the name of the event DISPATCH interface. Please read the L<Events>
618section below for detailed explanation of the Win32::OLE event
619support.
620
621=end original
622
623このクラスメソッドは OBJECT によって指定されたイベントを発火させるのを
624可能にも不可能にもできます。
625HANDLER が指定されなければ、イベントは接続されません。
626いくつかのオブジェクトでは Win32::OLE は自動的に正しい
627イベントインターフェースを判定できません。
628その場合、INTERFACE 引数は OBJECT の COCLASS 名またはイベント
629DISPATCH インターフェースの名前のどちらかが入っていなければなりません。
630Win32::OLE イベントサポートの詳細な説明については下記の
631L</Events> セクションをお読みださい。
632
633177=back
634178
635=begin original
179PerlがWin32::OLEパッケージでメソッド名を見つけられなかった場合、それは自動的にOLEメソッドの名前として使われ、このメソッド呼出しはOLEサーバーによって処理されます。
636180
637Whenever Perl does not find a method name in the Win32::OLE package it
181このモジュールには１つの特別な方法が組み込まれています: もしメソッドまたはプロパティ名がOLEオブジェクトによって解決されなければ、オブジェクトのデフォルト・メソッドがそのメソッド名を第1引数として呼ばれます。 そこで
638is automatically used as the name of an OLE method and this method call
639is dispatched to the OLE server.
640182
641=end original
642
643Perl が Win32::OLE パッケージでメソッド名を見つけられなかった場合、それは
644自動的に OLE メソッドの名前として使われます。
645そしてこのメソッド呼び出しは OLE サーバーによって処理されます。
646
647=begin original
648
649There is one special hack built into the module: If a method or property
650name could not be resolved with the OLE object, then the default method
651of the object is called with the method name as its first parameter. So
652
653=end original
654
655このモジュールには一つの特別な方法が組み込まれています。
656もしメソッドまたはプロパティ名が OLE オブジェクトによって解決されなければ、
657オブジェクトのデフォルトメソッドがそのメソッド名を第1引数として呼ばれます。
658そこで
659
660183 my $Sheet = $Worksheets->Table1;
661
662=begin original
663
664or
665
666=end original
667
668184または
669
670185 my $Sheet = $Worksheets->{Table1};
671186
672=begin original
187は以下のように解決されます:
673188
674is resolved as
675
676=end original
677
678は以下のように解決されます
679
680189 my $Sheet = $Worksheet->Item('Table1');
681190
682=begin original
191$WorksheeetsオブジェクトがC<Table1>メソッドまたはプロパティを持っていない場合です。 この方法はタイプ・ライブラリではメソッドに名前をつけないコレクションのデフォルト・メソッドを呼び出すために導入されています。 "名無しの"デフォルト・メソッドを呼び出す推奨される方法は以下の通りです:
683192
684provided that the $Worksheets object doesnot have a C<Table1> method
685or property. This hack has been introduced to call the default method
686of collections which did not name the method in their type library. The
687recommended way to call the "unnamed" default method is:
688
689=end original
690
691$Worksheeets オブジェクトが C<Table1> メソッドまたはプロパティを
692持っていない場合です。
693この方法はタイプライブラリではメソッドに名前をつけないコレクションの
694デフォルトメソッドを呼び出すために導入されています。
695「名無しの」デフォルトメソッドを呼び出す推奨される方法は以下の通りです:
696
697193 my $Sheet = $Worksheets->Invoke('', 'Table1');
698194
699=begin original
195この特殊な方法はC<use strict 'subs'>の元では使えません。
700196
701This special hack is disabled under C<use strict 'subs';>.
702
703=end original
704
705この特殊な方法は C<use strict 'subs'> の元では使えません。
706
707197=head2 Object methods and properties
708198
709(オブジェクトメソッドとプロパティ)
199new() メソッドによって返されるオブジェクトは、特定のOLEクラスのためのドキュメントで説明されているのと同じ形式で、メソッドを呼び出したり、プロパティを取り出したりするのに使うことができます。 （例えばMicrosoft ExcelドキュメントはOLEアクセスのために公開されているプロパティやメソッドを持ったオブジェクト階層について説明しています。）
710200
711=begin original
201メソッド呼出しでのオプションのパラメータはC<undef>をプレースホルダとして使うことによって省略することができます。 オプションのパラメータの順序はOLEサーバー・アプリケーションの後のバージョンでは変更されてしまうかもしれないので、よりよい方法は名前付き引数を使うことです。 名前付きパラメータはハッシュへのリファレンスをメソッド呼出しのへの最後のパラメータとして指定することでできます。
712202
713The object returned by the new() method can be used to invoke
203プロパティはハッシュの書き方を使って取得、設定するすることができ、メソッドは通常のperlメソッド呼出しの書き方で呼び出すことができます。 C<keys>関数とC<each>関数はオブジェクトのプロパティを列挙するために使うことができます。
714methods or retrieve properties in the same fashion as described
204プロパティは常に書込可能そして、読込可能でさえあるわけではないことに注意してください（時には未定義である間は読み込んだときに例外を起こすこともあります）。
715in the documentation for the particular OLE class (eg. Microsoft
716Excel documentation describes the object hierarchy along with the
717properties and methods exposed for OLE access).
718205
719=end original
206もしメソッドやプロパティが埋め込まれたOLEオブジェクトを返すのであれば、メソッドとプロパティ・アクセスは以下の例にあるようにチェーンされます。
720207
721new() メソッドによって返されるオブジェクトは、特定の OLE クラスのための
722ドキュメントで説明されているのと同じ形式で、メソッドを呼び出したり、
723プロパティを取り出したりするのに使えます。
724(例えば Microsoft Excel ドキュメントは OLE アクセスのために公開されている
725プロパティやメソッドを持ったオブジェクト階層について説明しています)。
726
727=begin original
728
729Optional parameters on method calls can be omitted by using C<undef>
730as a placeholder. A better way is to use named arguments, as the
731order of optional parameters may change in later versions of the OLE
732server application. Named parameters can be specified in a reference
733to a hash as the last parameter to a method call.
734
735=end original
736
737メソッド呼び出しでのオプションのパラメータは C<undef> をプレースホルダとして
738使うことによって省略できます。
739オプションのパラメータの順序は OLE サーバーアプリケーションの後の
740バージョンでは変更されてしまうかもしれないので、よりよい方法は名前付き
741引数を使うことです。
742名前付きパラメータはハッシュへのリファレンスをメソッド呼び出しのへの
743最後のパラメータとして指定することでできます。
744
745=begin original
746
747Properties can be retrieved or set using hash syntax, while methods
748can be invoked with the usual perl method call syntax. The C<keys>
749and C<each> functions can be used to enumerate an object's properties.
750Beware that a property is not always writable or even readable (sometimes
751raising exceptions when read while being undefined).
752
753=end original
754
755プロパティはハッシュの書き方を使って取得、設定できます。
756メソッドは通常のperlメソッド呼び出しの書き方で呼び出すことができます。
757C<keys> と C<each> 関数はオブジェクトのプロパティを列挙するために
758使えます。
759プロパティは常に書込可能そして、読込可能でさえあるわけではないことに
760注意してください
761(時には未定義である間は読み込んだときに例外を起こすこともあります)。
762
763=begin original
764
765If a method or property returns an embedded OLE object, method
766and property access can be chained as shown in the examples below.
767
768=end original
769
770もしメソッドやプロパティが埋め込まれた OLE オブジェクトを返すのであれば、
771メソッドとプロパティアクセスは以下の例にあるようにチェーンされます。
772
773208=head2 Functions
774209
775(関数)
776
777=begin original
778
779The following functions are not exported by default.
780
781=end original
782
783210以下の関数はデフォルトではエクスポートされません。
784211
785212=over 8
786213
787214=item HRESULT(ERROR)
788215
789=begin original
216HRESULT() 関数は符号なしの数値を符号付きのOLEによって内部的に使われるようなHRESULTエラー値に変換します。 これはPerlが全ての16進数定数を符号なしとして扱うために必要です。 最後のOLE関数が"Member not found'' (0x80020003)"を返したかどうかをチェックしたい場合は、以下のようにすることができます:
790217
791The HRESULT() function converts an unsigned number into a signed HRESULT
792error value as used by OLE internally. This is necessary because Perl
793treats all hexadecimal constants as unsigned. To check if the last OLE
794function returned "Member not found" (0x80020003) you can write:
795
796=end original
797
798HRESULT() 関数は符号なしの数値を符号付きの OLE によって内部的に使われるような
799HRESULT エラー値に変換します。
800これは Perl が全ての 16 進数定数を符号なしとして扱うために必要です。
801最後の OLE 関数が "Member not found" (0x80020003) を返したかどうかを
802チェックしたければ、以下のようにすることができます:
803
804218 if (Win32::OLE->LastError == HRESULT(0x80020003)) {
805 # your error recovery here
219 # ここにエラー処理を書く
806220 }
807221
808222=item in(COLLECTION)
809223
810=begin original
224もしCOLLECTION がOLEコレクンション・オブジェクトであれば、C<in $COLLECTION> は、そのコレクションのすべての要素のリストを返します。 これはC<Win32::OLE::Enum->All($COLLECTION)>のショートカットです。 これは一般的にC<foreach>ループで使われます:
811225
812If COLLECTION is an OLE collection object then C<in $COLLECTION>
813returns a list of all members of the collection. This is a shortcut
814for C<Win32::OLE::Enum->All($COLLECTION)>. It is most commonly used in
815a C<foreach> loop:
816
817=end original
818
819もし COLLECTION が OLE コレクンションオブジェクトであれば、
820C<in $COLLECTION> は、そのコレクションのすべての要素のリストを返します。
821これは C<Win32::OLE::Enum-E<gt>All($COLLECTION)> のショートカットです。
822これは一般的に C<foreach> ループで使われます:
823
824226 foreach my $value (in $collection) {
825 # do something with $value here
227 # $valueを使って何かする
826228 }
827229
828230=item valof(OBJECT)
829231
830=begin original
232Perl OLE の通常の代入は、単にその OLE オブジェクトへの新しいリファレンスを作ります。 valof() 関数は明示的にオブジェクト（デフォルト・メソッドを通じた）とオブジェトの値を区別します。
831233
832Normal assignment of Perl OLE objects creates just another reference
833to the OLE object. The valof() function explictly dereferences the
834object (through the default method) and returns the value of the object.
835
836=end original
837
838Perl OLE オブジェクトの通常の代入は他の OLE オブジェクトへの他の
839リファレンスを作成します。
840valof() 関数は明示的にオブジェクト(デフォルトメソッドを通じた)と
841オブジェクトの値を区別します。
842
843234 my $RefOf = $Object;
844235 my $ValOf = valof $Object;
845236 $Object->{Value} = $NewValue;
846237
847=begin original
238ここで$ValOfはまだ古い値を持っているのに、$RefOf はまだ$Objectへのリファレンスなので、$NewValue を解決します。
848239
849Now $ValOf still contains the old value wheras $RefOf would
240valof() 関数はWin32::OLE::VariantオブジェクトをPerl変数に変換するためにも使うことができます。
850resolve to the $NewValue because it is still a reference to
851$Object.
852241
853=end original
854
855いまや $ValOf はまだ古い値を持っているのに、$RefOf はまだ $Object への
856リファレンスなので、$NewValue を解決します。
857
858=begin original
859
860The valof() function can also be used to convert Win32::OLE::Variant
861objects to Perl values.
862
863=end original
864
865valof() 関数は Win32::OLE::Variant オブジェクトを Perl 変数に
866変換するためにも使えます。
867
868242=item with(OBJECT, PROPERTYNAME => VALUE, ...)
869243
870=begin original
244この関数はあるオブジェクトの複数のプロパティを設定するための簡単な方法を提供します。 これは後ろについている各組合わせに対してC<$OBJECT->{PROPERTYNAME} = $VALUE> を繰り返しおこないます。
871245
872This function provides a concise way to set the values of multiple
873properties of an object. It iterates over its arguments doing
874C<$OBJECT->{PROPERTYNAME} = $VALUE> on each trailing pair.
875
876=end original
877
878この関数はあるオブジェクトの複数のプロパティを設定するための簡単な方法を
879提供します。
880これは後ろについている各組合わせに対して
881C<$OBJECT-E<gt>{PROPERTYNAME} = $VALUE> を繰り返しおこないます。
882
883246=back
884247
885248=head2 Overloading
886249
887(オーバーロード)
250Win32::OLEオブジェクトはブール値、数値、文字列コンテキストで使われたときにはいつでも、自動的にそれらの値に変換するためにオーバーロードすることができます。 これはデフォルトでは有効ではありません。 OVERLOAD疑似エクスポートを通して要求する必要があります:
888251
889=begin original
890
891The Win32::OLE objects can be overloaded to automatically convert to
892their values whenever they are used in a bool, numeric or string
893context. This is not enabled by default. You have to request it
894through the OVERLOAD pseudoexport:
895
896=end original
897
898Win32::OLE オブジェクトはブール値、数値、文字列コンテキストで
899使われたときにはいつでも、自動的にそれらの値に変換するために
900オーバーロードできます。
901これはデフォルトでは可能ではありません。
902OVERLOAD 疑似エクスポートを通して要求する必要があります:
903
904252 use Win32::OLE qw(in valof with OVERLOAD);
905253
906=begin original
254例えばデバッグのためにC<overload::StrVal()>メソッドを使って、元のオブジェクト(C<Win32::OLE=0xDEADBEEF>) の文字列表現を取得することもできます:
907255
908You can still get the original string representation of an object
909(C<Win32::OLE=0xDEADBEEF>), e.g. for debugging, by using the
910C<overload::StrVal()> method:
911
912=end original
913
914例えばデバッグのために C<overload::StrVal()> メソッドを使って、元の
915オブジェクトの文字列表現 (C<Win32::OLE=0xDEADBEEF>) を取得することもできます:
916
917256 print overload::StrVal($object), "\n";
918257
919=begin original
258C<OVERLOAD>はグローバルな設定であることに注意してください。 もしなんらかのモジュールがWin32::OLEオーバーロードを可能にすると、それはどこでも有効です。
920259
921Please note that C<OVERLOAD> is a global setting. If any module enables
922Win32::OLE overloading then it's active everywhere.
923
924=end original
925
926C<OVERLOAD> はグローバルな設定であることに注意してください。
927もしなんらかのモジュールが Win32::OLE オーバーロードを可能にすると、
928それはいつでも有効です。
929
930260=head2 Events
931261
932(イベント)
262Win32::OLEモジュールは今はB<アルファ>レベルのイベント・サポートを持っています。 このサポートはPerlが単一スレッド分離レベルで実行しているときにだけ利用できます。 これはC<EVENTS>疑似インポートを使うことによって、とても簡単に保証することができます:
933263
934=begin original
935
936The Win32::OLE module now contains B<ALPHA> level event support. This
937support is only available when Perl is running in a single threaded
938apartment. This can most easily be assured by using the C<EVENTS>
939pseudo-import:
940
941=end original
942
943Win32::OLE モジュールは今は B<アルファ> レベルのイベントサポートを
944持っています。
945このサポートは Perl がシングルスレッド分離レベルで実行しているときにだけ
946利用できます。
947これはとても簡単に C<EVENTS> 疑似インポートを使うことによって、
948保証することができます:
949
950264 use Win32::OLE qw(EVENTS);
951265
952=begin original
953
954which implicitly does something like:
955
956=end original
957
958266これは暗黙のうちに以下のようなことをしています:
959267
960268 use Win32::OLE;
961269 Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE);
962270
963=begin original
271現在のOLEイベントへのインターフェースは実験的なものであると考えられ、変更されやすいものです。 通常のOLEアプリケーションでは予定通りに機能しますが、OLE制御イベントはまだうまく機能していないようです。
964272
965The current interface to OLE events should be considered experimental
273イベントはWin32::OLE->WithEvents() クラス・メソッドを通して、OLEオブジェクトのために明示的に可能にされなければなりません。 Win32::OLEモジュールはオブジェクトのデフォルト・イベント・ソースを判定するために IProvideClassInfo2 インターフェースを利用しています。 このインターフェースがサポートされていなければ、ユーザは WithEvents()メソッドで明示的にイベント・ソースの名前を指定しなければなりません。 オブジェクトのクラス名を3番目のパラメータとして指定することも可能です。 この場合、Win32::OLEは、このCOCLASSのためのデフォルト・ソース・インターフェースを見つけようとします。
966and is subject to change. It works as expected for normal OLE
967applications, but OLE control events often don't seem to work yet.
968274
969=end original
275Win32::OLE->WithEvents() へのHANDLER引数はCODEリファレンスまたはパッケージ名のどちらかにすることができます。 前者の場合、すべてのイベントはこの特定の関数を呼び出します。 この関数への最初の 2 つの引数はOBJECTそのものとイベントの名前になります。 残りの引数はイベントによります:
970276
971現在の OLE イベントへのインターフェースは実験的なものであると考えられ、
972変更されやすいものです。
973通常の OLE アプリケーションでは予定通りに機能しますが、OLE 制御イベントは
974まだうまく機能していないようです。
975
976=begin original
977
978Events must be enabled explicitly for an OLE object through the
979Win32::OLE->WithEvents() class method. The Win32::OLE module uses the
980IProvideClassInfo2 interface to determine the default event source of
981the object. If this interface is not supported, then the user must
982specify the name of the event source explicitly in the WithEvents()
983method call. It is also possible to specify the class name of the
984object as the third parameter. In this case Win32::OLE will try to
985look up the default source interface for this COCLASS.
986
987=end original
988
989イベントは Win32::OLE->WithEvents() クラスメソッドを通して、
990OLE オブジェクトのために明示的に可能にされなければなりません。
991Win32::OLE モジュールはオブジェクトのデフォルトイベントソースを
992判定するために IProvideClassInfo2 インターフェースを利用しています。
993このインターフェースがサポートされていなければ、ユーザは
994WithEvents() メソッドで明示的にイベントソースの名前を
995指定しなければなりません。
996オブジェクトのクラス名を 3 番目のパラメータとして指定することも可能です。
997この場合、Win32::OLE は、この COCLASS のための
998デフォルトソースインターフェースを見つけようとします。
999
1000=begin original
1001
1002The HANDLER argument to Win32::OLE->WithEvents() can either be a CODE
1003reference or a package name. In the first case, all events will invoke
1004this particular function. The first two arguments to this function will
1005be the OBJECT itself and the name of the event. The remaining arguments
1006will be event specific.
1007
1008=end original
1009
1010Win32::OLE->WithEvents() への HANDLER 引数は CODE リファレンスまたは
1011パッケージ名のどちらかにすることができます。
1012前者の場合、すべてのイベントはこの特定の関数を呼び出します。
1013この関数への最初の二つの引数は OBJECT そのものとイベントの名前になります。
1014残りの引数はイベントによります:
1015
1016277 sub Event {
1017278 my ($Obj,$Event,@Args) = @_;
1018279 print "Event triggered: '$Event'\n";
1019280 }
1020281 Win32::OLE->WithEvents($Obj, \&Event);
1021282
1022=begin original
283またはHANDLER引数でパッケージ名を指定することができます。 OBJECTがイベントを発火したとき、Win32::OLEは、このパッケージでイベントと同じ名前の関数を見つけようとします。 この関数はOBJECTを最初の引数とし、イベント特有のパラメータが後ろについて呼び出されます:
1023284
1024Alternatively the HANDLER argument can specify a package name. When the
1025OBJECT fires an event, Win32::OLE will try to find a function of the same
1026name as the event in this package. This function will be called with the
1027OBJECT as the first argument followed again by the event specific parameters:
1028
1029=end original
1030
1031代わりに HANDLER 引数がパッケージ名を指定できます。
1032OBJECT がイベントを発火したとき、Win32::OLE は、このパッケージでイベントと
1033同じ名前の関数を見つけようとします。
1034この関数は OBJECT を最初の引数とし、イベント特有のパラメータが後ろについて
1035呼び出されます:
1036
1037285 package MyEvents;
1038286 sub EventName1 {
1039287 my ($Obj,@Args) = @_;
1040288 print "EventName1 event triggered\n";
1041289 }
1042290
1043291 package main;
1044292 Win32::OLE->WithEvents($Obj, 'MyEvents', 'IEventInterface');
1045293
1046=begin original
294Win32::OLEがイベント名の関数を見つけなければ、何も起こりません。
1047295
1048If Win32::OLE doesn't find a function with the name of the event then nothing
296I<参照渡しで>渡されたイベント・パラメータは特別に扱われます。 これらは対応するPerlデータ型に変換されず、 Win32::OLE::Variantオブジェクトとして渡されます。 これらのオブジェクトにPut()メソッドの助けを借りて新しい値を代入することができます。 この値はイベント関数が戻るとき、オブジェクトに戻されます:
1049happens.
1050297
1051=end original
1052
1053Win32::OLE がイベント名の関数を見つけなければ、何も起こりません。
1054
1055
1056=begin original
1057
1058Event parameters passed I<by reference> are handled specially. They are not
1059converted to the corresponding Perl datatype but passed as Win32::OLE::Variant
1060objects. You can assign a new value to these objects with the help of the
1061Put() method. This value will be passed back to the object when the event
1062function returns:
1063
1064=end original
1065
1066I<リファレンスによって> 渡されたイベントパラメータは特別に扱われます。
1067これらは対応する Perl データ型に変換されず、
1068Win32::OLE::Variant オブジェクトとして渡されます。
1069これらのオブジェクトに Put() メソッドの助けを借りて新しい値を
1070代入できます。
1071この値はイベント関数が戻るとき、オブジェクトに戻されます:
1072
1073298 package MyEvents;
1074299 sub BeforeClose {
1075300 my ($self,$Cancel) = @_;
1076301 $Cancel->Put(1) unless $MayClose;
1077302 }
1078303
1079=begin original
304$Cancelへの直接の代入は元の値に何も影響を与えないので、オブジェクトにアクションを閉じるのを中止させるように命令しません。
1080305
1081Direct assignment to $Cancel would have no effect on the original value and
1082would therefore not command the object to abort the closing action.
1083
1084=end original
1085
1086$Cancel への直接の代入は元の値に何も影響を与えません。
1087そしてこのためオブジェクトにアクションを閉じるのを中止させるように命令しません。
1088
1089306=head2 Module Options
1090307
1091(モジュールオプション)
308以下のモジュール・オプションはC<Win32::OLE->Option>クラスメソッドでアクセス、変更することができます。 Win32::OLEモジュールの始めのころのバージョンでは、これらのオプションはクラス変数として直接操作されました。 この方法は現在では非推奨です。
1092309
1093=begin original
1094
1095The following module options can be accessed and modified with the
1096C<Win32::OLE->Option> class method. In earlier versions of the Win32::OLE
1097module these options were manipulated directly as class variables. This
1098practice is now deprecated.
1099
1100=end original
1101
1102以下のモジュールオプションは C<Win32::OLE-E<gt>Option> クラスメソッドで
1103アクセス、変更できます。
1104Win32::OLE モジュールの始めのころのバージョンでは、これらのオプションは
1105クラス変数として直接操作されました。
1106この実装は今では廃止予定です:
1107
1108310=over 8
1109311
1110312=item CP
1111313
1112=begin original
314この変数はPerl文字列とOLEインターフェースによって使われるUnicode文字列の間のすべての変換によって使われるコードページの決定に使われます。 デフォルトの値はCP_ACPで、これはデフォルトのANSIコードページです。 他に可能な値は、CP_OEMCP, CP_MACCP, CP_UTF7, CP_UTF8です。 これらの定数はデフォルトではエクスポートされません。
1113315
1114This variable is used to determine the codepage used by all
1115translations between Perl strings and Unicode strings used by the OLE
1116interface. The default value is CP_ACP, which is the default ANSI
1117codepage. Other possible values are CP_OEMCP, CP_MACCP, CP_UTF7 and
1118CP_UTF8. These constants are not exported by default.
1119
1120=end original
1121
1122この変数は Perl 文字列と OLE インターフェースによって使われる Unicode 文字列の
1123間のすべての変換によって使われるコードページです。
1124デフォルトの値は CP_ACP です。
1125これはデフォルトの ANSI コードページです。
1126他に可能な値は、CP_OEMCP, CP_MACCP, CP_UTF7, CP_UTF8 です。
1127これらの定数はデフォルトではエクスポートされません。
1128
1129316=item LCID
1130317
1131=begin original
318この変数は全てのOLE呼出しに使われるロケール識別子を制御します。
319これはデフォルトではLOCALE_NEUTRALに設定されます。 他のロケール関連情報についてはL<Win32::OLE::NLS> モジュールをチェックしてください。
1132320
1133This variable controls the locale idnetifier used for all OLE calls.
321=item Variant
1134It is set to LOCALE_NEUTRAL by default. Please check the
1135L<Win32::OLE::NLS> module for other locale related information.
1136322
1137=end original
323このオプションは、メソッド呼び出しやプロパティアクセサが VT_CY 型と VT_DECIMAL 型を返すときにどのように返すかを制御します。 デフォルトでは VT_CY 型は文字列に変換され、 VT_DECIMAL 型は浮動小数点数に変換されます。 C<Variant> オプションが有効の場合、
324これらの値は VT_DATE 型や VT_ERROR と同様に Win32::OLE::Variant 型で返されます。 Win32::OLE::Variant モジュールも読み込まれている場合、文字列と数値のコンテキストでは全ての値は以前と同じ振る舞いをするはずです。
1138325
1139この変数は全ての OLE 呼び出しに使われるロケール識別子を制御します。
326C<Variant> の振る舞いがデフォルトになっていない唯一の理由は、すでにあるプログラムを壊す可能性のある互換性の無い変更だからです。
1140それはデフォルトでは LOCALE_NEUTRAL に設定されます。
1141他のロケール関連情報については L<Win32::OLE::NLS> モジュールを
1142チェックしてください。
1143327
1144328=item Warn
1145329
1146=begin original
330この変数はエラーが発生したときのWin32::OLEモジュールの動きを決定します。 有効な値は以下の通りです:
1147331
1148This variable determines the behavior of the Win32::OLE module when
332 0 エラーを無視; undefを返す
1149an error happens. Valid values are:
333 1 $^Wが設定されていれば(-w オプション）Carp::carp
334 2 常にCarp::carp
335 3 Carp::croak
1150336
1151=end original
337（Carp行/モジュール情報を無し）エラー番号とメッセージはC<Win32::OLE->LastError> クラス・メソッドを通して利用することができます。
1152338
1153この変数はエラーが発生したときの Win32::OLE モジュールの動きを決定します。
339またはWarnオプションにCODEリファレンスを設定することもできます。 例えば:
1154適切な値は以下の通りです:
1155340
1156=begin original
1157
1158 0 Ignore error, return undef
1159 1 Carp::carp if $^W is set (-w option)
1160 2 always Carp::carp
1161 3 Carp::croak
1162
1163=end original
1164
1165 0 エラーを無視して undef を返す
1166 1 $^W が設定されていれば(-w オプション)Carp::carp
1167 2 常に Carp::carp
1168 3 Carp::croak
1169
1170=begin original
1171
1172The error number and message (without Carp line/module info) are
1173available through the C<Win32::OLE->LastError> class method.
1174
1175=end original
1176
1177エラー番号とメッセージ(Carp 行/モジュール情報は無し)は
1178C<Win32::OLE->LastError> クラスメソッドを通して利用できます。
1179
1180=begin original
1181
1182Alternatively the Warn option can be set to a CODE reference. E.g.
1183
1184=end original
1185
1186代わりに CODE リファレンスに Warn オプションを設定できます。
1187例えば
1188
1189341 Win32::OLE->Option(Warn => 3);
1190342
1191=begin original
343これは以下のものと同じです:
1192344
1193is equivalent to
1194
1195=end original
1196
1197これは以下のものと同じです。
1198
1199345 Win32::OLE->Option(Warn => \&Carp::croak);
1200346
1201=begin original
347これはVisualBasicのC<On Error Goto Label>構造をエミュレートするために使うことさえもできます:
1202348
1203This can even be used to emulate the VisualBasic C<On Error Goto
1204Label> construct:
1205
1206=end original
1207
1208これは VisualBasic の C<On Error Goto Label> 構造をエミュレートするために
1209使うことさえもできます:
1210
1211349 Win32::OLE->Option(Warn => sub {goto CheckError});
1212 # ... your normal OLE code here ...
350 # ここに通常のOLEコードを書く
1213351
1214352 CheckError:
1215 # ... your error handling code here ...
353 # ここにエラー処理コードを書く
1216354
1217355=item _NewEnum
1218356
1219=begin original
357このオプションはコレクション・オブジェクトのための追加の列挙子のサポートを可能にします。 C<_NewEnum>オプションが設定されたとき、すべてのコレクションは1つの追加のプロパティである C<_NewEnum>を受け取ります。 このプロパティの値はコレクションのすべての要素が入った配列へのリファレンスになります。 このオプションはC<Data::Dumper>やオブジェクト・ツリー・ブラウザのような自動的なツリー構造横断プログラムと一緒に使うときに便利でしょう。 このオプションの値は1（有効）または0（無効、デフォルト）でなければなりません。
1220358
1221This option enables additional enumeration support for collection
1222objects. When the C<_NewEnum> option is set, all collections will
1223receive one additional property: C<_NewEnum>. The value of this
1224property will be a reference to an array containing all the elements
1225of the collection. This option can be useful when used in conjunction
1226with an automatic tree traversal program, like C<Data::Dumper> or an
1227object tree browser. The value of this option should be either 1
1228(enabled) or 0 (disabled, default).
1229
1230=end original
1231
1232このオプションはコレクションオブジェクトのための追加の列挙子のサポートを
1233可能にします。
1234_C<NewEnum> オプションが設定されたとき、すべてのコレクションは一つの
1235追加のプロパティ: C<_NewEnum> を受け取ります。
1236このプロパティの値はコレクションのすべての要素が入った配列への
1237リファレンスになります。
1238このオプションは C<Data::Dumper> やオブジェクトツリーブラウザのような
1239自動的なツリー構造横断プログラムと一緒に使うときに便利でしょう。
1240このオプションの値は1(有効)または0(無効、デフォルト)でなければなりません。
1241
1242359 Win32::OLE->Option(_NewEnum => 1);
1243360 # ...
1244361 my @sheets = @{$Excel->Worksheets->{_NewEnum}};
1245362
1246=begin original
363通常のアプリケーション・コードでは、これは以下のように書いた方がよいでしょう:
1247364
1248In normal application code, this would be better written as:
1249
1250=end original
1251
1252通常のアプリケーションコードでは、これは以下のように書いた方がよいでしょう:
1253
1254365 use Win32::OLE qw(in);
1255366 # ...
1256367 my @sheets = in $Excel->Worksheets;
1257368
1258369=item _Unique
1259370
1260=begin original
371C<_Unique> オプションはWin32::OLEがネイティブのCOM/OLEオブジェクトと１対1のマッピングを維持することを保証します。 このオプションがないと、元になっている同じCOMオブジェクトのために異なるWin32::OLEオブジェクトを取得し、同じプロパティを重複して問い合わせることになりかねません。
1261372
1262The C<_Unique> options guarantees that Win32::OLE will maintain a
373ユニーク・プロキシーを使うと、特定のノードを既に訪れたことを理解するためのツリー構造横断アルゴリズムは簡単になります。 このオプションは高くつきます: Win32::OLEがすべての存在するオブジェクトと対応するプロキシーのグローバルなハッシュと維持しなければならなりません。 オブジェクトがプロセスの外側に、あるいは異なるコンピュータにあったりしたら、COMオブジェクトの識別子チェックも同様に高価になりかねません。 このためこのオプションはプログラムがデバッガで実行されるのでなければ、デフォルトではオフです。
1263one-to-one mapping between Win32::OLE objects and the native COM/OLE
1264objects. Without this option, you can query the same property twice
1265and get two different Win32::OLE objects for the same underlying COM
1266object.
1267374
1268=end original
375残念ながら、このオプションは常に助けになるわけではありません。 いくつかのプログラムは同じプロパティであってさえも、何度も聞くと新しいCOMオブジェクトを返すことがあります（特にコレクションについては）。 この場合、これらのオブジェクトが事実上同じであると見分けるためにWin32::OLEができることは何もありません（というのもそれはCOMレベルではないからです）。
1269376
1270C<_Unique> オプションは Win32::OLE がネイティブの COM/OLE オブジェクトと
377C<_Unique> オプションは1（有効）または0（無効、デフォルト）のどちらかに設定できます。
12711 対 1 のマッピングを維持することを保証します。
1272このオプションがないと、元になっている同じ COM オブジェクトのために異なる
1273Win32::OLE オブジェクトを取得し、同じプロパティを重複して
1274問い合わせることになりかねません。
1275378
1276=begin original
1277
1278Using a unique proxy makes life easier for tree traversal algorithms
1279to recognize they already visited a particular node. This option
1280comes at a price: Win32::OLE has to maintain a global hash of all
1281outstanding objects and their corresponding proxies. Identity checks
1282on COM objects can also be expensive if the objects reside
1283out-of-process or even on a different computer. Therefore this option
1284is off by default unless the program is being run in the debugger.
1285
1286=end original
1287
1288ユニークプロキシーを使うと、特定のノードを既に訪れたことを
1289理解するためのツリー構造横断アルゴリズムは簡単になります。
1290このオプションは大きな犠牲を払います: Win32::OLE がすべての存在する
1291オブジェクトと対応するプロキシーのグローバルなハッシュと
1292維持しなければなりません。
1293オブジェクトがプロセスの外側に、あるいは異なるコンピュータにあったりしたら、
1294COM オブジェクトの識別子チェックも同様に高価になりかねません。
1295このためこのオプションはプログラムがデバッガで実行されるのでなければ、
1296デフォルトではオフです。
1297
1298=begin original
1299
1300Unfortunately, this option doesn't always help. Some programs will
1301return new COM objects for even the same property when asked for it
1302multiple times (especially for collections). In this case, there is
1303nothing Win32::OLE can do to detect that these objects are in fact
1304identical (because they aren't at the COM level).
1305
1306=end original
1307
1308残念ながら、このオプションは常に助けにはなりません。
1309いくつかのプログラムは同じプロパティであってさえも、何度も聞くと新しい
1310COM オブジェクトを返すことがあります(特にコレクションについては)。
1311この場合、これらのオブジェクトが事実上同じであると見分けるために
1312Win32::OLE ができることは何もありません(というのもそれは COM レベルでは
1313ないからです)。
1314
1315=begin original
1316
1317The C<_Unique> option can be set to either 1 (enabled) or 0 (disabled,
1318default).
1319
1320=end original
1321
1322C<_Unique> オプションは1(有効)または0(無効、デフォルト)のどちらかに
1323設定できます。
1324
1325379=back
1326380
1327381=head1 EXAMPLES
1328382
1329(例)
383これは簡単なMicrosoft Excelアプリケーションです。
1330384
1331=begin original
1332
1333Here is a simple Microsoft Excel application.
1334
1335=end original
1336
1337これは簡単な Microsoft Excel アプリケーションです。
1338
1339385 use Win32::OLE;
1340386
1341387 # use existing instance if Excel is already running
1342388 eval {$ex = Win32::OLE->GetActiveObject('Excel.Application')};
1343389 die "Excel not installed" if $@;
1344390 unless (defined $ex) {
1345391 $ex = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;})
1346392 or die "Oops, cannot start Excel";
1347393 }
1348394
1349395 # get a new workbook
1350396 $book = $ex->Workbooks->Add;
1351397
1352398 # write to a particular cell
1353399 $sheet = $book->Worksheets(1);
1354400 $sheet->Cells(1,1)->{Value} = "foo";
1355401
1356402 # write a 2 rows by 3 columns range
1357403 $sheet->Range("A8:C9")->{Value} = [[ undef, 'Xyzzy', 'Plugh' ],
1358404 [ 42, 'Perl', 3.1415 ]];
1359405
1360406 # print "XyzzyPerl"
1361407 $array = $sheet->Range("A8:C9")->{Value};
1362408 for (@$array) {
1363409 for (@$_) {
1364410 print defined($_) ? "$_|" : "<undef>|";
1365411 }
1366412 print "\n";
1367413 }
1368414
1369415 # save and exit
1370416 $book->SaveAs( 'test.xls' );
1371417 undef $book;
1372418 undef $ex;
1373419
1374=begin original
420Win32::OLE->newメソッドでデストラクタが指定されていることに注意してください。 これはPerlプログラムが死んだときでさえも、Excelが適切に終了されることを保証します。 そうでなければExcelのOLEインスタンスが開いたあとで、アプリケーションが死ぬとプロセス・リークになりかねません。 OLEオブジェクトが確実に適切に片づけられるようにするのはモジュール利用者の責任です!
1375421
1376Please note the destructor specified on the Win32::OLE->new method. It ensures
422以下はVariantデータ型を使った例です。
1377that Excel will shutdown properly even if the Perl program dies. Otherwise
1378there could be a process leak if your application dies after having opened
1379an OLE instance of Excel. It is the responsibility of the module user to
1380make sure that all OLE objects are cleaned up properly!
1381423
1382=end original
1383
1384Win32::OLE->new メソッドでデストラクタが指定されていることに
1385注意してください。
1386これは Perl プログラムが死んだときでさえも、Excel が適切に終了されることを
1387保証します。
1388そうでなければ Excel の OLE インスタンスが開いたあとで、アプリケーションが
1389die とプロセスリークになりかねません。
1390OLE オブジェクトが確実に適切に片づけられるようにするのはモジュール利用者の
1391責任です!
1392
1393=begin original
1394
1395Here is an example of using Variant data types.
1396
1397=end original
1398
1399以下は Variant データ型を使った例です。
1400
1401424 use Win32::OLE;
1402425 use Win32::OLE::Variant;
1403426 $ex = Win32::OLE->new('Excel.Application', \&OleQuit) or die "oops\n";
1404427 $ex->{Visible} = 1;
1405428 $ex->Workbooks->Add;
1406429 # should generate a warning under -w
1407430 $ovR8 = Variant(VT_R8, "3 is a good number");
1408431 $ex->Range("A1")->{Value} = $ovR8;
1409432 $ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970');
1410433
1411434 sub OleQuit {
1412435 my $self = shift;
1413436 $self->Quit;
1414437 }
1415438
1416=begin original
439上記では文字列は"3 is a good number"ではなく、"3"をセルA1に入れます。 セルA2は日付を持ちます:
1417440
1418The above will put value "3" in cell A1 rather than the string
441同様に、バイナリ・データでメソッドを呼び出すためには、以下のようにできます:
1419"3 is a good number". Cell A2 will contain the date.
1420442
1421=end original
1422
1423上記では文字列は "3 is a good number" ではなく、"3" をセル A1 に入れます。
1424セル A2 は日付を持ちます:
1425
1426=begin original
1427
1428Similarly, to invoke a method with some binary data, you can
1429do the following:
1430
1431=end original
1432
1433同様に、バイナリデータでメソッドを呼び出すためには、以下のようにできます:
1434
1435443 $obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") );
1436444
1437=begin original
445以下のものは基本的にnew()とDESTROY()を除いたすべてを委任するラッパー・クラスです。 下記のラッパー・クラスは、アプリケーションが適切なクリーンアップなしに死ぬことが免れないときに、接続を適切に終らせるもう1つの方法です。 あなた自身のラッパーは、独自に確証したいメソッドをオーバーライドするといったように、おそらくあなたの扱いたい特定のOLEオブジェクトにより特化したようなことをするでしょう。
1438446
1439Here is a wrapper class that basically delegates everything but
1440new() and DESTROY(). The wrapper class shown here is another way to
1441properly shut down connections if your application is liable to die
1442without proper cleanup. Your own wrappers will probably do something
1443more specific to the particular OLE object you may be dealing with,
1444like overriding the methods that you may wish to enhance with your
1445own.
1446
1447=end original
1448
1449以下のものは基本的に new() と DESTROY() を除いたすべてを委任する
1450ラッパークラスです。
1451下記のラッパークラスは、アプリケーションが適切なクリーンアップなしに
1452死ぬことが免れないときに、接続を適切に終らせるもう一つの方法です。
1453あなた自身のラッパーは、独自に確証したいメソッドを
1454オーバーライドするといったように、おそらくあなたの扱いたい特定の
1455OLE オブジェクトにより特化したようなことをするでしょう。
1456
1457447 package Excel;
1458448 use Win32::OLE;
1459449
1460450 sub new {
1461451 my $s = {};
1462452 if ($s->{Ex} = Win32::OLE->new('Excel.Application')) {
1463453 return bless $s, shift;
1464454 }
1465455 return undef;
1466456 }
1467457
1468458 sub DESTROY {
1469459 my $s = shift;
1470460 if (exists $s->{Ex}) {
1471461 print "# closing connection\n";
1472462 $s->{Ex}->Quit;
1473463 return undef;
1474464 }
1475465 }
1476466
1477467 sub AUTOLOAD {
1478468 my $s = shift;
1479469 $AUTOLOAD =~ s/^.*:://;
1480470 $s->{Ex}->$AUTOLOAD(@_);
1481471 }
1482472
1483473 1;
1484474
1485=begin original
475上記のモジュールは、異常終了のさいに接続を閉じるように気をつけてくれる点を除いて、Win32::OLEとまったく同じように使うことができます。
476この特定の例の効果はWin32::OLE::newのデストラクタ引数を使うことによって、より簡単に実現できるということに注意してください:
1486477
1487The above module can be used just like Win32::OLE, except that
1488it takes care of closing connections in case of abnormal exits.
1489Note that the effect of this specific example can be easier accomplished
1490using the optional destructor argument of Win32::OLE::new:
1491
1492=end original
1493
1494上記のモジュールは、異常終了の際に接続を閉じるように気をつけてくれる点を
1495除いて、Win32::OLE とまったく同じように使えます。
1496この特定の例の効果は Win32::OLE::new のデストラクタ引数を使うことによって、
1497より簡単に実現できるということに注意してください:
1498
1499478 my $Excel = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;});
1500479
1501=begin original
480上記の例での委任は特化されたオブジェクトでのメソッド呼出しのさらなる継承への見方と同じではないことに注意してください。 詳細については L<perlobj>, L<perltoot>, L<perlbot>を参照してください。
481本当のサブクラス化（@ISAを設定することによって利用できることになる）も、以下のデモンストレーションのように可能です:
1502482
1503Note that the delegation shown in the earlier example is not the same as
1504true subclassing with respect to further inheritance of method calls in your
1505specialized object. See L<perlobj>, L<perltoot> and L<perlbot> for details.
1506True subclassing (available by setting C<@ISA>) is also feasible,
1507as the following example demonstrates:
1508
1509=end original
1510
1511上記の例での委任は特化されたオブジェクトでのメソッド呼び出しのさらなる
1512継承への見方と同じではないことに注意してください。
1513詳細については L<perlobj>, L<perltoot>, L<perlbot> をご覧ください。
1514本当のサブクラスか(C<@ISA> を設定することによって利用できることになる)も、
1515以下のデモンストレーションのように可能です:
1516
1517483 #
1518484 # Add error reporting to Win32::OLE
1519485 #
1520486
1521487 package Win32::OLE::Strict;
1522488 use Carp;
1523489 use Win32::OLE;
1524490
1525491 use strict qw(vars);
1526492 use vars qw($AUTOLOAD @ISA);
1527493 @ISA = qw(Win32::OLE);
1528494
1529495 sub AUTOLOAD {
1530496 my $obj = shift;
1531497 $AUTOLOAD =~ s/^.*:://;
1532498 my $meth = $AUTOLOAD;
1533499 $AUTOLOAD = "SUPER::" . $AUTOLOAD;
1534500 my $retval = $obj->$AUTOLOAD(@_);
1535501 unless (defined($retval) || $AUTOLOAD eq 'DESTROY') {
1536502 my $err = Win32::OLE::LastError();
1537503 croak(sprintf("$meth returned OLE error 0x%08x",$err))
1538504 if $err;
1539505 }
1540506 return $retval;
1541507 }
1542508
1543509 1;
1544510
1545=begin original
511このパッケージはコンストラクラnew()をWin32::OLEパッケージから継承しています。 パッケージについての情報がオブジェクトによってキャッシュされるためにWin32::OLEを再びblessすることはできないことに注意しすることは大切なことです。 常に正しいパッケージを通して、new() コンストラクタを呼び出してください！
1546512
1547This package inherits the constructor new() from the Win32::OLE
1548package. It is important to note that you cannot later rebless a
1549Win32::OLE object as some information about the package is cached by
1550the object. Always invoke the new() constructor through the right
1551package!
1552
1553=end original
1554
1555このパッケージはコンストラクラ new() を Win32::OLE パッケージから
1556継承しています。
1557パッケージについての情報がオブジェクトによってキャッシュされるために
1558Win32::OLE を再び bless することはできないことに注意しすることは
1559大切なことです。
1560常に正しいパッケージを通して、new() コンストラクタを呼び出してください!
1561
1562=begin original
1563
1564Here's how the above class will be used:
1565
1566=end original
1567
1568513以下に上記のクラスがどのように使われるかを示します:
1569514
1570515 use Win32::OLE::Strict;
1571516 my $Excel = Win32::OLE::Strict->new('Excel.Application', 'Quit');
1572517 my $Books = $Excel->Workbooks;
1573518 $Books->UnknownMethod(42);
1574519
1575=begin original
520上記のサンプルでUnknownMethod()を呼び出すと、それは以下のように捕らえられます:
1576521
1577In the sample above the call to UnknownMethod() will be caught with
1578
1579=end original
1580
1581上記のサンプルで UnknownMethod() を呼び出すと、それは以下のように
1582捕らえられます:
1583
1584522 UnknownMethod returned OLE error 0x80020009 at test.pl line 5
1585523
1586=begin original
524というのもWorkbooksオブジェクトは$ExcelオブジェクトからWin32::OLE::Strictクラスを継承しているからです。
1587525
1588because the Workbooks object inherits the class C<Win32::OLE::Strict> from the
1589C<$Excel> object.
1590
1591=end original
1592
1593というのも Workbooks オブジェクトは C<$Excel> オブジェクトから
1594C<Win32::OLE::Strict> クラスを継承しているからです。
1595
1596526=head1 NOTES
1597527
1598(注意)
1599
1600528=head2 Hints for Microsoft Office automation
1601529
1602(Microsoft Office オートメーションのためのヒント)
1603
1604530=over 8
1605531
1606532=item Documentation
1607533
1608(ドキュメント)
534Office アプリケーションのオブジェクト・モデルは、多くのアプリケーションのためのVisual Basicリファレンス・ガイドで定義されています。 これらは典型的には、標準インストールによってデフォルトでインストールされません。 これらはセットアップ・プログラムをカスタム・インストール・オプションで実行することによって後から追加することができます。
1609535
1610=begin original
1611
1612The object model for the Office applications is defined in the Visual Basic
1613reference guides for the various applications. These are typically not
1614installed by default during the standard installation. They can be added
1615later by rerunning the setup program with the custom install option.
1616
1617=end original
1618
1619Office アプリケーションのオブジェクトモデルは、多くのアプリケーションのための
1620Visual Basic リファレンスガイドで定義されています。
1621これらは典型的には、標準インストールによってデフォルトで
1622インストールされません。
1623これらはセットアッププログラムをカスタムインストールオプションで
1624実行することによって後から追加できます。
1625
1626536=item Class, Method and Property names
1627537
1628(クラス、メソッド、プロパティ名)
538Officeのバージョンによっては名前は変更されています。 例えばOffice95ではApplicationはメソッドでしたが、Office97ではプロパティです。 このためOffice95オブジェクトに問い合わせたときには、keys %$object によるプロパティ名のリストには現れません。
1629539
1630=begin original
540クラス名はそのオブジェクトを作るメソッド/プロパティ名と常に同じではありません。 例えばWorkbookメソッドはOffice95ではWorkbookオブジェクトを返しますが、Office97では_Workbookを返します。
1631541
1632The names have been changed between different versions of Office. For
1633example C<Application> was a method in Office 95 and is a property in
1634Office97. Therefore it will not show up in the list of property names
1635C<keys %$object> when querying an Office 95 object.
1636
1637=end original
1638
1639Office のバージョンによっては名前は変更されています。
1640例えば Office95 では C<Application> はメソッドでしたが、Office97 では
1641プロパティです。
1642このため Office95 オブジェクトに問い合わせたときには、C<keys %$object> による
1643プロパティ名のリストには現れません。
1644
1645=begin original
1646
1647The class names are not always identical to the method/property names
1648producing the object. E.g. the C<Workbook> method returns an object of
1649type C<Workbook> in Office 95 and C<_Workbook> in Office 97.
1650
1651=end original
1652
1653クラス名はそのオブジェクトを作るメソッド/プロパティ名と常に
1654同じではありません。
1655例えば C<Workbook> メソッドは Office95 では C<Workbook> オブジェクトを
1656返しますが、Office97 では C<_Workbook> を返します。
1657
1658542=item Moniker (GetObject support)
1659543
1660(モニカ (GetObject サポート))
544Officeアプリケーションはファイル・モニカだけを実装しているようです。 例えばGetObject("File.XLS!Sheet") を通してあるワークシート・オブジェクトを取り出すことはできないようです。 さらにExcel95ではモニカはWorkseetオブジェクトを開始し、 Excel97ではWorkbookオブジェクトを返します。 移植性のあるコードを書くためには、Win32::OLE:: QueryObjectType クラス・メソッドまたは$object->{Version} のどちらかかを使うことができます。
1661545
1662=begin original
1663
1664Office applications seem to implement file monikers only. For example
1665it seems to be impossible to retrieve a specific worksheet object through
1666C<GetObject("File.XLS!Sheet")>. Furthermore, in Excel 95 the moniker starts
1667a Worksheet object and in Excel 97 it returns a Workbook object. You can use
1668either the Win32::OLE::QueryObjectType class method or the $object->{Version}
1669property to write portable code.
1670
1671=end original
1672
1673Office アプリケーションはファイルモニカだけを実装しているようです。
1674例えば C<GetObject("File.XLS!Sheet")> を通してあるワークシートオブジェクトを
1675取り出すことはできないようです。
1676さらに Excel95 ではモニカは Worksheet オブジェクトを開始し、Excel97 では
1677Workbook オブジェクトを返します。
1678移植性のあるコードを書くためには、Win32::OLE::QueryObjectType
1679クラスメソッドまたは $object->{Version} のどちらかかを使えます。
1680
1681546=item Enumeration of collection objects
1682547
1683(コレクションオブジェクトの列挙)
548列挙は不完全にしか実装されていないようです。 Office95アプリケーションはReset()もClone()メソッドもサポートしていないようです。 Clone()メソッドはOffice97でも未実装です。 しかしながら、Visual Basicと同じようにコレクションを一通りみるためには、C<for each>構造が機能します。
1684549
1685=begin original
1686
1687Enumerations seem to be incompletely implemented. Office 95 application don't
1688seem to support neither the Reset() nor the Clone() methods. The Clone()
1689method is still unimplemented in Office 97. A single walk through the
1690collection similar to Visual Basics C<for each> construct does work however.
1691
1692=end original
1693
1694列挙は不完全にしか実装されていないようです。
1695Office95 アプリケーションは Reset() も Clone() メソッドも
1696サポートしていないようです。
1697Clone() メソッドは Office97 でも未実装です。
1698しかしながら、Visual Basic の C<for each> 構造と同じようにコレクションを
1699一通りみるのは動作します。
1700
1701550=item Localization
1702551
1703(地域化)
552Office97からMicrosoftはローカライズされたクラス、メソッド、プロパティ名を変更し、英語に戻しました。 日付と通貨引数はまだ地域特有の解釈の対象となっていることに注意してください。 Visual Basicがタイプ・ライブラリ特有のロケールを使うのに対し、PerlはすべてのOLEトランザクションのためにシステム・デフォルト・ロケールを利用します。 VisualBasic スクリプトは相対的な参照を指定するために文字列引数として"R1C1"を使うでしょう。 ドイツ語Windowsで実行されるPerlスクリプトは "Z1S1"を使わなければなりません。 移植性のあるスクリプトを書くためには、LCIDモジュール・オプションをEnglishロケールに設定してください。 この変数はOLEオブジェクトを作成した後に変更するべきではありません; 途中でロケールが変更されると、メソッドによっては出たらめに失敗するようです。
1704553
1705=begin original
1706
1707Starting with Office 97 Microsoft has changed the localized class, method and
1708property names back into English. Note that string, date and currency
1709arguments are still subject to locale specific interpretation. Perl uses the
1710system default locale for all OLE transaction whereas Visual Basic uses a
1711type library specific locale. A Visual Basic script would use "R1C1" in string
1712arguments to specify relative references. A Perl script running on a German
1713language Windows would have to use "Z1S1". Set the LCID module option
1714to an English locale to write portable scripts. This variable should
1715not be changed after creating the OLE objects; some methods seem to randomly
1716fail if the locale is changed on the fly.
1717
1718=end original
1719
1720Office97 から Microsoft はローカライズされたクラス、メソッド、プロパティ名を
1721変更し、英語に戻しました。
1722日付と通貨引数はまだ地域特有の解釈の対象となっていることに注意してください。
1723Visual Basic がタイプライブラリ特有のロケールを使うのに対し、Perl は
1724すべての OLE トランザクションのためにシステムデフォルトロケールを
1725利用します。
1726VisualBasic スクリプトは相対的な参照を指定するために文字列引数として
1727"R1C1" を使うでしょう。
1728ドイツ語 Windows で実行される Perl スクリプトは "Z1S1" を
1729使わなければなりません。
1730移植性のあるスクリプトを書くためには、LCID モジュールオプションを
1731English ロケールに設定してください。
1732この変数は OLE オブジェクトを作成した後に変更するべきではありません;
1733途中でロケールが変更されると、メソッドによっては出たらめに失敗するようです。
1734
1735554=item SaveAs method in Word 97 doesn't work
1736555
1737(Word97 での SaveAs メソッドは機能しません)
556これはWord97でのバグであることがわかっています。 Word/Foxpro互換性欠如（incompatibility）のMS knowledge baseをご覧ください。 その問題はPerl OLEインターフェースにも同じようにあてはまります。 回避する方法はWordBasic互換のオブジェクトを使うことです。 しかしそれはネイティブなメソッドのすべてのオプションをサポートしているわけではありません。
1738557
1739=begin original
1740
1741This is an known bug in Word 97. Search the MS knowledge base for Word /
1742Foxpro incompatibility. That problem applies to the Perl OLE interface as
1743well. A workaround is to use the WordBasic compatibility object. It doesn't
1744support all the options of the native method though.
1745
1746=end original
1747
1748これは Word97 でのバグであることがわかっています。
1749Word / Foxpro の非非互換性については MS knowledge base を検索してください。
1750その問題は Perl OLE インターフェースにも同じように当てはまります。
1751回避する方法は WordBasic 互換のオブジェクトを使うことです。
1752しかしそれはネイティブなメソッドのすべてのオプションを
1753サポートしているわけではありません。
1754
1755558 $Word->WordBasic->FileSaveAs($file);
1756559
1757=begin original
560この問題はOffice97サービス・リリース1を提供することにより修正されるようです。
1758561
1759The problem seems to be fixed by applying the Office 97 Service Release 1.
1760
1761=end original
1762
1763この問題は Office97 サービスリリース 1 を適用することにより
1764修正されるようです。
1765
1766562=item Randomly failing method calls
1767563
1768(メソッド呼出しがでたらめに失敗する)
564選択/アクティブにされていないオブジェクトを変更することは時折、壊れやすいうです。 これらのほとんどの問題は、操作される前にグラフ/シート/ドキュメントを選択あるいは、アクティブにしておくことによりなくなるようです（まるで対話的なユーザーが自動的にしているかのように）。
1769565
1770=begin original
1771
1772It seems like modifying objects that are not selected/activated is sometimes
1773fragile. Most of these problems go away if the chart/sheet/document is
1774selected or activated before being manipulated (just like an interactive
1775user would automatically do it).
1776
1777=end original
1778
1779選択/アクティブにされていないオブジェクトを変更することは時折、
1780壊れやすいようです。
1781これらのほとんどの問題は、操作される前にグラフ/シート/ドキュメントを
1782選択あるいは、アクティブにしておくことによりなくなるようです(まるで対話的な
1783ユーザーが自動的にしているかのように)。
1784
1785566=back
1786567
1787568=head2 Incompatibilities
1788569
1789(非互換性)
570Activewareによって（build306として）配布されたバージョンとはいくつかの点で互換性がありません。
1790571
1791=begin original
1792
1793There are some incompatibilities with the version distributed by Activeware
1794(as of build 306).
1795
1796=end original
1797
1798Activeware によって(build 306 として)配布されたバージョンとはいくつかの点で
1799互換性がありません。
1800
1801572=over 8
1802573
1803574=item 1
1804575
1805=begin original
576パッケージの名前が"OLE"から"Win32::OLE"に変更されました。
1806577
1807The package name has changed from "OLE" to "Win32::OLE".
1808
1809=end original
1810
1811パッケージの名前が "OLE" から "Win32::OLE" に変更されました。
1812
1813578=item 2
1814579
1815=begin original
580古い名前が一時的に使えても、"Win32::OLEFoo"という形式の関数は、いまはすべて"Win32::OLE::Foo"です。 Win32::OLECreateObject() はWin32::OLE::CreateObject()に変更され、確立された名前付きのコンストラクタの書き方に向けてWin32::OLE::new()と呼ばれます。
581古い名前は非推奨と考えるべきで、次のバージョンでは削除されるでしょう。
1816582
1817All functions of the form "Win32::OLEFoo" are now "Win32::OLE::Foo",
1818though the old names are temporarily accomodated. Win32::OLECreateObject()
1819was changed to Win32::OLE::CreateObject(), and is now called
1820Win32::OLE::new() bowing to established convention for naming constructors.
1821The old names should be considered deprecated, and will be removed in the
1822next version.
1823
1824=end original
1825
1826古い名前が一時的に使えても、"Win32::OLEFoo" という形式の関数は、いまは
1827すべて "Win32::OLE::Foo" です。
1828Win32::OLECreateObject() は Win32::OLE::CreateObject() に変更され、
1829確立された名前付きのコンストラクタの書き方に向けて Win32::OLE::new() と
1830呼ばれます。
1831古い名前は廃止予定と考えるべきです; そして次のバージョンでは
1832削除されるでしょう。
1833
1834583=item 3
1835584
1836=begin original
585パッケージ"OLE::Variant"は今では"Win32::OLE::Variant"です。
1837586
1838Package "OLE::Variant" is now "Win32::OLE::Variant".
1839
1840=end original
1841
1842パッケージ "OLE::Varinat" は今では "Win32::OLE::Variant" です。
1843
1844587=item 4
1845588
1846=begin original
589Variant関数は新しく、デフォルトでエクスポートされます。 すべてのVT_XXXタイプ定数も同様です。
1847590
1848The Variant function is new, and is exported by default. So are
1849all the VT_XXX type constants.
1850
1851=end original
1852
1853Variant 関数は新しく、デフォルトでエクスポートされます。
1854すべての VT_XXX タイプ定数も同様です。
1855
1856
1857591=item 5
1858592
1859=begin original
593コレクション・オブジェクトのサポートはWin32::OLE::Enumパッケージに移りました。 C<keys %$object>メソッドは今はオブジェクトのプロパティを列挙するために使われます。
1860594
1861The support for collection objects has been moved into the package
1862Win32::OLE::Enum. The C<keys %$object> method is now used to enumerate
1863the properties of the object.
1864
1865=end original
1866
1867コレクションオブジェクトのサポートは Win32::OLE::Enum パッケージに
1868移りました。
1869C<keys %$object> メソッドは今はオブジェクトのプロパティを列挙するために
1870使われます。
1871
1872595=back
1873596
1874597=head2 Bugs and Limitations
1875598
1876(バグと制約)
1877
1878599=over 8
1879600
1880601=item *
1881602
1882=begin original
603Win32::OLEメソッドと同じ名前(Dispatch, Invoke, SetProperty, DESTROYなど）のネイティブなOLEメソッドを呼び出すためには、Invokeを使う必要があります:
1883604
1884To invoke a native OLE method with the same name as one of the
1885Win32::OLE methods (C<Dispatch>, C<Invoke>, C<SetProperty>, C<DESTROY>,
1886etc.), you have to use the C<Invoke> method:
1887
1888=end original
1889
1890Win32::OLE メソッドと同じ名前(C<Dispatch>, C<Invoke>, C<SetProperty>,
1891C<DESTROY> など)のネイティブな OLE メソッドを呼び出すためには、C<Invoke> を
1892使う必要があります:
1893
1894605 $Object->Invoke('Dispatch', @AdditionalArgs);
1895606
1896=begin original
607同じことは Exporter や the Dynaloader でエクスポートされるモジュール、つまり C<export>, C<export_to_level>, C<import>,
1897
1898The same is true for names exported by the Exporter or the Dynaloader
1899modules, e.g.: C<export>, C<export_to_level>, C<import>,
1900608C<_push_tags>, C<export_tags>, C<export_ok_tags>, C<export_fail>,
1901609C<require_version>, C<dl_load_flags>,
1902610C<croak>, C<bootstrap>, C<dl_findfile>, C<dl_expandspec>,
1903611C<dl_find_symbol_anywhere>, C<dl_load_file>, C<dl_find_symbol>,
1904C<dl_undef_symbols>, C<dl_install_xsub> and C<dl_error>.
612C<dl_undef_symbols>, C<dl_install_xsub>, C<dl_error> にもいえます。
1905613
1906=end original
1907
1908同じことが Exporter または Dynaloader モジュールによってエクスポートされる
1909名前についてもあてはまります。
1910例えば: C<export>, C<export_to_level>, C<import>,
1911C<_push_tags>, C<export_tags>, C<export_ok_tags>, C<export_fail>,
1912C<require_version>, C<dl_load_flags>,
1913C<croak>, C<bootstrap>, C<dl_findfile>, C<dl_expandspec>,
1914C<dl_find_symbol_anywhere>, C<dl_load_file>, C<dl_find_symbol>,
1915C<dl_undef_symbols>, C<dl_install_xsub>, C<dl_error>
1916
1917614=back
1918615
1919616=head1 SEE ALSO
1920617
1921=begin original
618L<Win32::OLE::Const>, L<Win32::OLE::Enum>, L<Win32::OLE::NLS>, L<Win32::OLE::Variant> のドキュメントにはWin32上のPerlでのOLEサポートについての追加の情報が入っています。
1922619
1923The documentation for L<Win32::OLE::Const>, L<Win32::OLE::Enum>,
1924L<Win32::OLE::NLS> and L<Win32::OLE::Variant> contains additional
1925information about OLE support for Perl on Win32.
1926
1927=end original
1928
1929L<Win32::OLE::Const>, L<Win32::OLE::Enum>, L<Win32::OLE::NLS>,
1930L<Win32::OLE::Variant> のドキュメントには Win32 上の Perl のための
1931追加の OLE サポートについての情報が入っています。
1932
1933620=head1 AUTHORS
1934621
1935622Originally put together by the kind people at Hip and Activeware.
1936623
1937624Gurusamy Sarathy <gsar@activestate.com> subsequently fixed several
1938625major bugs, memory leaks, and reliability problems, along with some
1939626redesign of the code.
1940627
1941628Jan Dubois <jand@activestate.com> pitched in with yet more massive redesign,
1942629added support for named parameters, and other significant enhancements.
1943630He's been hacking on it ever since.
1944631
1945632Please send questions about problems with this module to the
1946633Perl-Win32-Users mailinglist at ActiveState.com. The mailinglist charter
1947634requests that you put an [OLE] tag somewhere on the subject line (for OLE
1948635related questions only, of course).
1949636
1950637=head1 COPYRIGHT
1951638
1952639 (c) 1995 Microsoft Corporation. All rights reserved.
1953640 Developed by ActiveWare Internet Corp., now known as
1954641 ActiveState Tool Corp., http://www.ActiveState.com
1955642
1956643 Other modifications Copyright (c) 1997-2000 by Gurusamy Sarathy
1957644 <gsar@activestate.com> and Jan Dubois <jand@activestate.com>
1958645
1959646 You may distribute under the terms of either the GNU General Public
1960647 License or the Artistic License, as specified in the README file.
1961648
1962649=head1 VERSION
1963650
1964Version 0.1502 7 September 2001
651Version 0.1703 6 September 2005
1965
1966=begin meta
1967
1968Translated: Hippo2000 <GCD00051@nifty.ne.jp> (0.14)
1969Updated: SHIRAKATA Kentaro <argrath@ub32.org> (0.1502)
1970Status: completed
1971
1972=end meta
1973652
1974653=cut
Powered by Amon2, 翻訳, サイト. Operated by Japan Perl Association