ExternalInterface クラスの使用

ExternalInterface.available プロパティは、外部インターフェイス機能を提供するコンテナ内に現在の Flash Player が格納されているかどうかを示します。外部インターフェイスが利用できる場合、このプロパティは true になります。利用できない場合には false になります。 ExternalInterface クラスの他の機能を使用する前に、現在のコンテナにおいて外部インターフェイスによる通信がサポートされているかどうかを、次のようにして必ず確認してください。

if (ExternalInterface.available) 
{ 
    // Perform ExternalInterface method calls here. 
}

ExternalInterface.objectID プロパティを使用すると、Flash Player インスタンスの一意の識別子（特に、Internet Explorer における object タグの id 属性や、NPRuntime インターフェイスを使用するブラウザーにおける embed タグの name 属性）を確認できます。この一意の ID は、ブラウザー内の現在の SWF ドキュメントを表し、SWF ドキュメントを参照する場合に使用できます（コンテナ HTML ページ内の JavaScript 関数の呼び出しなど）。Flash Player コンテナが Web ブラウザーではない場合、このプロパティは null になります。

ExternalInterface.call() メソッドでは、コンテナアプリケーション内のコードが実行されます。パラメーターは最低 1 つ必要で、コンテナアプリケーション内で呼び出される関数の名前を含んだストリングを指定します。 ExternalInterface.call() メソッドに渡された追加パラメーターは、関数呼び出しのパラメーターとしてコンテナに渡されます。

// calls the external function "addNumbers" 
// passing two parameters, and assigning that function's result 
// to the variable "result" 
var param1:uint = 3; 
var param2:uint = 7; 
var result:uint = ExternalInterface.call("addNumbers", param1, param2);

コンテナが HTML ページの場合は、指定された名前の JavaScript 関数がこのメソッドによって呼び出されます。この名前は、格納された HTML ページの script エレメントで定義されている必要があります。JavaScript 関数の戻り値は ActionScript に返されます。

<script language="JavaScript"> 
    // adds two numbers, and sends the result back to ActionScript 
    function addNumbers(num1, num2) 
    { 
        return (num1 + num2); 
    } 
</script>

コンテナがその他の ActiveX コンテナの場合は、このメソッドによって Flash Player ActiveX コントロールから FlashCall イベントが送出されます。指定された関数名とパラメーターは、Flash Player によって直列化されて XML ストリングになります。 コンテナは、イベントオブジェクトの request プロパティでその情報にアクセスし、それを使用して自身のコードの実行方法を判定できます。値を ActionScript に返すには、コンテナコードで ActiveX オブジェクトの SetReturnValue() メソッドを呼び出し、その結果（シリアル化された XML ストリング）をメソッドのパラメーターとして渡します。この通信で使用される XML フォーマットについて詳しくは、 External API の XML フォーマット を参照してください。

コンテナが Web ブラウザーでも、その他の ActiveX コンテナでも、呼び出しが失敗した場合やコンテナ側のメソッドが戻り値を返さなかった場合は、 null が返されます。呼び出し側コードによるアクセスが、コンテナ環境の属するセキュリティ Sandbox によって許可されていない場合、 ExternalInterface.call() メソッドは SecurityError 例外をスローします。この問題を回避するには、コンテナ環境の allowScriptAccess に適切な値を設定します。例えば、HTML ページの allowScriptAccess の値を変更するには、 object および embed タグの該当する属性を編集します。

コンテナが呼び出すことができるのは、関数内の ActionScript コードのみです。それ以外の ActionScript コードは、コンテナから呼び出すことはできません。コンテナアプリケーションから ActionScript 関数を呼び出すには、ExternalInterface クラスへの関数の登録と、コンテナコードからの関数の呼び出しという、2 つの処理が必要になります。

最初に、ActionScript 関数を登録し、コンテナから使用可能にすることを示す必要があります。 ExternalInterface.addCallback() メソッドを次のように使用します。

function callMe(name:String):String 
{ 
    return "busy signal"; 
} 
ExternalInterface.addCallback("myFunction", callMe);

addCallback() メソッドには 2 つのパラメーターがあります。1 つはストリングの関数名で、コンテナはその名前で関数を認識します。 もう 1 つのパラメーターは実際の ActionScript 関数で、定義された関数名をコンテナが呼び出すと実行されます。 これらの名前は区別されるため、実際の ActionScript 関数が異なる名前であっても、コンテナで使用される関数名を指定できます。 これは、匿名関数が指定された場合や、呼び出される関数が実行時に決定される場合など、関数名が不明な場合に非常に便利です。

ActionScript 関数が ExternalInterface クラスに登録されると、コンテナが実際に関数を呼び出せるようになります。 その方法は、コンテナのタイプによって異なります。 例えば、Web ブラウザーの JavaScript コードの場合、登録された関数名をまるで Flash Player ブラウザーオブジェクトのメソッド（ object または embed タグを表す JavaScript オブジェクトのメソッド）のように使用して ActionScript 関数が呼び出されます。つまり、パラメーターが渡され、呼び出されたローカル関数から結果が返されます。

<script language="JavaScript"> 
    // callResult gets the value "busy signal" 
    var callResult = flashObject.myFunction("my name"); 
</script> 
... 
<object id="flashObject"...> 
    ... 
    <embed name="flashObject".../> 
</object>

あるいは、デスクトップアプリケーションで実行されている SWF ファイルの ActionScript 関数を呼び出す場合、登録された関数名とすべてのパラメーターを直列化して XML フォーマットストリングにする必要があります。 その後、ActiveX コントロールの CallFunction() メソッドとパラメーターとして XML ストリングを呼び出すことで、呼び出しが実際に実行されます。この通信で使用される XML フォーマットについて詳しくは、 External API の XML フォーマット を参照してください。

いずれの場合も、ActionScript 関数の戻り値はコンテナコードに返されますが、呼び出し側がブラウザーの JavaScript コードの場合は値として直接返され、呼び出し側が ActiveX コンテナの場合は XML フォーマットストリングとして直列化して返されます。

Shockwave Flash ActiveX コントロールをホストするアプリケーションと ActionScript 間の通信では、関数呼び出しと値をエンコードする際に専用の XML フォーマットが使用されます。 External API で使用される XML フォーマットには 2 つの部分があります。 1 つのフォーマットは、関数呼び出しを表すために使用されます。 もう 1 つのフォーマットは個々の値を表しています。このフォーマットは、関数のパラメーターおよび関数の戻り値に使用されます。 関数呼び出し用の XML フォーマットは、ActionScript との間の呼び出しに使用されます。 ActionScript からの関数呼び出しに対して、Flash Player は XML をコンテナに渡します。コンテナからの呼び出しに対しては、Flash Player はこのフォーマットで XML ストリングを渡すコンテナアプリケーションが必要になります。 次の XML は、XML フォーマットされた関数呼び出しの例を示しています。

<invoke name="functionName" returntype="xml"> 
    <arguments> 
        ... (individual argument values) 
    </arguments> 
</invoke>

ルートノードは invoke ノードです。 name は関数呼び出しの名前を表し、 returntype は常に xml になります。関数呼び出しにパラメーターが含まれている場合、 invoke ノードには arguments 子ノードができます。さらにその子ノードは、次に説明する個別の値フォーマットを使用してフォーマットされたパラメーター値になります。

関数のパラメーターや関数の戻り値などの個々の値では、実際の値に加えてデータ型情報を含んだフォーマッティングスキームが使用されます。 次の表に、ActionScript クラス、およびそのデータ型の値のエンコードに使用する XML フォーマットの一覧を示します。

<number>27.5</number> 
<number>-12</number>

<array> 
    <property id="0"> 
        <number>27.5</number> 
    </property> 
    <property id="1"> 
        <string>Hello there!</string> 
    </property> 
    ... 
</array>

<object> 
    <property id="name"> 
        <string>John Doe</string> 
    </property> 
    <property id="age"> 
        <string>33</string> 
    </property> 
    ... 
</object>

<null/> or  
<object></object>

External API と ActiveX コンテナアプリケーションを使用して独自のアプリケーションを構築している場合は、ネイティブ関数の呼び出しを直列化 XML 形式に変換できるプロキシを作成すると便利です。C# で記述されたプロキシクラスの例については、ExternalInterfaceProxy クラスの内部を参照してください。