Esempio di API esterna: comunicazione tra ActionScript e un'applicazione desktop che utilizza il controllo ActiveX

Questa applicazione di esempio rappresenta due programmi client di messaggistica istantanea (uno all'interno di un file SWF e un altro creato con Windows Form) che comunicano l'uno con l'altro. L'interfaccia utente include un'istanza del controllo ActiveX Shockwave Flash, all'interno del quale viene caricato il file SWF che contiene il client IM ActionScript. L'interfaccia include anche diversi campi di testo che compongono il client di messaggistica istantanea (IM) di Windows Forms: un campo per l'immissione dei messaggi (MessageText), un altro che visualizza la trascrizione dei messaggi scambiati tra i client (Transcript) e un terzo (Status) che visualizza lo stato della disponibilità in base all'impostazione specificata nel client IM SWF.

Per includere il controllo ActiveX di Shockwave Flash nell'applicazione Windows Forms, come prima cosa è necessario aggiungerlo alla Casella degli strumenti di Microsoft Visual Studio.

Il funzionamento della comunicazione che utilizza l'API esterna con un'applicazione contenitore ActiveX è uguale alla comunicazione con un browser Web, ma con una differenza importante. Come descritto in precedenza, quando ActionScript comunica con un browser Web, in fase di sviluppo viene specificato che le funzioni vengano chiamate direttamente; i dettagli di come le chiamate e le risposte delle funzioni vengono formattate per essere passate tra il lettore e il browser sono nascosti. Tuttavia, quando si utilizza l'API esterna per comunicare con un'applicazione contenitore ActiveX, Flash Player invia dei messaggi (chiamate a funzioni e valori restituiti) all'applicazione in un formato XML specifico e prevede che le chiamate alle funzioni e i valori restituiti dall'applicazione contenitore utilizzino lo stesso formato XML. Lo sviluppatore dell'applicazione contenitore ActiveX deve scrivere del codice in grado di comprendere e creare le chiamate alle funzioni e le relative risposte in un formato appropriato.

L'esempio dell'applicazione Introvert IM in C# comprende un set di classi che consentono di evitare la formattazione dei messaggi; piuttosto, è possibile lavorare con tipi di dati standard quando si chiamano e ricevono funzioni ActionScript. La classe ExternalInterfaceProxy, insieme ad altre classi di supporto, fornisce questa funzionalità e può essere riutilizzata in qualunque progetto .NET per facilitare la comunicazione dell'API esterna.

Le sezioni di codice seguenti, estratte dal form dell'applicazione principale (AppForm.cs), dimostrano l'interazione semplificata che è possibile ottenere utilizzando la classe ExternalInterfaceProxy:

public class AppForm : System.Windows.Forms.Form 
{ 
    ... 
    private ExternalInterfaceProxy proxy; 
    ... 
    public AppForm() 
    { 
        ... 
        // Register this app to receive notification when the proxy receives 
        // a call from ActionScript. 
        proxy = new ExternalInterfaceProxy(IntrovertIMApp); 
        proxy.ExternalInterfaceCall += new ExternalInterfaceCallEventHandler(proxy_ExternalInterfaceCall); 
        ... 
    } 
    ...

L'applicazione dichiara e crea un'istanza ExternalInterfaceProxy di nome proxy, passando un riferimento al controllo ActiveX di Shockwave Flash presente nell'interfaccia utente (IntrovertIMApp). Quindi, il codice registra il metodo proxy_ExternalInterfaceCall() per ricevere l'evento ExternalInterfaceCall del proxy. Questo evento viene inviato dalla classe ExternalInterfaceProxy quando una chiamata a una funzione proviene da Flash Player. La sottoscrizione a questo evento rappresenta il modo in cui il codice C# riceve le chiamate alle funzioni provenienti da ActionScript e risponde a esse.

Quando una chiamata a una funzione proviene da ActionScript, l'istanza ExternalInterfaceProxy (proxy) riceve la chiamata, la converte dal formato XML e invia una notifica agli oggetti che sono listener dell'evento ExternalInterfaceCall del proxy. Nel caso della classe AppForm, il metodo proxy_ExternalInterfaceCall() gestisce tale evento, come indicato di seguito:

    /// <summary> 
    /// Called by the proxy when an ActionScript ExternalInterface call 
    /// is made by the SWF 
    /// </summary> 
    private object proxy_ExternalInterfaceCall(object sender, ExternalInterfaceCallEventArgs e) 
    { 
        switch (e.FunctionCall.FunctionName) 
        { 
            case "isReady": 
                return isReady(); 
            case "setSWFIsReady": 
                setSWFIsReady(); 
                return null; 
            case "newMessage": 
                newMessage((string)e.FunctionCall.Arguments[0]); 
                return null; 
            case "statusChange": 
                statusChange(); 
                return null; 
            default: 
                return null; 
        } 
    } 
    ...

Al metodo viene passata un'istanza ExternalInterfaceCallEventArgs, che in questo esempio ha il nome e. Tale oggetto, a propria volta, contiene una proprietà FunctionCall che è un'istanza della classe ExternalInterfaceCall.

Un'istanza ExternalInterfaceCall è un oggetto value semplice con due proprietà. La proprietà FunctionName contiene il nome di funzione specificato nell'istruzione ActionScript ExternalInterface.Call(). Se in ActionScript vengono aggiunti dei parametri, questi ultimi vengono inclusi nella proprietà Arguments dell'oggetto ExternalInterfaceCall. In questo caso, il metodo che gestisce l'evento è semplicemente un'istruzione switch che funge da gestore del traffico. Il valore della proprietà FunctionName (e.FunctionCall.FunctionName) determina quale metodo della classe AppForm viene chiamato.

I rami dell'istruzione switch nel codice precedente dimostrano gli scenari più comuni di chiamate ai metodi. Qualunque metodo, ad esempio, deve restituire un valore ad ActionScript (ad esempio, la chiamata al metodo isReady()), altrimenti deve restituire null (come mostrato nelle altre chiamate ai metodi). L'accesso ai parametri passati da ActionScript è mostrato nella chiamata al metodo newMessage(), che passa un parametro e.FunctionCall.Arguments[0], il primo elemento dell'array Arguments.

La chiamata a una funzione ActionScript da C# mediante la classe ExternalInterfaceProxy è ancora più diretta della ricezione da ActionScript di una chiamata a una funzione. Per chiamare una funzione ActionScript, utilizzate il metodo Call() dell'istanza ExternalInterfaceProxy, come indicato di seguito:

    /// <summary> 
    /// Called when the "Send" button is pressed; the value in the 
    /// MessageText text field is passed in as a parameter. 
    /// </summary> 
    /// <param name="message">The message to send.</param> 
    private void sendMessage(string message) 
    { 
        if (swfReady) 
        { 
            ... 
            // Call the newMessage function in ActionScript. 
            proxy.Call("newMessage", message); 
        } 
    } 
    ... 
    /// <summary> 
    /// Call the ActionScript function to get the current "availability" 
    /// status and write it into the text field. 
    /// </summary> 
    private void updateStatus() 
    { 
        Status.Text = (string)proxy.Call("getStatus"); 
    } 
    ... 
}

Come mostra l'esempio, il metodo Call() della classe ExternalInterfaceProxy è molto simile alla sua controparte ActionScript, ExternalInterface.Call(). Il primo parametro è una stringa che corrisponde al nome della proprietà da chiamare. Tutti gli eventuali parametri supplementari (non mostrati in questo caso) vengono passati alla funzione ActionScript. Se la funzione ActionScript restituisce un valore, tale valore viene restituito dal metodo Call() (come mostrato nell'esempio precedente).

L'uso di un wrapper proxy su un controllo ActiveX non sempre si dimostra pratico; in alcuni casi, può essere preferibile o necessario scrivere una classe proxy personalizzata (ad esempio, scritta in un linguaggio di programmazione diverso o destinata a una piattaforma diversa). Anche se in questa sede non vengono descritti tutti i dettagli della creazione di un proxy, comprendere il funzionamento interno di una classe proxy illustrato in questo esempio può rivelarsi utile.

Utilizzate il metodo CallFunction() del controllo ActiveX di Shockwave Flash per chiamare una funzione ActionScript dal contenitore ActiveX mediante l'API esterna. Questa operazione viene mostrata nel seguente estratto dal metodo Call() della classe ExternalInterfaceProxy:

// Call an ActionScript function on the SWF in "_flashControl", 
// which is a Shockwave Flash ActiveX control. 
string response = _flashControl.CallFunction(request);

In questa porzione di codice, _flashControl è il codice ActiveX di Shockwave Flash. Le chiamate alle funzioni ActionScript vengono effettuate mediante il metodo CallFunction(), il quale riceve un parametro (nell'esempio, request), che è una stringa contenente le istruzioni in formato XML che comprendono il nome della funzione ActionScript da chiamare e gli eventuali parametri. Qualunque valore restituito da ActionScript viene codificato sotto forma di stringa in formato XML e reinviato come valore restituito dalla chiamata CallFunction(). In questo esempio, tale stringa XML viene memorizzata nella variabile response.

La ricezione di una chiamata a una funzione proveniente da ActionScript è un processo suddiviso in più fasi. Tali chiamate provocano l'invio dell'evento FlashCall da parte del controllo ActiveX di Shockwave Flash, pertanto una classe (ad esempio, ExternalInterfaceProxy) che intende ricevere le chiamate da un file SWF deve definire un gestore per tale evento. Nella classe ExternalInterfaceProxy, la funzione del gestore di eventi è denominata _flashControl_FlashCall() ed è registrata per ascoltare l'evento nella funzione di costruzione della classe, come mostrato di seguito:

private AxShockwaveFlash _flashControl; 
 
public ExternalInterfaceProxy(AxShockwaveFlash flashControl) 
{ 
    _flashControl = flashControl; 
    _flashControl.FlashCall += new _IShockwaveFlashEvents_FlashCallEventHandler(_flashControl_FlashCall); 
} 
... 
private void _flashControl_FlashCall(object sender, _IShockwaveFlashEvents_FlashCallEvent e) 
{ 
    // Use the event object's request property ("e.request") 
    // to execute some action. 
    ... 
    // Return a value to ActionScript; 
    // the returned value must first be encoded as an XML-formatted string. 
    _flashControl.SetReturnValue(encodedResponse); 
}

L'oggetto evento (e) contiene una proprietà request (e.request) costituita da una stringa che contiene le informazioni sulla chiamata alla funzione (ad esempio il nome della funzione e i parametri) in formato XML. Queste informazioni possono essere utilizzate dal contenitore per determinare quale codice eseguire. Nella classe ExternalInterfaceProxy, la richiesta viene convertita dal formato XML a un oggetto ExternalInterfaceCall, che fornisce le stesse informazioni in una forma più accessibile. Il metodo SetReturnValue() del controllo ActiveX viene utilizzato per restituire il risultato di una funzione al chiamante ActionScript; ancora una volta, il parametro risultante deve essere codificato nello stesso formato XML utilizzato dall'API esterna.

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. Nell'esempio dell'applicazione Introvert IM in C#, la classe ExternalInterfaceProxy consente al codice presente nel form dell'applicazione di agire direttamente sui valori inviati o ricevuti da ActionScript e di ignorare il formato XML utilizzato da Flash Player. Per ottenere questo risultato, la classe ExternalInterfaceProxy utilizza i metodi della classe ExternalInterfaceSerializer per convertire i messaggi XML in oggetti .NET. La classe ExternalInterfaceSerializer ha quattro metodi pubblici:

• EncodeInvoke(): codifica un nome di una funzione e un ArrayList di argomenti C# nel formato XML appropriato.

• EncodeResult(): codifica il valore di un risultato in un formato XML appropriato.

• DecodeInvoke(): decodifica una chiamata a una funzione proveniente da ActionScript. La proprietà request dell'oggetto evento FlashCall viene passata al metodo DecodeInvoke() e converte la chiamata in un oggetto ExternalInterfaceCall.

• DecodeResult(): decodifica l'XML ricevuto come risultato di una chiamata a una funzione ActionScript.

Questi metodi codificano i valori C# nel formato XML dell'API esterna e decodificano l'XML in oggetti C#. Per maggiori dettagli sul formato XML utilizzato da Flash Player, vedete Il formato XML dell'API esterna.