Harici API örneği: ActionScript ve ActiveX denetimi kullanan bir masaüstü uygulaması arasındaki iletişim

Bu örnek uygulama, birbiriyle iletişim kuran iki anında mesajlaşma programını (biri SWF dosyası içinde, diğeri de Windows Form'da yerleşik) temsil eder. Kullanıcı arabirimi, ActionScript IM istemcisini içeren SWF dosyasının yüklendiği bir Shockwave Flash ActiveX denetimi örneğini içerir. Arabirim, Windows Forms IM istemcisini oluşturan birçok metin alanını da içerir: mesajları girmek için bir alan (MessageText), istemciler arasında gönderilen mesajların kopyasını görüntüleyen başka bir alan (Transcript) ve SWF IM istemcisinde ayarlandığı şekilde kullanılabilirlik durumunu görüntüleyen üçüncü bir alan (Status).

Shockwave Flash ActiveX denetimini kendi Windows Forms uygulamanıza dahil etmek için, ilk önce bu denetimi Microsoft Visual Studio Toolbox'a eklemeniz gerekir.

Bir ActiveX kabı uygulaması ile harici API kullanılarak kurulan iletişim, tek bir önemli fark dışında web tarayıcısıyla iletişim gibi çalışır. Daha önce de açıklandığı gibi, ActionScript bir web tarayıcısıyla iletişim kurduğuna, geliştiriciye göre işlevler doğrudan çağrılır; işlev çağrılarının ve yanıtlarının oynatıcı ve tarayıcı arasında iletilmek üzere nasıl biçimlendirildiğine yönelik ayrıntılar gizlenir. Ancak, bir ActiveX kabı uygulamasıyla iletişim kurmak için harici API kullanıldığında, Flash Player, mesajları (işlev çağrılarını ve döndürme değerlerini) uygulamaya belirli bir XML biçiminde gönderir ve kap uygulamasından gelen işlev çağrılarının ve döndürme değerlerinin aynı XML biçimini kullanmasını bekler. ActiveX kabı uygulaması geliştiricisinin, işlev çağrılarını ve yanıtlarını anlayıp oluşturabilen ve bunları uygun biçimde yanıtlayan kod yazması gerekir.

Introvert IM C# örneği, mesajların biçimlendirmesini önlemenize olanak sağlayan bir sınıf kümesi içerir; bunun yerine ActionScript işlevlerini çağırırken ve ActionScript'ten gelen işlev çağrılarını alırken standart veri türleriyle çalışabilirsiniz. ExternalInterfaceProxy sınıfı, diğer yardımcı sınıflarla birlikte bu işlevselliği sunar ve harici API iletişimini kolaylaştırmak için herhangi bir .NET projesinde yeniden kullanılabilir.

Ana uygulama formundan (AppForm.cs) alınmış aşağıdaki kod bölümleri, ExternalInterfaceProxy sınıfı kullanılarak gerçekleştirilen basitleştirilmiş etkileşimi gösterir:

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

Uygulama, proxy adında bir ExternalInterfaceProxy örneği bildirip oluşturarak kullanıcı arabirimindeki (IntrovertIMApp) Shockwave Flash ActiveX denetimine yapılan bir başvuruda geçer. Daha sonra kod, proxy’nin ExternalInterfaceCall olayını almak için proxy_ExternalInterfaceCall() yöntemini kaydeder. Bu olay, Flash Player'dan bir işlev çağrısı geldiğinde ExternalInterfaceProxy sınıfı tarafından gönderilir. C# kodu, bu olaya abone olunmasıyla ActionScript'ten gelen işlev çağrılarını alır ve yanıtlar.

ActionScript'ten bir işlev çağrısı geldiğinde, ExternalInterfaceProxy örneği (proxy) çağrıyı alır, XML biçimine dönüştürür ve proxy’nin ExternalInterfaceCall olayı için dinleyici olan nesnelere bildirim gönderir. AppForm sınıfı olması durumunda, proxy_ExternalInterfaceCall() yöntemi şu şekilde olayı işler:

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

Yönteme, bu örnekte e olarak adlandırılmış bir ExternalInterfaceCallEventArgs örneği iletilir. Daha sonra da bu nesne, ExternalInterfaceCall sınıfının örneği olan bir FunctionCall özelliğine sahip olur.

ExternalInterfaceCall örneği, iki özelliğe sahip basit bir değer nesnesidir. FunctionName özelliği, ActionScript ExternalInterface.Call() deyiminde belirtilen işlev adını içerir. ActionScript'e herhangi bir parametre eklenirse, ExternalInterfaceCall nesnesinin Arguments özelliğine bu parametreler dahil edilir. Bu durumda, olayı işleyen yöntem yalnızca trafik yöneticisi olarak hareket eden bir switch deyimidir. FunctionName özelliğinin değeri (e.FunctionCall.FunctionName), AppForm sınıfının hangi yönteminin çağrıldığını belirler.

Önceki kod listesinde yer alan switch deyiminin dalları, yaygın yöntem çağrısı senaryolarını gösterir. Örneğin, tüm yöntemlerin ActionScript'e bir değer döndürmesi gerekir (örneğin, isReady() yöntem çağrısı), aksi takdirde null değerinin dönmesi gerekir (diğer yöntem çağrılarında görüldüğü gibi). ActionScript'ten iletilen parametrelere erişilmesi, newMessage() yöntem çağrısında (Arguments dizisinin birinci öğesi olan e.FunctionCall.Arguments[0] parametresi boyunca iletilen) gösterilmiştir.

ExternalInterfaceProxy sınıfı kullanılarak C# uygulamasından bir ActionScript çağrılması, ActionScript'ten bir işlev çağrısı alınmasına göre daha net bir eylemdir. Bir ActionScript işlevini çağırmak için, aşağıdaki gibi, ExternalInterfaceProxy örneğinin Call() yöntemini kullanırsınız:

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

Bu örnekte de gösterildiği gibi, ExternalInterfaceProxy sınıfının Call() yöntemi, ActionScript'teki eşdeğerine ExternalInterface.Call() çok benzer. Birinci parametre bir dize olup çağrılacak işlemin adını ifade eder. Ek parametrelerin tümü (burada gösterilmeyenler) ActionScript işlevi boyunca iletilir. ActionScript işlevi bir değer döndürürse, bu değer Call() yöntemi tarafından döndürülür (önceki örnekte de görüldüğü gibi).

ActiveX denetimi etrafında bir proxy sarıcı kullanılması her zaman pratik bir yöntem olmayabilir veya kendi proxy sınıfınızı yazmak isteyebilirsiniz (örneğin, farklı bir programlama dilinde veya farklı bir platformu hedefleyen). Proxy oluşturulmasına yönelik tüm ayrıntılar burada açıklanmasa da, bu örnekteki proxy sınıfının iç çalışmalarının anlaşılması gerekir.

Harici API kullanan ActiveX kabından bir ActionScript işlevi çağırmak için, Shockwave Flash ActiveX denetiminin CallFunction() yöntemini kullanırsınız. ExternalInterfaceProxy sınıfının Call() yönteminin alıntısında bu gösterilmektedir:

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

Bu kod alıntısında, _flashControl, Shockwave Flash ActiveX denetimidir. ActionScript işlev çağrıları, CallFunction() yöntemi kullanılarak yapılır. Bu yöntem, çağrılacak ActionScript işlevinin adı ve parametreler dahil olmak üzere, XML biçimli talimatlar içeren bir dize niteliğindeki tek bir parametreyi (bu örnekte request) alır. ActionScript'ten döndürülen tüm değerler XML biçimli bir dize olarak kodlanır ve CallFunction() çağrısının döndürme değeri olarak geri gönderilir. Bu örnekte, söz konusu XML dizesi response değişkeninde saklanır.

ActionScript'ten gelen bir işlev çağrısının alınması birkaç adımdan oluşan bir işlemdir. ActionScript'ten gelen işlev çağrıları, Shockwave Flash ActiveX denetiminin FlashCall olayını göndermesine neden olur, bu nedenle, SWF dosyasından çağrı almaya çalışan bir sınıfın (örn. ExternalInterfaceProxy sınıfı), o olay için bir işleyici tanımlaması gerekir. ExternalInterfaceProxy sınıfında, olay işleyicisi işlevi _flashControl_FlashCall() olarak adlandırılır ve aşağıdaki gibi, sınıf yapıcısında olayı dinlemek için kaydedilir:

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

Olay nesnesi (e), işlev adı ve parametreleri gibi işlev çağrısı hakkındaki bilgilerin XML biçiminde yer aldığı bir dize olan request özelliğine (e.request) sahiptir. Bu bilgiler, hangi kodun çalıştırılacağını belirlemek için kap tarafından kullanılabilir. ExternalInterfaceProxy sınıfında, XML biçimindeki istek, aynı bilgileri daha erişilebilir biçimde sağlayan bir ExternalInterfaceCall nesnesine dönüştürülür. ActionScript çağıranına bir işlev sonucunu döndürmek için, ActiveX denetiminin SetReturnValue() yöntemi kullanılır; yine sonuç parametresinin, harici API tarafından kullanılan XML biçiminde kodlanması gerekir.

ActionScript ile Shockwave Flash ActiveX denetimini barındıran bir uygulama arasındaki iletişim, işlev çağrılarını ve değerlerini kodlamak için belirli bir XML biçimini kullanır. Introvert IM C# örneğinde, ExternalInterfaceProxy sınıfı, uygulama formundaki kodun, ActionScript'e gönderilen veya ActionScript'ten alınan değerler üzerinde doğrudan çalışmasına ve Flash Player tarafından kullanılan XML biçiminin ayrıntılarını yok saymasına olanak sağlar. ExternalInterfaceProxy sınıfı, bunu gerçekleştirmek için XML mesajlarını .NET nesnelerine gerçekten çevirmek üzere ExternalInterfaceSerializer sınıfının yöntemlerini kullanır. ExternalInterfaceSerializer sınıfı dört yönteme sahiptir:

• EncodeInvoke(): Bir işlev adını ve argümanların C# ArrayList öğesini uygun XML biçimine kodlar.

• EncodeResult(): Bir sonuç değerini uygun XML biçimine kodlar.

• DecodeInvoke(): ActionScript'ten gelen bir işlev çağrısının kodunu çözer. DecodeInvoke() yöntemine FlashCall olay nesnesinin request özelliği iletilir ve bu yöntem, çağrıyı bir ExternalInterfaceCall nesnesine çevirir.

• DecodeResult(): ActionScript işlevinin çağrılması sonucunda alınan XML'in kodunu çözer.

Bu yöntemler, C# değerlerini harici API'nin XML biçimine kodlar ve XML'in kodunu C# nesneleri olarak çözer. Flash Player tarafından kullanılan XML biçimiyle ilgili ayrıntılar için, bkz. Harici API’nin XML biçimi.