archived-doc-ja/reference/com/com.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 122f551481914f577ac61c629b9ebcb371f80fc7 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi -->
<phpdoc:classref xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="class.com" xmlns="http://docbook.org/ns/docbook">
 <titleabbrev>COM</titleabbrev>
 <title>COM クラス</title>
 <partintro>

 <section xml:id="class.com.class">
  <title>説明</title>
  <simpara>
   COM クラスにより、OLE 互換の COM オブジェクトのインスタンスを作成し、
   そのメソッドをコールしたりそのプロパティにアクセスしたりすることが
   可能となります。
  </simpara>
  <simpara>
   <literal>$obj = new COM("Application.ID")</literal>
  </simpara>
 </section>
 <section xml:id="com.com">
  <title>メソッド</title>
  <methodsynopsis>
   <methodname>COM::COM</methodname>
   <methodparam><type>string</type><parameter>module_name</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>server_name</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>codepage</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>typelib</parameter></methodparam>
  </methodsynopsis>
  <para>
   COM クラスのコンストラクタ。 パラメータには以下のような意味があります。
   <variablelist>
    <varlistentry>
     <term>module_name</term>
     <listitem>
      <simpara>
       ロードするコンポーネントを指定する
       プログラム ID、クラス ID またはモニカです。
      </simpara>
      <simpara>
       プログラムID は、通常、アプリケーションまたは DLL の名前の後に、
       <literal>Word.Application</literal> のようにピリオドと
       オブジェクト名を付けたものです。
      </simpara>
      <simpara>
       クラス ID は、指定されたクラスがユニークに定義する UUID です。
      </simpara>
      <simpara>
       モニカは、URL スキームの考え方に似た特別な命名形式です。リソースと、
       それがどのように読み込まれるかを指定します。例として、モジュール名に
       Word ドキュメントのフルパスを指定すると、Word を読み込んで
       ドキュメントに対応するオブジェクトを取得することができます。
       あるいは、LDAP への ADSI インターフェイスを指すモニカとして
       <literal>LDAP:</literal> を使用することが可能です。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>server_name</term>
     <listitem>
      <simpara>
       コンポーネントが読み込んで実行される DCOM サーバーの名前です。
       &null; の場合、オブジェクトはアプリケーションのデフォルトを
       指定して実行されます。典型的なデフォルトは、ローカルマシン上で
       実行させることでが、管理者によってはアプリケーションを別の
       マシン上で実行させるように設定しているかもしれません。
      </simpara>
      <simpara>
       非 &null; 値をサーバーに指定した場合、
       <xref linkend="ini.com.allow-dcom"/> 設定オプションが
       &true; に設定されていない限り PHP はオブジェクトの読み込みを
       拒否します。
      </simpara>
      <para>
       <parameter>server_name</parameter> が配列の場合、以下の要素
       (大文字小文字を区別します!)を含まなければなりません。
       これらはすべて省略可能であることに注意しましょう
       (とはいえ、Username および Password は両方指定する必要があります)。
       もしサーバー設定を省略した場合は(上で説明した)デフォルトのサーバーが
       使用され、オブジェクトの生成は <xref linkend="ini.com.allow-dcom"/>
       ディレクティブの影響を受けません。
       <table>
        <title>DCOM サーバー名</title>
        <tgroup cols="3">
         <thead>
          <row>
           <entry><parameter>server_name</parameter> のキー</entry>
           <entry>型</entry>
           <entry>説明</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>Server</entry>
           <entry>string</entry>
           <entry>サーバーの名前。</entry>
          </row>
          <row>
           <entry>Username</entry>
           <entry>string</entry>
           <entry>接続するユーザー名。</entry>
          </row>
          <row>
           <entry>Password</entry>
           <entry>string</entry>
           <entry><parameter>Username</parameter> に対するパスワード。</entry>
          </row>
          <row>
           <entry>Flags</entry>
           <entry>integer</entry>
           <entry>以下の定数のうちのひとつまたは複数の論理和。
            <constant>CLSCTX_INPROC_SERVER</constant>、
            <constant>CLSCTX_INPROC_HANDLER</constant>、
            <constant>CLSCTX_LOCAL_SERVER</constant>、
            <constant>CLSCTX_REMOTE_SERVER</constant>、
            <constant>CLSCTX_SERVER</constant> および
            <constant>CLSCTX_ALL</constant>。指定されていない場合の
            デフォルト値は、<parameter>Server</parameter> を省略した場合が
            <constant>CLSCTX_SERVER</constant> でサーバー名を指定した場合は
            <constant>CLSCTX_REMOTE_SERVER</constant> です。
            これらの定数の意味についての詳細な情報を得るには、Microsoft
            のドキュメントで CoCreateInstance について調べましょう。
            通常はこれらを使用する必要はないはずです。
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>codepage</term>
     <listitem>
      <simpara>
       文字列と Unicode 文字列との相互変換に使用するコードページを指定します。
       PHP の文字列と COM オブジェクトのメソッドとの受け渡しの際には、いつも
       変換が行われます。PHP 5 では、コードページの扱いは面倒です。というのは、
       オブジェクトだけではなくオブジェクトから返される variant にもそれが
       影響するからです。
      </simpara>
      <simpara>
       とりうる値は
       <constant>CP_ACP</constant> (システムのデフォルト ANSI
       コードページを使用する - このパラメータが指定されなかった場合の
       デフォルト)、
       <constant>CP_MACCP</constant>、
       <constant>CP_OEMCP</constant>、<constant>CP_SYMBOL</constant>、
       <constant>CP_THREAD_ACP</constant> (現在実行中のスレッドの
       コードページ/ロケールを使用する)、<constant>CP_UTF7</constant>
       および <constant>CP_UTF8</constant> です。コードページに対応する
       数値を指定することも可能です。コードページとそれに対応する数値に
       ついての詳細は、Microsoft のドキュメントを参照ください。
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </section>

 <section xml:id="class.com.overloadedmethods">
  <title>オーバーロードされたメソッド</title>
  <para>
   返されるオブジェクトは、オーバーロードされたものです。つまり、
   PHP 側では通常のクラスのメソッドは見えないということです。
   その代わりに、プロパティやメソッドへのアクセスは COM を通じて行います。
  </para>
  <para>
   PHP 5 以降では、参照渡しのパラメータを受け付けるメソッドを PHP が
   自動検出するようになりました。それらのメソッドについては、PHP が自動的に
   変数を参照渡し形式に変換します。つまり、メソッドのコールをより自然に
   行えるということです。コードの中で特別な処理をする必要はありません。
  </para>
  <para>
   PHP 4 では、パラメータを参照渡しする場合には、そのパラメータをラップする
   ために <xref linkend="class.variant"/> クラスのインスタンスを生成する
   必要があります。
  </para>
 </section>

 <section xml:id="class.com.falsemethods">
  <title>疑似メソッド</title>
  <para>
   PHP 5 より前のバージョンでは、以下のようなメソッド名を COM に渡すことが
   できず、直接 PHP で扱うことができないというあまりうれしくない出来事が
   ありました。PHP 5 ではこれらを解決します。スクリプトの修正方法に
   ついては以下の詳細を参照ください。これらのマジックメソッドの名前は
   大文字小文字を区別しません。
  </para>
  <methodsynopsis xml:id="com.addref">
   <type>void</type><methodname>COM::AddRef</methodname>
   <void/>
  </methodsynopsis>
  <simpara>
   COM オブジェクトの参照カウントを作為的に追加します。
  </simpara>
  <warning>
   <simpara>
    このメソッドを使用することはまずないはずです。
    これは、以下で説明する Release() メソッドを論理的に補完するものとして
    存在するものです。
   </simpara>
  </warning>
  <methodsynopsis xml:id="com.release">
   <type>void</type><methodname>COM::Release</methodname>
   <void/>
  </methodsynopsis>
  <simpara>
   COM オブジェクトの参照カウントを作為的に削除します。
  </simpara>
  <warning>
   <simpara>
    このメソッドを使用することはまずないはずです。
    これは、COM オブジェクトが必要以上に動作を続けてしまうというバグに
    対応する方法として PHP に存在するものです。
   </simpara>
  </warning>
 </section>
 <section xml:id="class.com.iteratormethods">
  <title>反復処理のための疑似メソッド</title>
  <para>
   以下の疑似メソッドは、 <function>com_isenum</function> が &true;
   を返す場合のみ利用可能で、この場合、これらのメソッドは、
   通常は COM オブジェクトにより提供される同じ名前を有する全ての
   メソッドを隠蔽します。これらのメソッドは PHP 5 では完全に廃止されています。
   代わりに <xref linkend="com.examples.foreach"/> を使用してください。
  </para>
  <methodsynopsis xml:id="com.all">
   <type>variant</type><methodname>COM::All</methodname>
   <void/>
  </methodsynopsis>
  <simpara>
   10 の要素を保持する SafeArray を表す variant を返します。
   個々の要素は empty/null の variant となります。この関数は
   イテレータからの全ての要素を含む配列を返すことを想定していますが、
   決して完了しません。使用しないでください。
  </simpara>
  <methodsynopsis xml:id="com.next">
   <type>variant</type><methodname>COM::Next</methodname>
   <void/>
  </methodsynopsis>
  <simpara>
   イテレータの次の要素を表す variant を返します。要素が
   もうない場合には &false; を返します。
  </simpara>
  <methodsynopsis xml:id="com.prev">
   <type>variant</type><methodname>COM::Prev</methodname>
   <void/>
  </methodsynopsis>
  <simpara>
   イテレータの前の要素を現す variant を返します。要素が
   もうない場合には &false; を返します。
  </simpara>
  <methodsynopsis xml:id="com.reset">
   <type>void</type><methodname>COM::Reset</methodname>
   <void/>
  </methodsynopsis>
  <simpara>
   イテレータを最初の場所まで巻き戻します。
  </simpara>
 </section>
 <section xml:id="class.com.examples">
  <title>COM の例</title>
  <para>
   <example xml:id="example.com1">
    <title>COM の例 (1)</title>
    <programlisting role="php">
<![CDATA[
<?php
// word を起動します
$word = new COM("word.application") or die("Unable to instantiate Word");
echo "Loaded Word, version {$word->Version}\n";

// 前面に移動させます
$word->Visible = 1;

// 空のドキュメントを開きます
$word->Documents->Add();

// 何か複雑なことを行います
$word->Selection->TypeText("This is a test...");
$word->Documents[1]->SaveAs("Useless test.doc");

// word を閉じます
$word->Quit();

// オブジェクトを開放します
$word = null;
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example xml:id="example.com2">
    <title>COM の例 (2)</title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = new COM("ADODB.Connection") or die("Cannot start ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

$rs = $conn->Execute("SELECT * FROM sometable");    // レコードセット

$num_columns = $rs->Fields->Count();
echo $num_columns . "\n";

for ($i=0; $i < $num_columns; $i++) {
    $fld[$i] = $rs->Fields($i);
}

$rowcount = 0;
while (!$rs->EOF) {
    for ($i=0; $i < $num_columns; $i++) {
        echo $fld[$i]->value . "\t";
    }
    echo "\n";
    $rowcount++;            // 行カウントの加算
    $rs->MoveNext();
}

$rs->Close();
$conn->Close();

$rs = null;
$conn = null;

?>
]]>
    </programlisting>
   </example>
  </para>
 </section>

 </partintro>
</phpdoc:classref>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->