ExternalInterface sınıfını kullanma

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

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.

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.

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.

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:

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

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

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

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

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.