com_get_active_object

(PHP 5, PHP 7, PHP 8)

com_get_active_object — すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す

説明

com_get_active_object(string $prog_id, ?int $codepage = null): variant

com_get_active_object() は、新しい com オブジェクトのインスタンスを作成することに似ています。しかし、オブジェクトがすでに実行中の場合にはそのオブジェクトが返されるという点が違います。 OLE アプリケーションは、既知のアプリケーションを一度だけ起動させることを許可するために、"Running Object Table" というものを使用します。この関数は、実行中のインスタンスのハンドルを取得するために COM ライブラリ関数 GetActiveObject() を公開します。

パラメータ

prog_id: prog_id は、アクセスしたいオブジェクトの ProgID あるいは CLSID (たとえば Word.Application) である必要があります。
codepage: com クラスの場合と同様の働きをします。

戻り値

要求されたオブジェクトが実行中の場合は、他の COM オブジェクトと同様にスクリプトへ返されます。

エラー / 例外

この関数が失敗する理由はさまざまなものが考えられますが、最も一般的なのはオブジェクトがまだ起動していないことです。そのような場合、例外のエラーコードは MK_E_UNAVAILABLE となります。例外オブジェクトの getCode メソッドを使用することで、例外コードの内容を調べることが可能です。

変更履歴

バージョン	説明
8.0.0	`codepage` は、nullable になりました。

注意

警告

Web 環境で com_get_active_object() を使用することは、あまり良い考えではありません。ほとんどの COM/OLE アプリケーションは複数のクライアントから同時に利用されることを考慮していないのです。(あの) Microsoft Office でさえもです! この件に関する一般的な問題についての詳細な情報は、» Considerations for Server-Side Automation of Office を参照ください。

add a note

User Contributed Notes 1 note

down

gerrit at timingteam dot nl ¶

15 years ago


Please note the next behavior (Apache 2.2.8, W2K, WXP)

If Apache runs as a service, com_get_active_object() always returns MK_E_UNAVAILABLE, even when it is definitely sure that the Running Object Table contains a reference to the required object.

If Apache runs in a console, com_get_active_object()  returns the object handle as required.

This apparently is a Windows issue.

add a note