この例は、ActiveX コントロールを使用するデスクトップアプリケーションと ActionScript との間における、外部 API を使用した通信を示しています。この例では、ActionScript コードを含めて Introvert IM を再利用しており、SWF ファイルも同じものを使用しているため、ActionScript での外部 API の使用については説明しません。前述の例をよく理解しておくと、この例を理解しやすくなります。

この例のデスクトップアプリケーションは、Microsoft Visual Studio .NET を使用して C# で記述されています。ここでは、ActiveX コントロールを使用した外部 API の具体的な操作方法を中心に説明します。この例は、次のことを示しています。

• Flash Player ActiveX コントロールをホスティングしているデスクトップアプリケーションからの ActionScript 関数の呼び出し
• ActionScript からの関数呼び出しの受信、および ActiveX コンテナでのその処理
• ActiveX コンテナへのメッセージ送信に Flash Player が使用するプロキシクラスを使用した、直列化 XML フォーマットの詳細の非表示

このサンプルのアプリケーションファイルを入手するには、www.adobe.com/go/learn_programmingAS3samples_flash を参照してください。Introvert IM C# ファイルは Samples/IntrovertIM_CSharp フォルダにあります。アプリケーションは、次のファイルで構成されています。

サブトピック

• Introvert IM C# アプリケーションの概要
• Shockwave Flash ActiveX コントロールの追加
• ActionScript から ActiveX コンテナへの通信について
• ExternalInterfaceProxy クラスの内部

Introvert IM C# アプリケーションの概要

このサンプルアプリケーションは、互いに通信する 2 つのインスタントメッセージクライアントプログラム（1 つは SWF ファイル内、もう 1 つは Windows Forms に埋め込み）を示しています。ユーザーインターフェイスには Shockwave Flash ActiveX コントロールのインスタンスがあり、その中に、ActionScript IM クライアントのある SWF ファイルがロードされます。また、このインターフェイスには Windows Forms IM クライアントを構成するいくつかのテキストフィールドもあります。1 つ目はメッセージ入力用のフィールド（MessageText）で、2 つ目にはクライアント間で送信されるメッセージの複製（Transcript）が表示されます。第 3 のフィールド（Status）には SWF IM クライアントで設定された availability ステータスが表示されます。

Shockwave Flash ActiveX コントロールの追加

Shockwave Flash ActiveX コントロールを独自の Windows Forms アプリケーションに含めるには、最初にそれを Microsoft Visual Studio Toolbox に追加する必要があります。

コントロールをツールボックスに追加するには :

1. Visual Studio Toolbox を開きます。
2. Visual Studio 2003 の「Windows フォーム」セクション、または Visual Studio 2005 の任意のセクションを右クリックします。Visual Studio 2003 ではコンテキストメニューで「項目の追加/削除」を選択します。Visual Studio 2005 では「項目の選択」を選択します。

   これにより、[ツールボックスのカスタマイズ] (2003) または [ツールボックス項目の選択] (2005) ダイアログボックスが表示されます。

3. [COM コンポーネント] タブを選択します。このタブには、Flash Player ActiveX コントロールなど、そのコンピュータにあるすべての COM コンポーネントが表示されます。
4. スクロールして Shockwave Flash Object を探し、選択します。

   この項目が表示されない場合は、システムに Flash Player ActiveX がインストールされているか確認してください。

ActionScript から ActiveX コンテナへの通信について

外部 API を使用した ActiveX コンテナアプリケーションとの通信は、Web ブラウザとの通信と同様になりますが、大きな違いが 1 つあります。前述したように、ActionScript が Web ブラウザと通信する場合、開発者が考慮している限り、関数は直接呼び出されます。関数の呼び出し方法と応答方法の詳細は、プレイヤー間で受け渡しできるようフォーマットされ、ブラウザは認識されません。ただし、外部 API を使用して ActiveX コンテナアプリケーションと通信する場合、Flash Player からはメッセージ（関数呼び出しと戻り値）が特定の XML フォーマットでアプリケーションに送信されます。そして、コンテナアプリケーションからの関数呼び出しと戻り値でもそれと同じ XML フォーマットを使用することが前提となります。ActiveX コンテナアプリケーションの開発者は、適切なフォーマットの関数呼び出しと応答を認識し、作成可能なコードを作成する必要があります。

サンプルの Introvert IM C# には、メッセージのフォーマッティング防止の可能なクラスが含まれていますが、ActionScript 関数の呼び出しおよび ActionScript からの呼び出しの受信時は、標準のデータ型を使用して操作することができます。この機能は ExternalInterfaceProxy クラスを他のヘルパークラスと組み合わせて使用することによって提供され、ExternalInterfaceProxy クラスを任意の .NET プロジェクトで再利用することで外部 API との通信が容易になります。

次のコードは、メインアプリケーションフォーム (AppForm.cs) から引用したもので、ExternalInterfaceProxy クラスを使用して実現された単純な操作を示しています。

public class AppForm : System.Windows.Forms.Form
{
    ...
    private ExternalInterfaceProxy proxy;
    ...
    public AppForm()
    {
        ...
        // Register this app to receive notification when the proxy receives
        // a call from ActionScript.
        proxy = new ExternalInterfaceProxy(IntrovertIMApp);
        proxy.ExternalInterfaceCall += new ExternalInterfaceCallEventHandler(proxy_ExternalInterfaceCall);
        ...
    }
    ...

このアプリケーションでは、proxy という名前の ExternalInterfaceProxy インスタンスを宣言して作成し、ユーザーインターフェイスにある Shockwave Flash ActiveX コントロールへの参照（IntrovertIMApp）を渡します。次に、プロキシの ExternalInterfaceCall イベントを受信するための proxy_ExternalInterfaceCall() メソッドをコードで登録します。このイベントは、Flash Player から関数呼び出しがあったときに ExternalInterfaceProxy クラスによって送出されます。このイベントへのサブスクライブは、C# コードが ActionScript からの関数呼び出しを受信し、応答する方法になっています。

ActionScript から関数呼び出しがあると、ExternalInterfaceProxy インスタンス（proxy）はその呼び出しを受信し、それを XML フォーマットから変換します。そして、プロキシの ExternalInterfaceCall イベントのリスナーとなっているオブジェクトに通知します。AppForm クラスの場合、proxy_ExternalInterfaceCall() メソッドでは次のようにイベントを処理します。

    /// <summary>
    /// Called by the proxy when an ActionScript ExternalInterface call
    /// is made by the SWF
    /// </summary>
    private object proxy_ExternalInterfaceCall(object sender, ExternalInterfaceCallEventArgs e)
    {
        switch (e.FunctionCall.FunctionName)
        {
            case "isReady":
                return isReady();
            case "setSWFIsReady":
                setSWFIsReady();
                return null;
            case "newMessage":
                newMessage((string)e.FunctionCall.Arguments[0]);
                return null;
            case "statusChange":
                statusChange();
                return null;
            default:
                return null;
        }
    }
    ...

このメソッドに、ExternalInterfaceCallEventArgs インスタンス（この例ではインスタンス名は e）を渡します。これにより、このオブジェクトは ExternalInterfaceCall クラスのインスタンスである FunctionCall プロパティを持ちます。

ExternalInterfaceCall インスタンスが、2 つのプロパティを持つ単純な値オブジェクトです。FunctionName プロパティには、ActionScript の ExternalInterface.Call() ステートメントで指定された関数名が格納されています。ActionScript で何らかのパラメータが追加されると、それらのパラメータは ExternalInterfaceCall オブジェクトの Arguments プロパティに格納されます。この例では、イベントを処理するメソッドは単純な switch ステートメントで、交通整理のような役割を果たします。FunctionName プロパティの値（e.FunctionCall.FunctionName）によって、AppForm クラスのどのメソッドが呼び出されたのかを判断します。

前述のコードの switch ステートメントのブランチは、メソッド呼び出しの共通のシナリオ例を示しています。例えば、どのメソッドでも、値を ActionScript に返すか（isReady() メソッド呼び出しなど）、値を返さない場合は null を返す（それ以外のメソッド呼び出しの場合）必要があります。newMessage() メソッド呼び出しでは、ActionScript から渡されたパラメータへのアクセス例を示しています（Arguments 配列の第 1 エレメントであるパラメータ e.FunctionCall.Arguments[0] を渡しています）。

ExternalInterfaceProxy クラスを使用した C# からの ActionScript 関数の呼び出しは、ActionScript からの関数呼び出しの受信よりもはるかに単純です。ActionScript 関数を呼び出すには、次のように、ExternalInterfaceProxy インスタンスの Call() メソッドを使用します。

    /// <summary>
    /// Called when the "Send" button is pressed; the value in the
    /// MessageText text field is passed in as a parameter.
    /// </summary>
    /// <param name="message">The message to send.</param>
    private void sendMessage(string message)
    {
        if (swfReady)
        {
            ...
            // Call the newMessage function in ActionScript.
            proxy.Call("newMessage", message);
        }
    }
    ...
    /// <summary>
    /// Call the ActionScript function to get the current "availability"
    /// status and write it into the text field.
    /// </summary>
    private void updateStatus()
    {
        Status.Text = (string)proxy.Call("getStatus");
    }
    ...
}

この例に示すように、ExternalInterfaceProxy クラスの Call() メソッドは、ActionScript でそれに相当する ExternalInterface.Call() と非常によく似ています。第 1 パラメータはストリングで、呼び出す関数の名前になります。その他のパラメータ (ここには示されていません) も ActionScript 関数に渡されます。ActionScript 関数から値が返された場合、その値は Call() メソッドによって返されます（前述の例を参照）。

ExternalInterfaceProxy クラスの内部

ActiveX コントロールのプロキシラッパーを使用することは必ずしも重要ではなく、独自のプロキシクラス (例えば、別のプログラミング言語や別のプラットフォーム用) を作成することもできます。プロキシの作成についてはここで詳しく説明しませんが、この例におけるプロキシクラスの内部処理を理解することは有益です。

Shockwave Flash ActiveX コントロールの CallFunction() メソッドを使用すると、外部 API を使用して ActiveX コンテナから ActionScript 関数を呼び出すことができます。次の ExternalInterfaceProxy クラスの Call() メソッドの一部は、この例を示しています。

// Call an ActionScript function on the SWF in "_flashControl",
// which is a Shockwave Flash ActiveX control.
string response = _flashControl.CallFunction(request);

このコード部分で、_flashControl は Shockwave Flash ActiveX コントロールです。ActionScript 関数呼び出しは、CallFunction() メソッドを使用して行われます。このメソッドにはパラメータが 1 つあります（この例では request）。このパラメータは、XML フォーマットの命令が格納されたストリングで、呼び出される ActionScript 関数の名前とそのすべてのパラメータが含まれています。ActionScript から返される値はすべて XML フォーマットストリングにエンコードされ、CallFunction() 呼び出しの戻り値として送り返されます。この例では、この XML ストリングを response 変数に格納しています。

ActionScript からの関数呼び出しの受信は、段階的な手順で行われます。ActionScript から関数呼び出しがあると、Shockwave Flash ActiveX コントロールは FlashCall イベントを送出するため、SWF ファイルからの呼び出しを受信するためのクラス (ExternalInterfaceProxy クラスなど) ではそのイベント用のハンドラを定義しておく必要があります。ExternalInterfaceProxy クラスでは、このイベントハンドラ関数の名前は _flashControl_FlashCall() で、クラスコンストラクタ内のイベントを待ち受けるよう登録されています。

private AxShockwaveFlash _flashControl;

public ExternalInterfaceProxy(AxShockwaveFlash flashControl)
{
    _flashControl = flashControl;
    _flashControl.FlashCall += new _IShockwaveFlashEvents_FlashCallEventHandler(_flashControl_FlashCall);
}
...
private void _flashControl_FlashCall(object sender, _IShockwaveFlashEvents_FlashCallEvent e)
{
    // Use the event object's request property ("e.request")
    // to execute some action.
    ...
    // Return a value to ActionScript;
    // the returned value must first be encoded as an XML-formatted string.
    _flashControl.SetReturnValue(encodedResponse);
}

イベントオブジェクト（e）には request プロパティ（e.request）があります。このプロパティは、関数名やパラメータなど、関数呼び出しに関する情報が XML フォーマットで格納されたストリングです。この情報をコンテナで使用すると、実行するコードを判別できます。ExternalInterfaceProxy クラスでは、要求が XML フォーマットから ExternalInterfaceCall オブジェクトに変換され、同じ情報がアクセスしやすい形式で提供されます。ActiveX コントロールの SetReturnValue() メソッドを使用すると、関数の結果を ActionScript の呼び出し側に返すことができます。この場合も、結果のパラメータを、外部 API で使用される XML フォーマットにエンコードする必要があります。

Shockwave Flash ActiveX コントロールをホストするアプリケーションと ActionScript との間の通信では、関数呼び出しおよび値をエンコードするために特定の XML フォーマットが使用されます。Introvert IM C# の例では、アプリケーションフォーム内のコードで、ActionScript との間で受け渡す値を直接操作し、Flash Player で使用される XML フォーマットの詳細を無視していますが、そうしたことが ExternalInterfaceProxy クラスによって可能になります。これを実現するため、ExternalInterfaceProxy クラスでは ExternalInterfaceSerializer クラスのメソッドを使用して、実際に XML メッセージを .NET オブジェクトに変換しています。ExternalInterfaceSerializer クラスには、次の 4 つのパブリックメソッドがあります。

• EncodeInvoke()：引数の関数名と C# ArrayList を適切な XML フォーマットにエンコードします。
• EncodeResult()：結果値を適切な XML フォーマットにエンコードします。
• DecodeInvoke()：ActionScript からの関数呼び出しをデコードします。FlashCall イベントオブジェクトの request プロパティは DecodeInvoke() メソッドに渡され、このメソッドで呼び出しが ExternalInterfaceCall オブジェクトに変換されます。
• DecodeResult()：ActionScript 関数の呼び出しの結果として受信した XML をデコードします。

これらのメソッドは、C# の値を外部 API の XML フォーマットにエンコードし、XML を C# オブジェクトにデコードします。Flash Player で使用される XML フォーマットの詳細については、外部 API の XML フォーマットを参照してください。