Exemplo de API externa: comunicação entre ActionScript e um aplicativo de desktop que usa o controle de ActiveX

Este aplicativo de exemplo representa dois programas cliente de mensagem instantânea (um no arquivo SWF e outro incorporado no Windows Forms) que se comunicam. A interface de usuário inclui uma ocorrência do controle ActiveX do Shockwave Flash, na qual é carregado o arquivo SWF que contém o cliente IM do ActionScript. A interface também inclui diversos campos de texto que fazem parte do cliente IM do Windows Forms: um campo para inserir mensagens (MessageText), outro que exibe a transcrição das mensagens enviadas entre os clientes (Transcript) e um terceiro (Status) que exibe o status de disponibilidade definido no cliente IM do SWF.

Para incluir o controle ActiveX do Shockwave Flash no seu próprio aplicativo Windows Forms, adicione-o primeiro à caixa de ferramentas do Microsoft Visual Studio.

A comunicação feita com a API externa e um aplicativo de contêiner ActiveX funciona como a comunicação com um navegador da Web, com uma diferença importante. Conforme descrito anteriormente, quando o ActionScript se comunica com um navegador da Web, contanto que o navegador queira, as funções são chamadas diretamente; os detalhes de como as chamadas e respostas de função são formatadas para serem transmitidas entre o player e o navegador são ocultos. No entanto, quando a API externa é usada para se comunicar com um aplicativo de contêiner ActiveX, o Flash Player envia mensagens (chamadas de função e valores de retorno) ao aplicativo em um formato XML específico e espera chamadas de função e valores de retorno do aplicativo de contêiner para usar o mesmo formato XML. O desenvolvedor do aplicativo de contêiner ActiveX deve gravar o código entendido e pode criar chamadas de função e respostas no formato apropriado.

O exemplo do Introvert IM em C# inclui um conjunto de classes que permitem evitar mensagens de formatação; em vez disso, você pode trabalhar com tipos de dados padrão ao chamar funções do ActionScript e receber chamadas de função do ActionScript. A classe ExternalInterfaceProxy, junto com outras classes auxiliares, fornece essa funcionalidade e pode ser reutilizada em qualquer projeto .NET para facilitar a comunicação da API externa.

As seções de código a seguir, extraídas do formulário do aplicativo principal (AppForm.cs), demonstram a interação simplificada que é atingida com a 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); 
        ... 
    } 
    ...

O aplicativo declara e cria uma ocorrência de ExternalInterfaceProxy chamada proxy, transmitindo uma referência ao controle ActiveX do Shockwave Flash que está na interface de usuário (IntrovertIMApp). Em seguida, o código registra o método proxy_ExternalInterfaceCall() para receber o evento ExternalInterfaceCall do proxy. Esse evento é enviado pela classe ExternalInterfaceProxy quando uma chamada de função vem do Flash Player. A inscrição nesse evento é o modo como o código C# recebe e responde às chamadas de função do ActionScript.

Quando uma chamada de função vem do ActionScript, a ocorrência de ExternalInterfaceProxy (proxy) recebe a chamada, a converte em formato XML e notifica os objetos que são ouvintes do evento ExternalInterfaceCall do proxy. No caso da classe AppForm, o método proxy_ExternalInterfaceCall() manipula esse evento da seguinte forma:

    /// <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; 
        } 
    } 
    ...

O método é transmitido como uma ocorrência de ExternalInterfaceCallEventArgs, chamada e neste exemplo. Esse objeto tem uma propriedade FunctionCall que é uma ocorrência da classe ExternalInterfaceCall.

Uma ocorrência de ExternalInterfaceCall é um simples objeto de valor com duas propriedades. A propriedade FunctionName contém o nome de função especificado na instrução ExternalInterface.Call() do ActionScript. Se algum parâmetro for adicionado ao ActionScript, esses parâmetros serão incluídos na propriedade Arguments do objeto ExternalInterfaceCall. Nesse caso, o método que manipula o evento é simplesmente uma instrução switch que age como um gerenciador de tráfego. O valor da propriedade FunctionName (e.FunctionCall.FunctionName) determina qual método da classe AppForm é chamado.

As ramificações da instrução switch na listagem de código anterior demonstram cenários comuns de chamada de método. Por exemplo, qualquer método deve retornar um valor para o ActionScript (como a chamada do método isReady()) ou deve retornar null (conforme visto nas outras chamadas de método). O acesso aos parâmetros transmitidos do ActionScript é demonstrado na chamada do método newMessage() (que é transmitido como o parâmetro e.FunctionCall.Arguments[0], o primeiro elemento da matriz Arguments).

Chamar uma função do ActionScript em C# usando a classe ExternalInterfaceProxy é ainda mais simples do que receber uma chamada de função a partir do ActionScript. Para chamar uma função do ActionScript, use o método Call() da ocorrência de ExternalInterfaceProxy do seguinte modo:

    /// <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"); 
    } 
    ... 
}

Como mostra este exemplo, o método Call() da classe ExternalInterfaceProxy é muito parecido com seu correspondente no ActionScript, ExternalInterface.Call(). O primeiro parâmetro é uma string, o nome da função a ser chamada. Todos os parâmetros adicionais (não mostrados aqui) são transmitidos junto com a função do ActionScript. Se a função do ActionScript retornar um valor, esse valor será retornado pelo método Call() (conforme visto no exemplo anterior).

Usar um envoltório de proxy em torno do controle ActiveX talvez nem sempre seja prático ou você talvez queira gravar sua própria classe de proxy (por exemplo, em uma linguagem de programação diferente ou visando uma plataforma diferente). Embora nem todos os detalhes da criação do proxy sejam explicados aqui, é útil entender o funcionamento da classe de proxy desse exemplo.

Use o método CallFunction() do controle ActiveX do Shockwave Flash para chamar uma função do ActionScript a partir do contêiner ActiveX usando a API externa. Isso é mostrado no trecho do método Call() da classe ExternalInterfaceProxy:

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

Neste trecho de código, _flashControl é o controle ActiveX do Shockwave Flash. As chamadas de função do ActionScript são feitas com o método CallFunction(). Esse método assume um parâmetro (request no exemplo), que é uma string que contém as instruções em formato XML, incluindo o nome da função do ActionScript a ser chamada e os parâmetros. Todos os valores retornados do ActionScript são codificados como uma string XML e enviados de volta como o valor de retorno da chamada CallFunction(). Neste exemplo, essa string XML é armazenada na variável response.

O recebimento de uma chamada de função do ActionScript é um processo de várias etapas. As chamadas de função do ActionScript fazem com que o controle ActiveX do Shockwave Flash envie o evento FlashCall, de modo que a classe (como a classe ExternalInterfaceProxy) que deve receber as chamadas de um arquivo SWF precisa definir um manipulador para esse evento. Na classe ExternalInterfaceProxy, a função do manipulador de eventos é chamada de _flashControl_FlashCall(), e é registrada para ouvir o evento no construtor da classe do seguinte modo:

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

O objeto de evento (e) tem uma propriedade request (e.request) que é uma string que contém informações sobre a chamada de função, como o nome da função e os parâmetros, em formato XML. Essas informações podem ser usadas pelo contêiner para determinar o código a ser executado. Na classe ExternalInterfaceProxy, a solicitação é convertida do formato XML em um objeto ExternalInterfaceCall, que fornece as mesmas informações de forma mais acessível. O método SetReturnValue() do controle ActiveX é usado para retornar um resultado de função para o chamador do ActionScript; novamente, o parâmetro resultante deve ser codificado no formato XML usado pela API externa.

A comunicação entre o ActionScript e um aplicativo que hospeda o controle ActiveX do Shockwave Flash usa um formato XML específico para codificar chamadas e valores de função. No exemplo do Introvert IM em C#, a classe ExternalInterfaceProxy possibilita isso para o código no formulário do aplicativo a ser aplicado diretamente nos valores enviados ou recebidos do ActionScript, e ignora os detalhes do formato XML usado pelo Flash Player. Para fazer isso, a classe ExternalInterfaceProxy usa os métodos da classe ExternalInterfaceSerializer para realmente converter as mensagens XML em objetos .NET. A classe ExternalInterfaceSerializer tem quatro métodos públicos:

• EncodeInvoke(): codifica um nome de função e um C# ArrayList de argumentos no formato XML apropriado.

• EncodeResult(): codifica um valor de resultado no formato XML apropriado.

• DecodeInvoke(): decodifica uma chamada de função do ActionScript. A propriedade request do objeto de evento FlashCall é transmitida para o método DecodeInvoke() e converte a chamada em um objeto ExternalInterfaceCall.

• DecodeResult(): decodifica o XML recebido em resultado da chamada de uma função do ActionScript.

Esses métodos codificam valores C# no formato XML da API externa e decodificam o XML em objetos C#. Para obter informações sobre o formato XML usado pelo Flash Player, consulte O formato XML da API externa.