第一個 COM 程式例子

一、前言

　　1、IDE ： vc6.0 (ATL 3.0)請閱讀本回內容；

       2、這第一個組件，除了所有 COM 組件必須的 IUnknown 介面外，我們再實現一個自己定義的介面 IFun，它有兩個函數： Add()完成兩個數值的加法，Cat()完成兩個字串的串連。

　　二、建立 ATL 工程

　　步驟2.1：建立一個工作區(WorkSpace)。

　　步驟2.2：在工作區中，建立一個 ATL 工程(Project)。樣本程式叫 Simple1，並選擇DLL方式，見圖一。

圖一、建立 ATL DLL 工程

　　Dynamic Link Library(DLL) 表示建立一個 DLL 的組件程式。

　　Executable(EXE) 表示建立一個 EXE 的組件程式。

　　Service(EXE) 表示建立一個服務程式，系統啟動後就會載入並執行的程式。

　　Allow merging of proxy/stub code 選擇該項表示把“代理/存根”代碼合并到組件程式中，否則需要單獨編譯，單獨註冊代理存根程式。代理/存根，這個是什麼概念？還記得我們在上回書中介紹的嗎？當調用者調用進程外或遠程組件功能的時候，其實是代理/存根負責資料交換的。關於代理/存根的具體變成和操作，以後再說啦......

　　Support MFC 除非有特殊的原因，我們寫 ATL 程式，最好不要選擇該項。你可能會說，如果沒有MFC的支援，那CString怎麼辦呀？告訴你個秘密吧，一般人我都不告訴他，我後半輩子就靠著這個秘密活著了：

　　1、你會STL嗎？可以用 STL 中的 string 代替；

　　2、自己寫個 MyString 類，嘿嘿；

　　3、悄悄地、秘密地、不要告訴別人（特別是別告訴微軟），把 MFC 中的 CString 源碼拿過來用；

　　4、使用 CComBSTR 類，至少也能簡化我們字串操作；

　　5、直接用 API 操作字串，反正我們大家學習 C 語言的時候，都是從這裡幹起的。（等於沒說，呵呵）

　　Support MTS 支援交易處理，也就是是否支援 COM+ 功能。COM+ 也許在第 99 回介紹吧。

　　三、增加 ATL 對象類

　　步驟3.1：菜單 Insert\New ATL Object...（或者用滑鼠右鍵在 ClassView 卡片中快顯功能表）並選擇Object 分類，選中 Simple Object 項目。見圖二。

圖二、選擇建立簡單COM對象

Category Object 普通組件。其中可以選擇的組件物件類型很多，但本質上，就是讓嚮導幫我們預設加上一些介面。比如我們選 "Simple Object"，則嚮導給我們的組件加上 IUnknown 介面；我們選 "Internet EXPlorer Object"，則嚮導除了加上 IUnknown 介面外，再增加一個給 IE 所使用的 IObjectWithSite 介面。當然了，我們完全可以手工增加任何介面。

　　Category Controls ActiveX 控制項。其中可以選擇的 ActiveX 類型也很多。我們在後續的專門介紹 ActiveX 編程中再討論。

　　Category Miscellaneous 輔助雜類組件。

　　Categroy Data Access 資料庫類組件(我最討厭資料庫編程了，所以我也不會)。

　　步驟3.2：增加自訂類 CFun(介面 IFun) ,見圖三。

圖三、輸入類中的各項名稱

　　 其實，我們只需要輸入短名(Short Name)，其它的項目會自動填寫。沒什麼多說的，只請大家注意一下 ProgID 項，預設的 ProgID 構造方式為“工程名.短名”。

　　 步驟3.3：填寫介面屬性，見圖四。

圖四、介面屬性

　　Threading Model 選擇組件支援的執行緒模式。COM 中的線程，我認為是最討厭，最複雜的部分。COM 線程和公寓的概念，留待後續介紹。現在嗎......大家都選 Apartment，它代表什麼那？簡單地說：當線上程中調用組件函數的時候，這些調用會排隊進行。因此，這種模式下，我們可以暫時不用考慮同步的問題。

　　 Interface 介面基本類型。Dual 表示支援雙介面，這個非常 非常重要，非常非常常用，但我們今天不講。Custom 表示自訂借口。切記！切記！我們的這第一個
COM 程式中，一定要選擇它！！！！（如果你選錯了，請刪除全部內容，重新來過。）

　　 Aggregation 我們寫的組件，將來是否允許被別人彙總使用。Only 表示必須被彙總才能使用，有點類似 C++ 中的純虛類，你要是總工程師，只負責設計但不親自寫代碼的話，才選擇它。

　　Support ISupportErrorInfo 是否支援豐富資訊的錯誤處理介面。以後就講。

　　Support Connection Points 是否支援連接點介面（事件、回調）。以後就講。

　　Free Threaded Marshaler 以後也不講，就算打死你，我也不說！

　　四、添加介面函數


圖五、調出增加介面方法的菜單

圖六、增加介面函數 Add 進入討論群組討論。

圖七、增加介面函數 Cat

　　請嚴格按照圖六的方式，增加Add()函數；由於圖七中增加Cat()函數的參數比較長，我沒有適當的輸入空格，請大家自己輸入的時候注意一下。[in]表示參數方向是輸入；[out]表示參數方向是輸出；[out,retval]表示參數方向是輸出，同時可以作為函數運算結果的傳回值。一個函數中，可以有多個[in]、[out]，但[retval]只能有一個，並且要和[out]組合後在最後一個位置。



圖八、介面函數定義完成後的圖示

　　我們都知道，要想改變 C++ 中的類函數，需要修改兩個地方：一是標頭檔(.h)中類的函式宣告，二是函數體(.cpp)檔案的實現處。而我們現在用 ATL 寫組件程式，則還要修改一個地方，就是介面定義(IDL)檔案。別著急 IDL 下次就要討論啦。

　　由於 vc6.0 的BUG，導致大家在增加完介面和介面函數後，可能不會向（圖八）所表現的樣式。解決方案：
　 1 關閉工程，然後重新開啟該方法常常有效 2 關閉 IDE，然後重新運行　 3 開啟 IDL 檔案，檢查介面函數是否正確，如不正確請修改　 4 開啟 IDL 檔案，隨便修改一下(加一個空格，再刪除這個空格)，然後儲存該方法常常有效 5 開啟 h/cpp 檔案，檢查函數是否存在或是否正確，有則改之無則嘉勉，不說完這個成語心理彆扭
6 刪除 IDL/H/CPP 中的介面函數，然後再來一遍 7 重建立立工程、重新安裝vc、重新安裝windows、砸電腦砸！

　　五、實現介面函數

　　滑鼠雙點圖八中CFun\IFun\Add(...)就可以開始輸入函數實現了：

STDMETHODIMP CFun::Add(long n1, long n2, long *pVal) { *pVal = n1 + n2; return S_OK; }　　這個太簡單了，不再浪費“口條”。下面我們實現字串串連的Cat()函數：STDMETHODIMP CFun::Cat(BSTR s1,
BSTR s2, BSTR *pVal) { int nLen1 = ::SysStringLen( s1 ); // s1 的字元長度 int nLen2 = ::SysStringLen( s2 ); // s2 的字元長度 *pVal = ::SysAllocStringLen( s1, nLen1 + nLen2 ); // 構造新的 BSTR 同時把 s1 先儲存進去 if( nLen2 ) { ::memcpy( *pVal + nLen1, s2, nLen2 * sizeof(WCHAR)
); // 然後把 s2 再串連進去 // wcscat( *pVal, s2 ); } return S_OK; }　　學生：上面的函數實現，完全是調用基本的 API 方式完成的。

　　老師：是的，說實話，的確比較煩瑣。

　　學生：我們是用memcpy()完成串連第二個字串功能的，那麼為什麼不用函數 wcscat()那？
老師：多數情況下可以，但你需要知道：由於BSTR包含有字串長度，因此實際的BSTR字串內容中是可以儲存L’’\0’’的，而函數 wcscat() 是以L’’\0’’作為複製結束標誌，因此可能會遺失資料。明白了嗎？

　　學生：明白，明白。我看過《COM 組件設計與應用之資料類型》後就明白了。那麼老師，有沒有簡單一些的方法那？

　　老師：有呀，你看......STDMETHODIMP CFun::Cat(BSTR s1, BSTR s2, BSTR *pVal) { CComBSTR sResult( s1 ); sResult.AppendBSTR( s2 ); *pVal = sResult.Copy(); // *pVal
= sResult.Detach(); return S_OK; }　　學生：哈哈，好！使用了 CComBSTR，這個就簡單多了。CComBSTR::Copy()和CComBSTR::Detach()有什麼區別？

　　老師：CComBSTR::Copy() 會製造一個 BSTR 的副本，另外CComBSTR::CopyTo()也有類似功能。而CComBSTR::Detach()是使對象與內部的 BSTR 指標剝離，這個函數由於沒有複製過程，因此速度稍微快一點點。但要注意，一但剝離後，就不能再使用該對象啦。