XPConnect Sample

原版本

Ariel Blackenroth <arielb@rice.edu>
Michael Ang <mang@subcarrier.org>
Last modified 09/19/2006 14:21:29

在"錯了也沒關係"也沒關係的這個想法底下，我們寫出了這份指南。它還不成熟，所以還會再進行修改。

XPConnect 可以光靠 Javascript 就能完整控制整個 XPCOM 物件。在 Javascript 和 native code 之間的溝通是靠 XPIDL 介面定義的程序語言來控制的。可以參考 Roadmap for documentation on XPCOM, XPConnect, XPTCall and XPIDL 獲得更多資訊。

概觀

這份範例將展示如何透過 XPConnect 取用一個 XPCOM 物件，Javascript 會在頁面載入的>時候就用 components 物件創建一個實體(instance)，然後透過nsISample 介面呼叫一個 QueryInterface 。

netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
sample = sample.QueryInterface(Components.interfaces.nsISample);

在表單上面的按鈕連接著 javascript 事件處理器，它會再去呼叫 C++ 程式碼中定義的功>能。

nsISample.idl 這個介面宣告了 XPCOM 物件。它定義了兩個函式跟所需要的的參數還有一個屬性。它同時>也設定好了這個介面的 id 。這個 idl 檔案是用 xpidl 編譯器編進 C++ 標頭檔。這些東>西包括 nsISample.h 還有一個 .xpt 的檔案在執行期間還會用再用到。

attribute string value;
void writeValue(in string aPrefix);
void poke(in string aValue);

nsSample.cpp

包含了 nsISample.idl 中宣告了的所有方法。 SampleImpl 從 nsISample.h 中繼承而來，的標頭是動態從 xpidl 中創建而來的。屬性值已經展開進一個 get 和 set 還有 return 的值會改變 NS_IMETHOD，一個成功的狀態給這個方法。巨集 NS_DECL_ISUPPORTS定義在這個方法裡。巨集 NS_DECL_ISUPPORTS定義在 mozilla/xpcom/public/nsISupportsUtils.h 裡，定義了那些從 nsISupports.h 來的方法。 * NS_IMPL_ISUPPORTS1(SampleImpl, nsISample) 在這個建構子裡面， NS_INIT_REFCNT 巨集被設做 0。

要注意因為在 C++ 裡面用 InterCaps Style 來撰寫，所以 IDL 還有 Javascript 跟著使用這樣的命名方式，除了

QueryInterface nsSampleFactory.cpp

這就是那個建立 nsSample 類別的 class。 ... 為了增加程式碼的可攜性，COM framework 用了 factories 來建立應用功能的實體，而不是直接應用這些實體自已本身。這個 factory 是從 nsFactory 繼承來的，它也同樣是一個 XPCOM 物件。想知道更多有關 factory 的資訊，可以參考這裡：

generic factory document Modularization techniques document

nsSample.js 這個 javascript 檔案用 factory glue 來動作 nsISample 裡面的功能。

Compiling the idl

XPIDL 編譯器 (在 windows 上面也有 xpidl.exe 在 Mac 上面用CodeWarrior外掛也行) 如果你想在 mozilla 上面測試上面說的東西的話，你用得上這個東西。

如果你之前有編過 mozila ，那它會在 mozilla\dist\WIN32_D.OBJ\bin\xpidl.exe

使用的指令大概是： D:\mozilla\xpcom\sample>d:\mozilla\dist\WIN32_D.OBJ\bin\xpidl -I d:\mozilla\dist\idl -m header nsISample.idl

• -I d:\mozilla\dist\idl 要指到有 idl 檔案的目錄夾。因為 nsISample.idl 是從 nsISupports.idl 繼承來的緣故，所以要配合它的需要。
• -m header 表示要建立 C++ 的標頭檔，它會做出以 .xpt 為副檔名的型別函式庫的檔案

更多有關 compile 的資訊可以參考這裡： xpidl compiler page

建立 Sample XPConnect 物件

• 要建立 sample 可以直接在 mozilla\xpcom\sample 下：

 d:\mozilla\xpcom\sample>nmake /f makefile.win

當然，要做上面的動作之前你得先確保你的環境已經設定 ok 了，不然你也可以參考一下這裡： Build，應該可以給你更多的資訊。

把這個 Sample 跑起來 !!

如果你是用 Mozilla 的話，你可以把這個 URL 載入先：resource://res/samples/xpconnect-sample.html (當然，也有一個可能就是你現在正在讀的這個頁面啦~) 當你按下 "write" 按鈕時，你留心 console 底下的反應，應該都合乎在 nsSample.cpp 裡面的定義。