Verwenden der ExternalInterface-Klasse

Die ExternalInterface.available -Eigenschaft gibt an, ob der aktuelle Flash Player in einem Container ausgeführt wird, der über eine externe Schnittstelle verfügt. Wenn die externe Schnittstelle zur Verfügung steht, lautet der Wert dieser Eigenschaft true , ansonsten false . Vor dem Einsatz weiterer Funktionen der ExternalInterface-Klasse sollten Sie stets mithilfe der folgenden Vorgehensweise sicherstellen, dass der aktuelle Container die externe Schnittstellenkommunikation unterstützt:

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

Mit der ExternalInterface.objectID -Eigenschaft können Sie die eindeutige ID der Flash Player-Instanz ermitteln (d. h. das id -Attribut des object -Tags in Internet Explorer oder das name -Attribut des embed -Tags in Browsern mit der NPRuntime-Schnittstelle). Diese eindeutige ID gibt das aktuelle SWF-Dokument im Browser an und kann für Verweise auf das SWF-Dokument verwendet werden, beispielsweise beim Aufrufen einer JavaScript-Funktion in einer Container-HTML-Seite. Wenn der Flash Player-Container kein Webbrowser ist, hat diese Eigenschaft den Wert null .

Mit der ExternalInterface.call() -Methode wird Code in der Containeranwendung ausgeführt. Sie erfordert mindestens einen Parameter: einen String mit dem Namen der in der Containeranwendung aufzurufenden Funktion. Alle weiteren an die ExternalInterface.call() -Methode übergebenen Parameter werden als Parameter des Funktionsaufrufs an den Container weitergeleitet.

// 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);

Wenn der Container eine HTML-Seite ist, ruft diese Methode die JavaScript-Funktion mit dem angegebenen Namen auf, die in einem script -Element der HTML-Seite definiert sein muss. Der Rückgabewert der JavaScript-Funktion wird an ActionScript zurückgegeben.

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

Wenn der Container ein anderer ActiveX-Container ist, bewirkt diese Methode, dass das Flash Player-ActiveX-Steuerelement das zugehörige FlashCall -Ereignis sendet. Der angegebene Funktionsname und alle Parameter werden in Flash Player in einen XML-String serialisiert. Der Container kann auf diese Informationen über die request -Eigenschaft des Ereignisobjekts zugreifen und so ermitteln, in welcher Form der Code ausgeführt werden soll. Für die Rückgabe eines Wertes an ActionScript wird mit dem Containercode die SetReturnValue() -Methode des ActiveX-Objekts aufgerufen und der Ergebniswert (in einen XML-String serialisiert) als Parameter dieser Methode übergeben. Weitere Informationen zum für diese Kommunikation verwendeten XML-Format finden Sie unter XML-Format der externen API .

Unabhängig davon, ob der Container ein Webbrowser oder ein anderer ActiveX-Container ist, wird null zurückgegeben, wenn der Aufruf fehlschlägt oder die Containermethode keinen Rückgabewert festlegt. Die ExternalInterface.call() -Methode löst eine SecurityError-Ausnahme aus, wenn die Containerumgebung einer Sicherheits-Sandbox angehört, auf die der aufrufende Code keinen Zugriff hat. Sie können dies vermeiden, indem Sie in der Containerumgebung einen entsprechenden Wert für allowScriptAccess festlegen. Zum Ändern des Wertes von allowScriptAccess in einer HTML-Seite müssen Sie beispielsweise das entsprechende Attribut im object -Tag und im embed -Tag bearbeiten.

Ein Container kann nur ActionScript-Code aufrufen, der sich innerhalb einer Funktion befindet. Anderer ActionScript-Code steht für Container nicht zur Verfügung. Um eine ActionScript-Funktion über die Containeranwendung aufzurufen, müssen Sie zwei Dinge tun: Registrieren der Funktion in der ExternalInterface-Klasse und anschließend Aufrufen der Klasse über den Containercode.

Zunächst müssen Sie die ActionScript-Funktion registrieren, um anzugeben, dass sie für die Containeranwendung zur Verfügung steht. Verwenden Sie die ExternalInterface.addCallback() -Methode wie folgt:

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

Für die addCallback() -Methode sind zwei Parameter erforderlich. Der erste ist ein String mit dem Funktionsnamen, unter dem die Funktion im Container bekannt ist. Der zweite Parameter ist die eigentliche ActionScript-Funktion, die ausgeführt wird, wenn im Container der definierte Funktionsname aufgerufen wird. Da diese Namen voneinander unabhängig sind, können Sie zur Verwendung für den Container einen Funktionsnamen angeben, der vom eigentlichen Namen der ActionScript-Funktion abweicht. Dies ist besonders hilfreich, wenn der Funktionsname unbekannt ist, beispielsweise wenn eine anonyme Funktion angegeben oder die aufzurufende Funktion zur Laufzeit festgelegt wird.

Nachdem eine ActionScript-Funktion bei der ExternalInterface-Klasse registriert wurde, ist sie aus dem Container aufrufbar. Die Vorgehensweise zum Aufrufen hängt vom Containertyp ab. Beispielsweise werden ActionScript-Funktionen aus JavaScript-Code in einem Webbrowser mithilfe des registrierten Funktionsnamens aufgerufen, als wären sie Methoden des Flash Player-Browserobjekts (d. h. Methoden des JavaScript-Objekts, das das Tag object oder embed repräsentiert). Das bedeutet, dass Parameter übergeben werden und ein Rückgabewert zurückgegeben wird, wie dies beim Aufrufen einer lokalen Funktion der Fall wäre.

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

Im Gegensatz dazu müssen beim Aufrufen einer ActionScript-Funktion in einer SWF-Datei, die in einer Desktopanwendung ausgeführt wird, der registrierte Funktionsname und alle Parameter in einen XML-formatierten String serialisiert werden. Der eigentliche Aufruf erfolgt dann durch Aufrufen der CallFunction() -Methode des ActiveX-Steuerelements mit dem XML-String als Parameter. Weitere Informationen zum für diese Kommunikation verwendeten XML-Format finden Sie unter XML-Format der externen API .

In beiden Fällen wird der Rückgabewert der ActionScript-Funktion an den Containercode zurückgegeben, entweder direkt als Wert (beim Aufruf aus JavaScript-Code in einem Browser) oder serialisiert als XML-formatierter String (beim Aufruf aus einem ActiveX-Container).

Bei der Kommunikation zwischen ActionScript und einer Anwendung, in der ein Shockwave Flash-ActiveX-Steuerelement ausgeführt wird, wird zum Kodieren der Funktionsaufrufe und Rückgabewerte ein spezielles XML-Format verwendet. Es liegen zwei Formen des in der externen API verwendeten XML-Formats vor. Das eine Format wird zum Darstellen von Funktionsaufrufen verwendet. Das andere dient zum Abbilden einzelner Werte. Es wird für Funktionsparameter sowie für Rückgabewerte von Funktionen verwendet. Das XML-Format für Funktionsaufrufe wird für Aufrufe zwischen ActionScript und dem ActiveX-Steuerelement verwendet. Bei einem Funktionsaufruf aus ActionScript wird der XML-String in Flash Player an den Container übergeben. Bei einem Aufruf aus dem Container erwartet Flash Player einen XML-String in diesem Format. Im folgenden XML-Fragment ist ein Beispiel für einen XML-formatierten Funktionsaufruf dargestellt:

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

Der Stammknoten ist der invoke -Knoten. Er hat zwei Attribute: name gibt den Namen der aufzurufenden Funktion an. returntype hat immer den Wert xml . Wenn der Funktionsaufruf Parameter enthält, hat der invoke -Knoten einen untergeordneten arguments -Knoten, dessen untergeordnete Knoten wiederum die Parameterwerte sind. Je nach Wert sind diese individuell formatiert, wie im Folgenden dargestellt ist.

Bei individuellen Werten einschließlich Funktionsnamen und Rückgabewerten wird ein Formatierungsschema verwendet, das zusätzlich zu den eigentlichen Werten auch eine Datentypangabe enthält. In der folgenden Tabelle sind ActionScript-Klassen und das XML-Format aufgeführt, das zum Kodieren der Werte für den jeweiligen Datentyp verwendet wird:

<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>

Wenn Sie Anwendungen mithilfe der externen API und einem ActiveX-Container erstellen, ist es möglicherweise hilfreich, eine Proxy-Klasse zu programmieren, mit der die jeweiligen Funktionsaufrufe in das serialisierte XML-Format konvertiert werden. Ein Beispiel einer in C# geschriebeben Proxy-Klasse finden Sie unter Details der ExternalInterfaceProxy-Klasse.