ExternalInterface sınıfını kullanma

Flash Player 9 ve üstü, Adobe AIR 1.0 ve üstü

ActionScript ile kap uygulaması arasındaki iletişim iki formdan birini alabilir: ActionScript, kapta tanımlı kodu (örn. bir JavaScript işlevi) çağırabilir veya kaptaki kod, çağrılabilir olarak belirlenen bir ActionScript işlevini çağırabilir. Her iki durumda da, çağrılmakta olan koda bilgi gönderilebilir ve çağrıyı yapan koda sonuçlar döndürülebilir.

Bu iletişimi kolaylaştırmak için, ExternalInterface sınıfı iki statik özellik ve iki statik yöntem içerir. Bu özellikler ve yöntemler, harici arabirim bağlantısı hakkında bilgi edinmek, ActionScript'ten kaptaki kodu çalıştırmak ve ActionScript işlevlerini kap tarafından çağrılabilir duruma getirmek için kullanılır.

Harici kap hakkında bilgi alma

ExternalInterface.available özelliği, geçerli Flash Player uygulamasının harici arabirim sunan bir kapta bulunup bulunmadığını belirtir. Harici arabirim kullanılabilir durumdaysa, bu özellik true olur; aksi takdirde, false olur. ExternalInterface sınıfındaki diğer işlevlerden herhangi birini kullanmadan önce, her zaman şu şekilde geçerli kabın harici arabirim iletişimini destekleyip desteklemediğini kontrol etmeniz gerekir:

if (ExternalInterface.available) 
{ 
    // Perform ExternalInterface method calls here. 
}
Not: ExternalInterface.available özelliği, geçerli kabın ExternalInterface bağlantısını destekleyen bir türde olup olmadığını bildirir. Bu, size geçerli tarayıcıda JavaScript'in etkinleştirilmiş olup olmadığını bildirmez.

ExternalInterface.objectID özelliği, Flash Player örneğinin benzersiz tanımlayıcısını (özellikle de Internet Explorer'da object etiketinin id niteliği veya NPRuntime arabirimini kullanan tarayıcılarda embed etiketinin name niteliği) belirlemenize olanak sağlar. Bu benzersiz kimlik, tarayıcıda geçerli SWF belgesini temsil eder ve örneğin, bir kap HTML sayfasında JavaScript işlevi çağrılırken SWF belgesine başvuru yapmak için kullanılabilir. Flash Player kabı bir web tarayıcısı değilse, bu özellik null olur.

ActionScript'ten harici kod çağırma

ExternalInterface.call() yöntemi, kap uygulamasında kodu çalıştırır. Kap uygulamasında çağrılması için en az bir parametre ve işlevin adını içeren bir dize gereklidir. ExternalInterface.call() yöntemine iletilen tüm ek parametreler, işlev çağrısının parametreleri olarak kap boyunca iletilir.

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

Kap bir HTML sayfasıysa, bu yöntem belirtilen ada sahip ve kapsayan HTML sayfasındaki bir script öğesinde tanımlanmış olması gereken JavaScript işlevini çağırır. JavaScript işlevinin döndürme değeri, ActionScript'e geri iletilir.

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

Kap başka bir ActiveX kabıysa, bu yöntem Flash Player ActiveX denetiminin FlashCall olayını göndermesine neden olur. Belirtilen işlev adı ve tüm parametreler, Flash Player tarafından bir XML dizesine serileştirilir. Kap, olay nesnesinin request özelliğinde bu bilgilere erişebilir ve kendi kodunun nasıl çalıştırılacağını belirlemek için bu bilgileri kullanır. Kap kodu, ActionScript'e bir değer döndürmek için ActiveX nesnesinin SetReturnValue() yöntemini çağırarak sonucu (XML dizesine serileştirişmiş) o yöntemin bir parametresi olarak iletir. Bu iletişim için kullanılan XML biçimi hakkında daha fazla bilgi almak için bkz. Harici API’nin XML biçimi.

Kap bir web tarayıcısı da olsa veya başka bir ActiveX kabı da olsa, çağrı başarısız olursa ya da kap yöntemi bir döndürme değeri belirtmezse, null değeri döndürülür. Kapsayan ortam, çağıran kodun erişemediği bir güvenlik sanal alanına aitse, ExternalInterface.call() yöntemi bir SecurityError istisnası atar. Kapsayan ortamda allowScriptAccess için uygun bir değer ayarlayarak bu soruna geçici çözüm oluşturabilirsiniz. Örneğin, bir HTML sayfasında allowScriptAccess değerini değiştirmek için, object ve embed etiketlerinde uygun niteliği düzenlersiniz.

Kaptan ActionScript kodu çağırma

Kap yalnızca bir işlevde bulunan ActionScript kodunu çağırabilir—başka bir ActionScript kodu kap tarafından çağrılamaz. Kap uygulamasından bir ActionScript işlevi çağırmak için iki şey yapmanız gerekir: işlevi ExternalInterface sınıfıyla kaydetme ve sonra kabın kodundan çağırma.

İlk olarak, kap için kullanılabilir durumda olduğunu belirtmek üzere ActionScript işlevinizi kaydetmeniz gerekir. Aşağıdaki gibi, ExternalInterface.addCallback() yöntemini kullanın:

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

addCallback() yöntemi iki parametre alır. Birincisi olan String olarak işlev adı, işlevin kap tarafından bilinecek adıdır. İkinci parametre, kap tanımlı işlev adını çağırdığında çalıştırılacak olan gerçek ActionScript işlevidir. Bu adlar birbirinden farklı olduğundan, ActionScript işlevi farklı bir ada sahip olsa da, kap tarafından kullanılacak bir işlev adı belirtebilirsiniz. Bu özellikle de işlev adı bilinmediğinde, örneğin, adsız bir işlev belirtildiğinde veya çağrılacak işlev çalışma zamanında belirlendiğinde kullanışlıdır.

Bir ActionScript işlevi ExternalInterface sınıfıyla kaydolduktan sonra, kap gerçekten işlevi çağırabilir. Bunun yapılma şekli, kabın türüne göre değişiklik gösterir. Örneğin, ActionScript işlevi bir web tarayıcısındaki JavaScript kodunda, Flash Player tarayıcı nesnesinin bir yöntemiymiş gibi (başka bir deyişle, object veya embed etiketini temsil eden bir JavaScript yöntemiymiş gibi), kayıtlı işlev adı kullanılarak çağrılır. Başka bir deyişle, parametreler iletilir ve yerel bir işlev çağrılmış gibi bir sonuç döndürülür.

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

Alternatif olarak, masaüstü uygulamasında çalışan bir SWF dosyasında ActionScript işlevi çağrılırken, kayıtlı işlev adı ve parametrelerin XML biçiminde bir dizeye serileştirilmesi gerekir. Daha sonra parametre olarak XML dizesiyle ActiveX denetiminin CallFunction() yöntemi çağrılarak gerçekten çağrı gerçekleştirilir. Bu iletişim için kullanılan XML biçimi hakkında daha fazla bilgi almak için bkz. Harici API’nin XML biçimi.

Çağıran bir tarayıcıdaki JavaScript kodu olduğunda doğrudan bir değer olarak veya çağıran bir ActiveX kabı olduğunda XML biçimli bir dize olarak serileştirilmiş şekilde, her durumda ActionScript işlevinin döndürme değeri kap koduna geri iletilir.

Harici API’nin XML biçimi

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. Harici API tarafından kullanılan XML biçiminin iki bölümü vardır. Bir biçim, işlev çağrılarını temsil etmek için kullanılır. Başka bir biçim ise tek tek değerleri temsil etmek için kullanılır; bu biçim, işlev döndürme değerlerinin yanı sıra işlevlerdeki parametreler için de kullanılır. İşlev çağrılarının XML biçimi, ActionScript'e ve ActionScript'ten gelen çağrılar için kullanılır. ActionScript'ten gelen bir işlev için Flash Player, XML'i kaba iletir; kaptan gelen bir çağrı için Flash Player, kap uygulamasının kendisine bu biçimde bir XML dizesi iletmesini bekler. Aşağıdaki XML parçası, örnek bir XML biçimli işlev çağrısı göstermektedir:

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

Kök düğüm, invoke düğümüdür. İki niteliğe sahiptir: name öğesi, çağrılacak işlevin adını belirtir ve returntype her zaman xml olur. İşlev çağrısı parametreler içeriyorsa, invoke düğümü, alt düğümleri daha sonra açıklanan tek tek değer biçimi kullanılarak biçimlendirilmiş parametre değerleri olacak bir alt arguments düğümüne sahiptir.

İşlev parametreleri ve işlev döndürme değerleri gibi tek tek değerler, gerçek değerlere ek olarak veri türü bilgilerini de içeren bir biçimlendirme şemasını kullanır. Aşağıdaki tabloda, bu veri türünün değerlerini kodlamak için kullanılan ActionScript sınıfları ve XML biçimi listelenmektedir:

ActionScript sınıfı/değeri

C# sınıfı/değeri

Biçim

Yorumlar

null

null

<null/>

 

Boolean true

bool true

<true/>

 

Boolean false

bool false

<false/>

 

Dize

dize

<string>string value</string>

 

Number, int, uint

single, double, int, uint

<number>27.5</number> 
<number>-12</number>
 

Array (karma tür olabilen öğeler)

ArrayList veya object[] gibi karma tür öğelere izin veren bir koleksiyon

<array> 
    <property id="0"> 
        <number>27.5</number> 
    </property> 
    <property id="1"> 
        <string>Hello there!</string> 
    </property> 
    ... 
</array>

property düğümü tek tek öğeleri tanımlar ve id niteliği sayısal, sıfır tabanlı dizindir.

Nesne

Dize anahtarları içeren bir HashTable gibi dize anahtarları ve nesne değerlerini içeren bir sözlük

<object> 
    <property id="name"> 
        <string>John Doe</string> 
    </property> 
    <property id="age"> 
        <string>33</string> 
    </property> 
    ... 
</object>

property düğümü tek tek özellikleri tanımlar ve id niteliği özellik adıdır (dize).

Diğer yerleşik veya özel sınıflar

 
<null/> or  
<object></object>

ActionScript, diğer nesneleri null olarak veya boş bir nesne olarak kodlar. Her iki durumda da özellik değerleri kaybolur.

Not: Bu tabloda, örnekleme yoluyla, ActionScript sınıflarına ek olarak eşdeğer C# sınıfları gösterilmektedir, harici API, herhangi bir programlama diliyle veya ActiveX denetimlerini destekleyen çalışma zamanıyla iletişim kurmak için kullanılabilir ve C# uygulamalarıyla sınırlı değildir.

Bir ActiveX kabı uygulaması ile harici API kullanarak kendi uygulamalarınızı oluştururken, yerel işlev çağrılarını serileştirilmiş XML biçimine dönüştürme görevini gerçekleştirecek bir proxy yazmanız rahatlık sağlayabilir. C# uygulamasında yazılmış bir proxy sınıfı örneği için, bkz. ExternalInterfaceProxy sınıfının içinde.