Använda klassen ExternalInterface

Egenskapen ExternalInterface.available anger om Flash Player är i en behållare som har ett externt gränssnitt. Om det externa gränssnittet är tillgängligt är egenskapen true. Annars är den false. Innan du använder några andra funktioner i klassen ExternalInterface måste du kontrollera att den aktuella behållaren stöder extern gränssnittskommunikation på följande sätt:

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

Med egenskapen ExternalInterface.objectID kan du avgöra Flash Player-instansens unika identifierare (id-attributet för object-taggen i Internet Explorer eller name-attributet för embed-taggen i webbläsare som använder NPRuntime-gränssnittet). Detta unika ID representerar det SWF-dokument som är i webbläsaren och kan användas för att referera till SWF-dokumentet, till exempel vid anrop till en JavaScript-funktion i en HTML-behållarsida. När Flash Player-behållaren inte är en webbsida är egenskapen null.

Metoden ExternalInterface.call() kör kod i behållarprogrammet. Den måste ha minst en parameter, en sträng som innehåller namnet på den funktion som ska anropas i behållarprogrammet. Eventuella ytterligare parametrar som skickas till metoden ExternalInterface.call() skickas vidare till behållaren som parametrar för funktionsanropet.

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

Om behållaren är en HTML-sida aktiverar metoden JavaScript-funktionen med det angivna namnet, som måste definieras i ett script-element i HTML-behållarsidan. Returvärdet för JavaScript-funktionen skickas tillbaka till ActionScript.

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

Om behållaren är någon annan ActiveX-behållare gör metoden att Flash Player ActiveX-kontrollen skickar händelsen FlashCall. Det angivna funktionsnamnet och eventuella parametrar serialiseras till en XML-sträng av Flash Player. Behållaren har åtkomst till informationen i egenskapen request för händelseobjektet och kan använda den för att avgöra hur den egna koden ska köras. För att returnera ett värde till ActionScript anropar behållarens kod ActiveX-objektets SetReturnValue()-metod och skickar resultatet (serialiserat till en XML-sträng) som en parameter för den metoden. Mer information om det XML-format som används för den här kommunikationen finns i Det externa API:ts XML-format.

Oavsett om behållaren är en webbläsare eller en annan ActiveX-behållare returneras null om anropet misslyckas eller om behållarens metod inte anger ett returvärde. Metoden ExternalInterface.call() ger ett SecurityError-undantag om behållarmiljön tillhör en säkerhetssandlåda som den anropande koden inte har tillgång till. Du kan undvika detta genom att ställa in ett lämpligt värde för allowScriptAccess i behållarmiljön. För att ändra värdet för allowScriptAccess i en HTML-sida redigerar du motsvarande attribut i taggarna object och embed.

En behållare kan bara anropa ActionScript-kod som är i en funktion. Ingen annan ActionScript-kod kan anropas av en behållare. För att kunna anropa en ActionScript-funktion från behållarprogrammet måste du göra två saker: registrera funktionen med klassen ExternalInterface och sedan anropa den från behållarens kod.

Först måste du registrera ActionScript-funktionen för att ange att den ska vara tillgänglig för behållaren. Använd metoden ExternalInterface.addCallback() på följande sätt:

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

Metoden addCallback() används med två parametrar. Den första, som är ett funktionsnamn i form av en sträng, är namnet som kommer att användas för funktionen i behållaren. Den andra parametern är den faktiska ActionScript-funktion som körs när behållaren anropar det definierade funktionsnamnet. Eftersom namnen är åtskilda kan du ange ett funktionsnamn som ska användas i behållaren även om ActionScript-funktionen har ett annat namn. Det är särskilt användbart om funktionsnamnet är okänt, till exempel om en anonym funktion anges eller om det inte avgörs förrän under körning vilken funktion som ska anropas.

När en ActionScript-funktion har registrerats i klassen ExternalInterface kan behållaren anropa den. Hur detta görs varierar beroende på behållartypen. I JavaScript-kod i en webbläsare anropas till exempel ActionScript-funktionen med det registrerade funktionsnamnet som om det vore en metod i Flash Player-objektet i webbläsaren (d.v.s. en metod i JavaScript-objektet som representerar object- eller embed-taggen). Med andra ord skickas parametrar och resultatet returneras som om en lokal funktion hade anropats.

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

När en ActionScript-funktion anropas i en SWF-fil som körs i ett skrivbordsprogram måste det registrerade funktionsnamnet och alla parametrar serialiseras i en XML-formaterad sträng. Anropet utförs sedan genom att metoden CallFunction() i ActiveX-kontrollen anropas med XML-strängen som parameter. Mer information om det XML-format som används för den här kommunikationen finns i Det externa API:ts XML-format.

I båda fallen skickas ActionScript-funktionens returvärde tillbaka till behållarkoden, antingen direkt som ett värde när anroparen är JavaScript-kod i en webbläsare eller serialiserad som en XML-formaterad sträng när anroparen är en ActiveX-behållare.

För kommunikation mellan ActionScript och ett program med Shockwave Flash ActiveX-kontrollen används ett specifikt XML-format för att koda funktionsanrop och värden. XML-formatet som används av det externa API:t har två delar. Ett format används för att representera funktionsanrop. Ett annat format används för att representera enskilda värden. Det formatet används både för parametrar i funktioner och för funktionernas returvärden. XML-formatet för funktionsanrop används för anrop till och från ActionScript. För ett funktionsanrop från ActionScript skickar Flash Player XML-strängen till behållaren. För ett anrop från behållaren förväntar sig Flash Player att behållarprogrammet ska skicka en XML-sträng i det här formatet. I följande XML-fragment visas ett exempel på ett XML-formaterat funktionsanrop:

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

Rotnoden kallas invoke-nod. Den har två attribut: name anger namnet på funktionen som ska anropas och returntype är alltid xml. Om funktionsanropet innehåller parametrar har invoke-noden en underordnad arguments-nod vars underordnade noder är de parametervärden som formaterats med det enskilda värdeformatet som förklaras härnäst.

För enskilda värden, inklusive funktionens parametrar och funktionens returvärden, använder du ett formateringsschema som förutom de faktiska värdena innehåller datatypsinformation. I följande tabell listas ActionScript-klasser och det XML-format som används för att koda värden som tillhör den datatypen:

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

När du skapar egna program med det externa API:t med ett ActiveX-behållarprogram är det antagligen praktiskt att skriva en proxy som utför konverteringen av programspecifika funktionsanrop till det serialiserade XML-formatet. Ett exempel på en proxyklass skriven i C# finns i Inuti klassen ExternalInterfaceProxy.