Uso della classe ExternalInterface

La proprietà ExternalInterface.available indica se la versione corrente di Flash Player si trova in un contenitore dotato di interfaccia esterna. Se l'interfaccia esterna è disponibile, questa proprietà è true ; in caso contrario, è false . Prima di utilizzare qualunque altra funzionalità della classe ExternalInterface, verificate sempre che il contenitore corrente supporti la comunicazione con l'interfaccia esterna nel modo seguente:

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

La proprietà ExternalInterface.objectID consente di determinare l'identificatore univoco per l'istanza di Flash Player (nello specifico, l'attributo id del tag object in Internet Explorer o l'attributo name del tag embed nei browser che utilizzano l'interfaccia NPRuntime). Questo identificatore univoco rappresenta il documento SWF corrente nel browser e può essere utilizzato per fare riferimento al documento SWF (ad esempio, quando si chiama una funzione JavaScript in una pagina HTML contenitore). Quando il contenitore di Flash Player non è un browser Web, questa proprietà è null .

Il metodo ExternalInterface.call() esegue il codice nell'applicazione contenitore. Richiede almeno un parametro, ovvero una stringa che contiene il nome della funzione da chiamare nell'applicazione contenitore. Tutti gli eventuali parametri aggiuntivi passati al metodo ExternalInterface.call() vengono passati al contenitore come parametri della chiamata alla funzione.

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

Se il contenitore è una pagina HTML, questo metodo chiama la funzione JavaScript con il nome specificato, che deve essere definita in un elemento script presente nella pagina HTML contenitore. Il valore restituito dalla funzione JavaScript viene ripassato ad ActionScript.

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

Se il contenitore è un altro contenitore ActiveX, questo metodo fa in modo che il controllo ActiveX di Flash Player invii il proprio evento FlashCall . Il nome di funzione specificato e tutti gli eventuali parametri vengono serializzati in una stringa XML da Flash Player. Il contenitore può accedere a queste informazioni nella proprietà request dell'oggetto evento e utilizzarle per determinare come eseguire il proprio codice. Per restituire un valore ad ActionScript, il codice del contenitore chiama il metodo SetReturnValue() dell'oggetto ActiveX, passando il risultato (serializzato in una stringa XML) come parametro di tale metodo. Per ulteriori informazioni sul formato XML utilizzato per questa comunicazione, vedete la sezione Il formato XML dell'API esterna .

Se il contenitore è un browser Web o un altro contenitore ActiveX, se la chiamata non riesce o se il metodo container non specifica un valore da restituire, viene restituito null . Il metodo ExternalInterface.call() genera un'eccezione SecurityError se l'ambiente contenitore appartiene a una funzione di sicurezza sandbox a cui il codice chiamante non ha accesso. Per ovviare a questo inconveniente, potete impostare un valore adeguato per allowScriptAccess nell'ambiente contenitore. Per modificare, ad esempio, il valore di allowScriptAccess in una pagina HTML, potete modificare l'attributo appropriato nei tag object ed embed .

Un contenitore può chiamare esclusivamente il codice ActionScript presente in una funzione. Per chiamare una funzione ActionScript dall'applicazione contenitore, è necessario eseguire due operazioni: registrare la funzione con la classe ExternalInterface, quindi chiamarla dal codice del contenitore.

Come prima cosa, è necessario registrare la funzione ActionScript per indicare che deve essere resa disponibile al contenitore. Utilizzate il metodo ExternalInterface.addCallback() nel modo indicato di seguito:

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

Il metodo addCallback() accetta due parametri: il primo, un nome di funzione quale una stringa, è il nome con cui la funzione sarà conosciuta dal contenitore. Il secondo parametro è la funzione ActionScript vera e propria che verrà eseguita quando il contenitore chiama il nome di funzione definito. Dal momento che questi nomi sono distinti, potete specificare un nome di una funzione che verrà utilizzata dal contenitore, anche se l'effettiva funzione ActionScript ha un nome diverso. Si tratta di una possibilità particolarmente utile se non si conosce il nome della funzione (ad esempio, se viene specificata una funzione anonima o se la funzione da chiamare viene determinata in fase di runtime).

Una volta che una funzione ActionScript è stata registrata con la classe ExternalInterface, il contenitore può chiamarla. Ciò può avvenire in diversi modi, a seconda del tipo di contenitore. Nel codice JavaScript in un browser Web, ad esempio, la funzione ActionScript viene chiamata utilizzando il nome della funzione registrata come se si trattasse di un metodo dell'oggetto browser Flash Player (ovvero, un metodo dell'oggetto JavaScript che rappresenta il tag object o embed ). In altre parole, vengono passati i parametri e viene restituito un risultato come se venisse chiamata una funzione locale.

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

In alternativa, quando chiamate una funzione ActionScript in un file SWF in esecuzione in un'applicazione desktop, il nome della funzione registrata e tutti gli eventuali parametri devono essere serializzati in una stringa in formato XML. Quindi, la chiamata viene eseguita realmente chiamando il metodo CallFunction() del controllo ActiveX con la stringa XML come parametro. Per ulteriori informazioni sul formato XML utilizzato per questa comunicazione, vedete la sezione Il formato XML dell'API esterna .

In entrambi i casi, il valore restituito dalla funzione ActionScript viene ripassato al codice del contenitore, sia direttamente sotto forma di valore quando il chiamante è il codice JavaScript in un browser sia serializzato come stringa in formato XML quando il chiamante è un contenitore ActiveX.

La comunicazione tra ActionScript e un'applicazione che contiene il controllo ActiveX di Shockwave Flash utilizza un formato XML specifico per codificare le chiamate alle funzioni e i valori. Il formato XML utilizzato dall'API esterna è suddiviso in due parti. Un formato viene utilizzato per rappresentare le chiamate alle funzioni. Un altro viene utilizzato per rappresentare i singoli valori; questo formato viene utilizzato per i parametri nelle funzioni, nonché per i valori restituiti da queste ultime. Il formato XML per le chiamate alle funzioni viene utilizzato per le chiamate verso e da ActionScript. Per una chiamata a una funzione proveniente da ActionScript, Flash Player passa l'XML al contenitore; per una chiamata proveniente dal contenitore, Flash Player prevede che l'applicazione contenitore passi una stringa XML in questo formato. Il frammento XML seguente mostra un esempio di chiamata a una funzione in formato XML:

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

Il nodo radice è il nodo invoke e ha due attributi: name indica il nome della funzione da chiamare, mentre returntype è sempre xml . Se la chiamata alla funzione comprende dei parametri, il nodo invoke ha un nodo arguments secondario, i cui nodi secondari sono costituiti dai valori di parametro formattati utilizzando il formato dei singoli valori illustrato di seguito.

I singoli valori, compresi i parametri della funzione e i valori da essa restituiti, utilizzano uno schema di formattazione che oltre ai valori effettivi include le informazioni sul tipo di dati. L'elenco seguente illustra le classi ActionScript e il formato XML utilizzato per codificare i valori per tale tipo di dati:

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

Quando si creano applicazioni che utilizzano l'API esterna con un'applicazione contenitore ActiveX, probabilmente è più comodo scrivere un proxy che esegua l'operazione di conversione delle chiamate alle funzioni native nel formato XML serializzato. Per un esempio di una classe proxy scritta in C#, vedete Funzionamento della classe ExternalInterfaceProxy.