一、前言

　　1、如果你在使用 vc5.0 及以前的版本，請你升級為 vc6.0 或 vc.net 2003；
　　2、如果你在使用 vc6.0 (ATL 3.0)請閱讀本回內容；
　　3、如果你在使用 vc.net(ATL 7.0)請閱讀下回內容；(當然讀讀本文內容也不錯)
　　4、這第一個組件，除了所有 COM 組件必須的 IUnknown 接口外，我們再實現一個自己定義的接口 IFun，它有兩個函數： Add()完成兩個數值的加法，Cat()完成兩個字符串的連接。
　　5、下面......好好聽講! 開始了:-)

二、建立 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，它代表什么那？簡單地說：當在線程中調用組件函數的時候，這些調用會排隊進行。因此，這種模式下，我們可以暫時不用考慮同步的問題。(注1)
　　 Interface 接口基本類型。Dual 表示支持雙接口(注2)，這個非常 非常重要，非常非常常用，但我們今天不講。Custom 表示自定義借口。切記！切記！我們的這第一個 COM 程序中，一定要選擇它！！！！（如果你選錯了，請刪除全部內容，重新來過。）
　　 Aggregation 我們寫的組件，將來是否允許被別人聚合(注3)使用。Only 表示必須被聚合才能使用，有點類似 C++ 中的純虛類，你要是總工程師，只負責設計但不親自寫代碼的話，才選擇它。
　　Support ISupportErrorInfo 是否支持豐富信息的錯誤處理接口。以后就講。
　　Support Connection Points 是否支持連接點接口（事件、回調）。以后就講。
　　Free Threaded Marshaler 以后也不講，就算打死你，我也不說！(注4)


四、添加接口函數


圖五、調出增加接口方法的菜單


圖六、增加接口函數 Add


圖七、增加接口函數 Cat

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

圖八、接口函數定義完成后的圖示
　　我們都知道，要想改變 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 指針剝離，這個函數由于沒有復制過程，因此速度稍微快一點點。但要注意，一但剝離后，就不能再使用該對象啦。
學生：老師，您講的太牛啦，我對您的敬仰如巍巍泰山，直入云霄......
老師：STOP，STOP！留作業啦......
　　 1、自己先按照今天講的內容寫出這個組件；
　　 2、不管你懂不懂，一定要去觀察 IDL 文件，CPP 文件；
　　 3、編譯后，看都產生了些什么文件？如果是文本的文件，就打開看看；
　　 4、下載本文的示例程序(vc6.0版本)編譯運行，看看效果。然后預習一下示例程序中的調用方法；
學生：知道啦，快下課吧，我要上廁所，我都憋的不行了......
老師：下課！別忘了頂我的帖子呀......


六、小結

　　本回介紹第一個ATL組件程序的建立步驟，而如何使用該組件，敬請關注《COM 組件設計與應用(七)》。
　

---

注1：Apartment，系統通過隱藏的窗口消息來排隊組件調用，因此我們可以暫時不考慮同步問題。注意，是暫時哈。
注2：雙接口表示在一個接口中，同時支持自定義接口和 IDispatch 接口。以后，以后，以后就講。因為雙接口非常重要，我們以后會天天講、夜夜講、常常講------簡稱“三講”:)
注3：組件的重用方法有2個，聚合和包容。
注4：名稱的功能很好聽，但微軟根本就沒有實現。
注5：這些都是 IDL 文件中的概念，以后用到什么，就介紹什么。