Korzystanie z klasy ExternalInterface

Właściwość ExternalInterface.available określa, czy bieżąca instancja programu Flash Player jest kontenerem, który oferuje interfejs zewnętrzny. Jeśli interfejs zewnętrzny jest dostępny, ta właściwość ma wartość true ; w przeciwnym razie ma wartość false . Przed wykorzystaniem innych możliwości klasy ExternalInterface należy upewnić się, że bieżący kontener obsługuje komunikację z interfejsem zewnętrznym:

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

Właściwość ExternalInterface.objectID umożliwia określenie unikalnego identyfikatora instancji Flash Player (atrybut id znacznika object w programie Internet Explorer lub atrybut name znacznika embed w przeglądarkach korzystających z interfejsu NPRuntime). Ten unikalny identyfikator reprezentuje bieżący dokument SWF w przeglądarce i może służyć do utworzenia odwołania do dokumentu SWF — na przykład w przypadku wywołania funkcji JavaScript na stronie HTML kontenera. Jeśli kontener Flash Player nie jest przeglądarką sieci Web, ta właściwość ma wartość null .

Metoda ExternalInterface.call() wykonuje kod w aplikacji kontenera. Wymaga wywołania co najmniej jednego parametru — ciągu znaków zawierającego nazwę funkcji, która ma zostać wywołana w aplikacji kontenera. Wszystkie pozostałe parametry wprowadzane do metody ExternalInterface.call() są wprowadzane wraz z kontenerem jako parametry wywołania funkcji.

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

Jeśli kontener jest stroną HTML, ta metoda wywołuje funkcję JavaScript z określoną nazwą, którą należy zdefiniować w elemencie script w zawierającej stronie HTML. Wartość zwracana funkcji JavaScript function jest przekazywana z powrotem do kodu ActionScript.

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

Jeśli kontener jest innym kontenerem ActiveX, ta metoda sprawia, że formant Flash Player ActiveX wywołuje własne zdarzenie FlashCall . Określona nazwa funkcji i parametry są serializowane w ciąg XML przez program Flash Player. Kontener może uzyskać dostęp do tych informacji we właściwości request obiektu zdarzenia, a następnie wykorzystać je w celu określenia sposobu wykonania własnego kodu. W celu zwrócenia wartości do kodu ActionScript kod kontenera wywołuje metodę SetReturnValue() obiektu ActiveX, przekazując wynik (serializowany do ciągu XML) jako parametr metody. Więcej informacji o formacie XML używanym dla komunikacji zawiera sekcja Format XML zewnętrznego interfejsu API .

Niezależnie od tego, czy kontener jest przeglądarką sieci Web lub innym kontenerem ActiveX — jeśli wywołanie nie powiedzie się lub jeśli metoda kontenera nie określa wartości zwracanej, zwracana jest wartość null . Metoda ExternalInterface.call() zgłasza wyjątek SecurityError, jeśli środowisko zawierające należy do bezpiecznego obszaru izolowanego, do którego kod wywołujący nie ma dostępu. Aby obejść to ograniczenie, należy ustawić odpowiednią wartość dla allowScriptAccess w środowisku zawierającym. Na przykład: aby zmienić wartość allowScriptAccess na stronie HTML, należy zmodyfikować odpowiedni atrybut w znacznikach object i embed .

Kontener może wywołać tylko kod ActionScript, który znajduje się w funkcji — żaden inny kod ActionScript nie może być wywoływany przez kontener. W celu wywołania funkcji ActionScript z aplikacji kontenera należy wykonać dwie czynności: zarejestrować funkcję w klasie ExternalInterface, a następnie wywołać ją z kodu kontenera.

Najpierw należy zarejestrować funkcję ActionScript w celu wskazania, że powinna zostać udostępniona dla kontenera. Należy użyć metody ExternalInterface.addCallback() w następujący sposób:

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

Metoda addCallback() przyjmuje dwa parametry. Pierwszy, nazwa funkcji (w tym przypadku String), to nazwa, pod jaką funkcja będzie znana kontenerowi. Drugi parametr jest rzeczywistą funkcją ActionScript, która zostanie wykonana, gdy kontener wywoła zdefiniowaną nazwę funkcji. Nazwy są rozróżniane, dlatego możliwe jest określenie nazwy funkcji, która zostanie wykorzystana przez kontener, nawet jeśli rzeczywista funkcja ActionScript ma inną nazwę. Jest to szczególnie użyteczne wówczas, gdy nazwa funkcji nie jest znana — np. w przypadku określenia funkcji anonimowej lub gdy funkcja, która zostanie wywołana, jest wybierana w czasie wykonywania.

Gdy funkcja ActionScript zostanie zarejestrowana w klasie ExternalInterface, kontener może wywołać tę funkcję. Sposób, w jaki to się odbywa, jest uzależniony od typu kontenera. Na przykład: w kodzie JavaScript, w przeglądarce sieci Web, funkcja ActionScript jest wywoływana przy użyciu zarejestrowanej nazwy funkcji, tak jakby była to metoda obiektu przeglądarki programu Flash Player (tj. metoda obiektu JavaScript reprezentującego znacznik object lub embed ). Innymi słowy: parametry są przekazywane, a wynik jest zwracany w taki sposób, jakby wywoływana była funkcja lokalna.

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

I odwrotnie — w przypadku wywołania funkcji ActionScript w pliku SWF działającym w aplikacji pulpitu nazwę zarejestrowanej funkcji i wszystkie parametry należy serializować, tworząc ciąg znaków w formacie XML. Następnie w celu wywołania funkcji należy wywołać metodę CallFunction() formantu ActiveX, wykorzystując ciąg znaków XML jako parametr. Więcej informacji o formacie XML używanym do komunikacji zawiera sekcja Format XML zewnętrznego interfejsu API .

W każdym z tych przypadków wartość zwracana funkcji ActionScript jest przekazywana z powrotem do kodu kontenera — bezpośrednio jako wartość, gdy obiektem wywołującym jest kod JavaScript w przeglądarce lub w postaci serializowanej jako ciąg znaków w formacie XML, jeśli obiektem wywołującym jest formant ActiveX.

W komunikacji między językiem ActionScript oraz aplikacją obsługującą formant Shockwave Flash ActiveX wykorzystywany jest konkretny format w celu kodowania wywołań i wartości funkcji. Zewnętrzny interfejs API korzysta dwuczęściowego formatu XML. Jeden format jest używany do reprezentowania wywołań funkcji. Drugi format służy do reprezentowania poszczególnych wartości; ten format jest używany dla parametrów w funkcjach, a także jako wartości zwracane funkcji. Format XML dla wywołań funkcji jest używany dla wywołań do i z kodu ActionScript. W przypadku wywołania funkcji z ActionScript program Flash Player przekazuje ciąg znaków XML do kontenera; w przypadku wywołania z kontenera program Flash Player oczekuje, że aplikacja kontenera przekaże do niego ciąg znaków XML w tym formacie. Poniższy fragment XML przedstawia przykładowe wywołanie funkcji w formacie XML:

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

Węzłem głównym jest węzeł invoke . Zawiera dwa atrybuty: name wskazuje nazwę funkcji do wywołania, a returntype ma zawsze wartość xml . Jeśli wywołanie funkcji zawiera parametry, wówczas węzeł invoke zawiera podrzędny węzeł arguments , którego węzły podrzędne będą wartościami parametrów sformatowanymi za pomocą formatu osobnych wartości, który opisano poniżej.

Osobne wartości, między innymi parametry funkcji i wartości zwracane funkcji, korzystają ze schematu formatowania, który zawiera informacje o typie danych, a także rzeczywiste wartości. W poniższej tabeli przedstawiono klasy ActionScript oraz format XML używany do kodowania wartości typów danych:

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

Podczas tworzenia własnych aplikacji za pomocą zewnętrznego interfejsu API w aplikacji kontenera ActiveX pewnym udogodnieniem może być napisanie proxy, które wykona zadanie przekształcenia rodzimych wywołań funkcji na serializowany format XML. Przykład klasy proxy napisanej w języku C# zawiera sekcja W klasie ExternalInterfaceProxy.