De klasse ExternalInterface gebruiken

De eigenschap ExternalInterface.available geeft aan of Flash Player zich in een container bevindt die een externe interface biedt. Als de externe interface beschikbaar is, is deze eigenschap true ; anders is deze false . Voordat u gebruik maakt van andere willekeurige functies uit de klasse ExternalInterface, moet u altijd als volgt controleren of de huidige container communicatie met de externe interface ondersteunt:

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

Met de eigenschap ExternalInterface.objectID kunt u de unieke id van de Flash Player-instantie bepalen (met name het kenmerk id van de tag object in Internet Explorer of het kenmerk name van de tag embed in browsers die gebruik maken van de NPRuntime-interface). Deze unieke id vertegenwoordigt het huidige SWF-document in de browser en kan worden gebruikt als verwijzing naar het SWF-document; bijvoorbeeld wanneer een JavaScript-functie binnen een containerwebpagina wordt aangeroepen. Wanneer de Flash Player-container geen webbrowser is, is deze eigenschap null .

De methode ExternalInterface.call() voert de code uit binnen de containertoepassing. Hiervoor is ten minste één parameter nodig, een tekenreeks met de naam van de functie die vanuit de containertoepassing moet worden aangeroepen. Extra parameters die worden doorgegeven aan de methode ExternalInterface.call() worden doorgegeven aan de container als parameters van de functieaanroep.

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

Wanneer de container een HTML-pagina is, roept deze methode de JavaScript-functie met de opgegeven naam aan, die gedefinieerd moet worden in een element script in de HTML-pagina. De geretourneerde waarde van de JavaScript-functie wordt doorgegeven aan ActionScript.

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

Als de container een andere ActiveX-container is, zorgt deze methode ervoor dat het ActiveX-besturingselement voor Flash Player de gebeurtenis FlashCall verzendt. De opgegeven functienaam en parameters worden door Flash Player met serienummering gecodeerd in een XML-tekenreeks. De container kan deze informatie benaderen in de eigenschap request van het gebeurtenisobject en aan de hand hiervan bepalen hoe deze zijn eigen code uitvoert. Om een waarde naar ActionScript te retourneren, roept de containercode de methode SetReturnValue() van het ActiveX-object aan, waarbij het resultaat (met serienummering gecodeerd in een XML-tekenreeks) als parameter van deze methode wordt doorgegeven. Zie XML-indeling van externe API voor meer informatie over de XML-indeling die voor deze communicatie wordt gebruikt.

Ongeacht of de container een webbrowser of een andere ActiveX-container is: als de aanroep mislukt of als de containermethode geen geretourneerde waarde opgeeft, wordt null geretourneerd. Als de betreffende omgeving behoort tot een beveiligingssandbox waartoe de aanroepcode geen toegang heeft, genereert de methode ExternalInterface.call() een uitzondering SecurityError. U kunt dit omzeilen door in de betreffende omgeving een juiste waarde in te stellen voor allowScriptAccess . Als u bijvoorbeeld de waarde van allowScriptAccess in een HTML-pagina wilt wijzigen, kunt u het juiste kenmerk in de tags object en embed bewerken.

Een container kan alleen ActionScript-code in een functie aanroepen; een container kan verder geen ActionScript-code aanroepen. Als u een ActionScript-functie wilt aanroepen vanuit de containertoepassing, moet u het volgende doen: de functie registreren bij de klasse ExternalInterface en deze vervolgens aanroepen vanuit de code van de container.

Eerst moet u uw ActionScript-functie registreren, om aan te geven dat deze beschikbaar moet zijn voor de container. Voer de methode ExternalInterface.addCallback() als volgt uit:

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

Voor de methode addCallback() zijn twee parameters nodig. De eerste, een functienaam als tekenreeks, is de naam waarmee de functie wordt herkend door de container. De tweede parameter is de daadwerkelijke ActionScript-functie, die wordt uitgevoerd wanneer de container de gedefinieerde functienaam aanroept. Omdat deze namen verschillen, kunt u een functienaam opgeven die wordt gebruikt door de container, ook als de daadwerkelijke ActionScript-functie een andere naam heeft. Dit is met name zinvol als de functienaam onbekend is; bijvoorbeeld als een anonieme functie is opgegeven, of als de aan te roepen functie bij uitvoering wordt bepaald.

Nadat een ActionScript-functie is geregistreerd met de klasse ExternalInterface, kan de container de functie daadwerkelijk aanroepen. De wijze waarop hangt af van het type container. De ActionScript-functie wordt bijvoorbeeld in een JavaScript-code in een webbrowser aangeroepen met behulp van de geregistreerde functienaam, ook al is dit een methode van het Flash Player-browserobject (dat wil zeggen een methode van het JavaScript-object dat de tag object of embed vertegenwoordigt). |Met andere woorden worden er parameters doorgegeven en een resultaat geretourneerd, ook al wordt er een lokale functie aangeroepen.

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

Wanneer u een ActionScript-functie aanroept in een SWF-bestand dat wordt uitgevoerd in een bureaubladtoepassing, moeten de geregistreerde functienaam en mogelijke parameters in serie in een XML-tekenreeks worden gecodeerd. De aanroep wordt in dat geval daadwerkelijk uitgevoerd door de methode CallFunction() van het ActiveX-besturingselement aan te roepen met de XML-tekenreeks als parameter. Zie XML-indeling van externe API voor meer informatie over de XML-indeling die voor deze communicatie wordt gebruikt.

In beide gevallen wordt de geretourneerde waarde van de ActionScript-functie doorgegeven aan de containercode, ofwel rechtstreeks als waarde wanneer de aanroeper een JavaScript-code in een browser is, ofwel gecodeerd met serienummering in een XML-tekenreeks wanneer de aanroeper een ActiveX-container is.

Bij communicatie tussen ActionScript en een toepassing die het ActiveX-besturingselement voor Shockwave Flash host, wordt gebruikgemaakt van een specifieke XML-indeling om functieaanroepen en waarden te coderen. De externe API maakt gebruik van twee onderdelen van de XML-indeling. Een onderdeel vertegenwoordigt functieaanroepen. Een ander onderdeel vertegenwoordigt individuele waarden; deze indeling wordt gebruikt voor parameters in functies en voor geretourneerde waarden voor functies. De XML-indeling voor functieaanroepen wordt gebruikt voor aanroepen naar en vanuit ActionScript. Voor een functieaanroep vanuit ActionScript geeft Flash Player de XML-tekenreeks door aan de container; voor een aanroep vanuit de container verwacht Flash Player dat de containertoepassing een XML-tekenreeks in deze indeling doorgeeft. Het volgende XML-fragment toont een voorbeeld van een functieaanroep in XML-indeling:

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

De hoofdnode is de node invoke . Deze heeft twee kenmerken: name geeft de naam van de aan te roepen functie weer en returntype is altijd xml . Als de functieaanroep parameters bevat, heeft de node invoke een onderliggende node arguments , waarvan de onderliggende nodes de parameterwaarden zijn die zijn opgemaakt volgens de hieronder uitgelegde individuele waardenindeling.

Individuele waarden, waaronder functieparameters en geretourneerde waarden voor functies, maken gebruik van een indelingsprotocol dat behalve de daadwerkelijke waarden ook informatie over het gegevenstype bevat. De volgende tabel bevat ActionScript-klassen en de XML-indeling, die gebruikt wordt om waarden van dit gegevenstype te coderen:

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

Wanneer u met een containertoepassing van ActiveX met de externe API zelf toepassingen maakt, vindt u het wellicht handig om een proxy te schrijven die native functieaanroepen omzet in een XML-indeling met serienummering. Zie In de klasse ExternalInterfaceProxy voor een voorbeeld van een proxyklasse in C#.