Exempel på extern API: kommunicera mellan ActionScript och ett skrivbordsprogram som använder ActiveX-kontrollen

Det här exempelprogrammet representerar två klientprogram för snabbmeddelanden (en med enbart en SWF-fil och en som har byggts med Windows Forms) som kommunicerar med varandra. Användargränssnittet innehåller en instans av Shockwave Flash ActiveX-kontrollen. Det är i den instansen som SWF-filen som innehåller ActionScript IM-klienten läses in. Gränssnittet innehåller också flera textfält som utgör Windows Forms IM-klient: ett fält att skriva meddelanden i (MessageText), ett annat som visar meddelandena som skickas mellan klienterna (Transcript) och ett tredje (Status) som visar den tillgänglighetsstatus som ställts in i SWF IM-klienten.

För att kunna inkludera Shockwave Flash ActiveX-kontrollen i ditt eget Windows Forms-program måste du först lägga till det i Microsoft Visual Studio Toolbox.

Kommunikation som sker genom att det externa API:t används med ett ActiveX-behållarprogram fungerar på samma sätt som kommunikation med en webbläsare, med en viktig skillnad. När ActionScript kommunicerar med en webbläsare anropas funktionerna direkt (ur utvecklarens perspektiv). Detaljerna för hur funktionsanropen och svaren formateras när de skickas mellan spelaren och webbläsaren är dolda. När det externa API:t används för att kommunicera med ett ActiveX-behållarprogram skickar Flash Player däremot meddelanden (funktionsanrop och returvärden) till programmet i ett specifikt XML-format. Funktionsanrop och returvärden från behållarprogrammet förväntas använda samma XML-format. Den som skapar ActiveX-behållarprogrammet måste skriva kod som kan tolka och skapa funktionsanrop och svar i det format som används.

I exemplet med Introvert IM i C# inkluderas en uppsättning klasser som gör att du slipper formateringsmeddelanden. Du kan i stället arbeta med standarddatatyper när du anropar ActionScript-funktioner och tar emot funktionsanrop från ActionScript. Klassen ExternalInterfaceProxy ger denna funktionalitet tillsammans med andra hjälpklasser och kan återanvändas i alla .NET-projekt för att underlätta kommunikation med det externa API:t.

I följande kodavsnitt, som är utdrag ur huvudprogramformuläret (AppForm.cs), visas den förenklade interaktionen som uppnås med hjälp av klassen 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); 
        ... 
    } 
    ...

Programmet deklarerar och skapar en ExternalInterfaceProxy-instans som heter proxy och skickar en referens till Shockwave Flash ActiveX-kontrollen som finns i användargränssnittet (IntrovertIMApp). Därefter registrerar koden metoden proxy_ExternalInterfaceCall() för att ta emot proxyns ExternalInterfaceCall-händelse. Händelsen skickas av klassen ExternalInterfaceProxy när ett funktionsanrop kommer från Flash Player. C#-koden får och svarar på funktionsanrop från ActionScript genom att lyssna efter den här händelsen.

När ett funktionsanrop kommer från ActionScript tar ExternalInterfaceProxy-instansen (proxy) emot anropet, konverterar det från XML-format och meddelar de objekt som är avlyssnare för proxyns ExternalInterfaceCall-händelse. När det gäller klassen AppForm hanterar metoden proxy_ExternalInterfaceCall() händelsen på följande sätt:

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

Metoden tar emot en ExternalInterfaceCallEventArgs-instans som heter e i det här exemplet. Det objektet har i sin tur en FunctionCall-egenskap som är en instans av klassen ExternalInterfaceCall.

En ExternalInterfaceCall-instans är ett enkelt värdeobjekt med två egenskaper. Egenskapen FunctionName innehåller det funktionsnamn som angavs i ActionScript-programsatsen ExternalInterface.Call(). Om parametrar läggs till i ActionScript tas de med i ExternalInterfaceCall-objektets Arguments-egenskap. I det här fallet är metoden som hanterar händelsen en enkel switch-programsats som fungerar som trafikpolis. Värdet för egenskapen FunctionName (e.FunctionCall.FunctionName) avgör vilken metod i klassen AppForm som anropas.

Förgreningarna i switch-programsatsen i föregående kodexempel visar vanliga scenarier för metodanrop. Alla metoder måste till exempel returnera ett värde till ActionScript (till exempel metodanropet isReady()), annars ska de returnera null (såsom i de andra metodanropen). Åtkomst till parametrar som skickats från ActionScript demonstreras i metodanropet newMessage() (som skickar med parametern e.FunctionCall.Arguments[0], det första elementet i arrayen Arguments).

Anrop till en ActionScript-funktion från C# med klassen ExternalInterfaceProxy är ännu enklare än att ta emot ett funktionsanrop från ActionScript. När du anropar en ActionScript-funktion använder du ExternalInterfaceProxy-instansens Call()-metod på följande sätt:

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

Exemplet visar att metoden Call() i klassen ExternalInterfaceProxy är mycket lik sin motsvarighet i ActionScript, ExternalInterface.Call(). Den första parametern är en sträng, som är namnet på den funktion som ska anropas. Andra eventuella parametrar (visas inte här) skickas vidare till ActionScript-funktionen. Om ActionScript-funktionen returnerar ett värde, returneras värdet av metoden Call() (vilket visas i föregående exempel).

Det är inte alltid praktiskt att bädda in ActiveX-kontrollen i en proxy, eller också kanske du vill skriva en egen proxyklass (till exempel i ett annat programmeringsspråk eller för en annan plattform). Alla detaljer om hur man skapar en proxy beskrivs inte här, men det kan vara nyttigt att förstå hur proxyklassen i exemplet fungerar.

Du använder Shockwave Flash ActiveX-kontrollens CallFunction()-metod för att anropa en ActionScript-funktion från ActiveX-behållaren med det externa API:t. Detta visas i det här utdraget från metoden Call() i klassen ExternalInterfaceProxy:

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

I det här kodutdraget är _flashControl Shockwave Flash ActiveX-kontrollen. ActionScript-funktionsanrop görs med metoden CallFunction(). Den metoden tar en parameter (request i exemplet) som är en sträng som innehåller XML-formaterade instruktioner, inklusive namnet på den ActionScript-funktion som ska anropas och alla eventuella parametrar. Alla värden som returneras från ActionScript kodas som en XML-formaterad sträng och skickas tillbaka som returvärde för anropet CallFunction(). I det här exemplet sparas XML-strängen i variabeln response.

Att ta emot ett funktionsanrop från ActionScript är en process med flera steg. Funktionsanrop från ActionScript gör att Shockwave Flash ActiveX-kontrollen skickar sin FlashCall-händelse. En klass (till exempel ExternalInterfaceProxy) som är avsedd att ta emot anrop från en SWF-fil måste därför definiera en hanterare för den händelsen. I klassen ExternalInterfaceProxy heter händelsehanterarfunktionen _flashControl_FlashCall(). Den registreras att lyssna efter händelsen i klassens konstruktor på följande sätt:

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

Händelseobjektet (e) har en request-egenskap (e.request) som är en sträng med information om funktionsanropet, till exempel funktionens namn och parametrar, i XML-format. Den här informationen kan användas av behållaren för att avgöra vilken kod som ska köras. I klassen ExternalInterfaceProxy konverteras begäran från XML-format till ett ExternalInterfaceCall-objekt som ger samma information i ett mer tillgängligt format. Metoden SetReturnValue() i ActiveX-kontrollen används för att returnera resultatet av en funktion till ActionScript-anroparen. Återigen måste resultatparametern kodas i det XML-format som används av det externa API:t.

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. I exemplet med Introvert IM i C# gör klassen ExternalInterfaceProxy att det blir möjligt för koden i programformuläret att verka direkt på värden som skickas till eller tas emot från ActionScript, utan att ta hänsyn till detaljerna i det XML-format som används av Flash Player. Klassen ExternalInterfaceProxy uppnår detta genom att använda metoderna i klassen ExternalInterfaceSerializer för att göra den faktiska översättningen av XML-meddelandena till .NET-objekt. Klassen ExternalInterfaceSerializer har fyra publika metoder:

• EncodeInvoke(): Kodar ett funktionsnamn och en ArrayList med argument i C# till det XML-format som används.

• EncodeResult(): Kodar ett resultatvärde till det XML-format som används.

• DecodeInvoke(): Avkodar ett funktionsanrop från ActionScript. FlashCall-händelseobjektets request-egenskap skickas till metoden DecodeInvoke() och anropet översätts till ett ExternalInterfaceCall-objekt.

• DecodeResult(): Avkodar det XML som tas emot som ett resultat av anrop till en ActionScript-funktion.

Dessa metoder kodar C#-värden till det externa API:ts XML-format och avkodar XML till C#-objekt. Mer information om det XML-format som används i Flash Player finns i Det externa API:ts XML-format.