#import 指令

C++特殊處

#import指令用于從一個類型庫中結合信息。該類型庫的內容被轉換為C++類,主要用于描述COM界面。

語法

#import "文件名" [屬性]

#import <文件名> [屬性]

屬性:

屬性1,屬性2,...

屬性1 屬性2 ...

文件名是一個包含類型庫信息的文件的名稱。一個文件可為如下類型之一:

* 一個類型庫(.TLB或.ODL)文件。

* 一個可執行(.EXE)文件。

* 一個包含類型庫資源(如.OCX)的庫文件(.DLL)。

* 一個包含類型庫的復合文檔。

* 其它可被LoadTypeLib API支持的文件格式。

文件名之前可以有一個目錄規格。文件名必須是一個已存在文件的名稱。兩種格式的區別是當路徑未完全說明時,預處理器檢索類型庫文件的順序不同。

動作

語法格式

引號格式 這種格式讓預處理器首先搜索與包含#import語句的文件同一目錄的類型庫文件,然后在所有包括(#include)該文件的目錄中搜索,最后在如下路徑中搜索

尖括號格式 這種格式指示預處理器沿以下路徑搜索類型庫文件

編譯器在以下目錄中搜索已命名的文件:

1. PATH環境變量路徑表。

2. LIB環境變量路徑表。

3. 用/I(額外的包括目錄)編譯器選項指定的路徑。#import可以任選地包含一個或多個屬性。這些屬性使編譯器改變類型庫頭文件的內容。一個反斜杠(\)符可用在一個單一的#import語句中包含額外的行,例如:

#import "test.lib" no_namespace \

rename("OldName","NewName")

#import屬性列出如下:

exclude	high_method_prefix
high_property_prefixes	implementation_only
include(...)	inject_statement
named_guids	no_auto_exclude
no_implementation	no_namespace
raw_dispinterfaces	raw_interfaces_only
raw_method_prefix	raw_native_types
raw_property_prefixes	rename
rename_namespace

#import指令可創建兩個在C++源代碼中重構類型庫內容的頭文件,第一個頭文件和用Microsoft接口定義語言(MIDL)編譯器生成的頭文件類似,但有額外的編譯器生成代碼和數據。第一個頭文件與類型庫有相同的基本名,其擴展名為.TLH。第二個頭文件也有與類型庫相同的基本名,其擴展名為.TLI。它包括了編譯器生成成員函數的實現,且被包含在(#include)的第一個頭文件內。

兩個頭文件都在用/Fo(命名對象文件)選項指定的輸出目錄中。隨后它們被讀出和編譯,就像第一個頭文件被#include指令命名一樣。

以下是伴隨#import指令的編譯器優化:

* 頭文件被創建時,將被分配與類庫相同的時間標志。

* 處理#import時,編譯器首先測試頭文件是否存在,是否過期。若條件為真,就不需重新創建。

* 編譯器延遲對于OLE子系統的初始化,直到碰到第一個#import命令。

#import指令也可參與最小重建且可被置于一個預編譯頭文件中。

基本類型庫頭文件

基本類型庫頭文件由七個部分組成:

1. 頭部固定正文:由注釋、COMDEF.H(定義用在頭部的一些標準宏)的#include語句和其它繁雜的安裝信息組成。

2.前向引用和類型定義:由象struct IMyinterface之類的結構說明和用于一些TKIND_ALIAS項的類型定義組成。

3.靈敏指針說明:模塊類_com_ptr_t是一個封裝接口指針和消除調用AddRef、Release 和QueryInterface函數需求的靈敏指針實現。此外,它隱藏了創建一個新COM對象中的CoCreateInstance調用。此部分采用宏語句_COM_SMARTPTR_TYPEDEF將COM接口的類型定義創建為_com_ptr_t模板類的模板特例化。例如,對于界面IFoo,.TLH文件包含有:

_COM_SMARTPTR_TYPEDEF(IFoo,_ _uuidof(IFoo));

編譯器將其擴展為:type def _com_ptr_t<_com_IIID<IFoo,_ _uuidof(IFoo) >> IFooPtr;

類型IFooPtr可以用在原始的界面指針IFoo*的地方。結果,就不需調用各種IUnknown成員函數。

4. 類型信息(typeinfo)說明:主要由類定義和其它項組成,這些項說明由ITyptLib:GetTypeInfo返回的單個的信息類型項目。在這部分,每個來自于類型庫的信息類型都以一種依賴于TYPEKIND信息的格式反映在該頭部。

5. 任選舊式GUID定義:包含命名的GUID常量的初始化過程,這些定義是格式CLSID_CoClass和IID_Interface的名稱,與那些由MIDL編譯器產生的類似。

6. 用于第二個類型庫頭部的#include語句。

7. 結尾固定正文:目前包括#pragma pack(pop)。

以上這些部分除頭部固定正文和結尾固定正文部分之外,都被包括在原來的IDL文件中以library語句指定其名稱的名稱空間中。你可以通過用名稱空間顯式限定或包括如下語句從類型庫頭部使用該名稱。

using namespace MyLib

在源代碼的#import語句之后立即

名稱空間可用#import指令的no_namespace屬性來阻止。但阻止的名稱空間可能導致名稱沖突。名稱空間也可用rename_namespace屬性重新換名。

編譯器提供完全路徑給需要依賴當前正在處理的類型庫的任何類型庫。路徑以注釋格式寫入到由編譯器為每個處理的類型庫生成的類型庫頭部(.TLH)。

如果一個類型庫包含了對其它類型庫定義的類型引用,.TLH文件將包括以下注釋:

//

//Cross-referenced type libraries:

//

//#import "c:\path\typelib0.tlb"

//

在#import注釋中的實際文件名是存儲在寄存器中交叉引用的類型庫全路徑。如果你遇到由于省略類型定義的錯誤時,檢查.TLH頭部的注釋,看哪一種依賴類型庫需要先輸入。在編譯該.TLI文件時可能的錯誤有語法錯誤(例如C2143,C2146,C2321)、C2501(缺少說明指示符)或C2433(在數據說明中禁止′inline′)。

你必須確定哪些依賴注釋是不被系統頭部給出的,而是在依賴類型庫的#import指令前的某處給出一個#import指令以消除這些錯誤。

exclude屬性exclude(“稱1”[,“名稱2”,...])

名稱1

被排斥的第一個項

名稱2

被排斥的第二個項(如有必要)

類型庫可能包含在系統頭部或其它類型庫內定義的項的定義。該屬性可用于從生成的類型庫頭文件中排斥這些項。這個屬性可帶任意數目的參量,每個參量是一個被排斥的高級類型庫項目:

high_method_prefix屬性

high_method_prefix("Prefix")

Prefix

被使用的前綴

在缺省的情況下,高級錯誤處理屬性和方法用一個無前綴命名的成員函數來展示。這個名稱來自于類型庫。high_method_prefix屬性說明一個前綴以用于命名這些高級屬性和方法。

high_property_prefixes屬性

high_property_prefixes("GetPrefix，""PutPrefix，""PutRefPrefix")

GetPrefix

用于propget方法的前綴

PutPrefix

用于propput方法的前綴

PutRefPrefix

用于propputref方法的前綴

在缺省情況下,高級錯誤處理方法,如propget、propput和propputref,分別采用以前綴Get、Put和PutRef命名的成員函數來說明。high_property_prefixes屬性用于分別說明這三種屬性方法的前綴。

implementation_only屬性

implementation_only屬性禁止.TLH頭文件(基本頭文件)的生成。這個文件包括了所有用于展示類型庫內容的說明。該.TLI頭文件和wrapper成員函數的實現,將被生成且包含在編譯過程中。

當指定該屬性時,該.TLI頭部的內容將和用于存放普通.TLH頭部的內容放在相同的名稱空間。此外,該成員函數不會作為聯編說明。implementation_only屬性一般希望與no_implementation屬性配對使用,以跟蹤預編譯頭文件(PCH)之外的實現。一個有no_implementation屬性的#import語句被置于用來創建pch的源區域中,結果PCH將被一些源文件所用。一個帶implementation_only屬性的#import語句隨后被用在PCH區域之外。在一個源文件里只需用一次這種語句。這將生成不需對每個源文件進行額外重編譯的所有必要的wrapper成員函數。

注意:一個#import語句中的implementation_only屬性必須和相同類型庫中no_implementation屬性的另一個#import語句配套使用。否則,將產生編譯錯誤。這是因為帶no_implementation屬性的#import語句生成的wrapper類定義需要編譯implementation_only屬性生成的語句實現。

include(...)屬性

Include(名稱1[,名稱2,...])

名稱1

第一個被強制包含的項

名稱2

第二個被強制包含的項(如果必要)

類型庫可能包含在系統頭部或其它類型庫中定義的項的定義。#import指令試圖用自動排斥這些項來避免多重定義錯誤。若這些項已經被排斥,象警告C4192所指出的那樣,且它們不應該被排斥,則這個屬性可用于禁止自動排斥。該屬性可帶任意數目的參量,每個參量應是被包括的類型庫項的名稱。

inject_statement屬性

inject_statement("source_text")

source_text

被插入到類型庫頭文件的源文本。

inject_statement屬性將其參量作為源文本插入類型庫頭部。此文本被置于包括頭文件中類型庫內容的名稱空間說明的起始處。

named_guids屬性

named_guids屬性讓編譯器定義和初始化模板LIBID_MyLib、CLSID_MyCoClass、IID_MyInterface和DIID_MyDispInterface的舊式格式的GUID變量。

no_implementation屬性

該屬性阻止.TLI頭文件的生成,這個文件包含wrapper成員函數的實現。如果指定這個屬性,則展示類型庫項說明的.TLH頭將生成沒有一個#include語句包括該.TLI頭文件。

該屬性與implementation_only屬性配套使用。

no_auto_exclude屬性

類型庫可能包括在系統頭部或其它類型庫中定義的項的定義。#import試圖通過自動排斥這些項來避免多重定義錯誤。當這樣做時,每個被排斥的項都將生成一個C4192警告信息。你可禁止這個屬性使用自動排斥。

no_namespace屬性

#import頭文件中的類型庫內容一般定義在一個名稱空間里。名稱空間的名稱在原來IDL文件的library語句中指定。如果指定no_namespace屬性,編譯器就不會生成這個名稱空間。

如果你想使用一個不同的名稱空間,應代替使用rename_namespace屬性。

raw_dispinterfaces屬性

raw_dispinterfaces屬性讓編譯器生成一個低級wrapper函數。該函數用于調用IDispatch::Invoke和返回HRESULT錯誤代碼的dispinterface方法和屬性。如果未指定此屬性,則只生成高級wrapper,它在失敗時丟棄該C++異常。

raw_interfaces_only屬性

raw_interfaces_only屬性禁止生成錯誤處理wrapper函數以及使用這些wrapper函數的_ _declspec(屬性)說明。

raw_interfaces_only屬性也導致刪除在命名non__property函數中的缺省前綴。通常該前綴是raw_。若指定此屬性,函數名稱將直接從類型庫中生成。該屬性只允許展示類型庫的低級內容。

raw_method_prefix屬性

raw_method_prefix("Prefix")

Prefix

被使用的前綴

用raw_作為缺省前綴的成員函數展示低層屬性和方法,以避免與高級錯誤處理成員函數的名稱沖突。raw_method_prefix屬性用于指定一個不同的前綴。注意: raw_method_prefix屬性的效果不會因raw_method_prefix屬性的存在而改變。在說明一個前綴時,raw_method_prefix總是優先于raw_interfaces_only。若兩種屬性用在同一個#import語句中時,則采用raw_method_prefix指定的前綴。

raw_native_types屬性

在缺省情況下,高級錯誤處理方法在BSTR和VARIANT數據類型和原始COM界面指針的地方使用COM支持類_bctr_t和_variant_t。這些類封裝了分配和取消分配這些數據類型的存儲器存儲的細節,并且極大地簡化了類型造型和轉換操作。raw_native_types屬性在高級wrapper函數中禁止使用這些COM支持類,并強制替換使用低級數據類型。

raw_property_prefix屬性

raw_property_prefix("GetPrefix","PutPrefix","PutRefPrefix")

GetPrefix

用于propget方法的前綴

PutPrefix

用于propput方法的前綴

PutRefPrefix

用于propputref方法的前綴

在缺省情況下,低級方法propget、propput和propputref分別用后綴為get_、put_和putref_的成員函數來展示。這些前綴與MIDL生成的頭文件中的名稱是兼容的。raw_property_prefixes屬性分別用于說明這三個屬性方法的前綴。

rename屬性

rename("OldName，""NewName")

OldName

類型庫中的舊名

NewName

用于替換舊名的名稱

rename屬性用于解決名稱沖突的問題。若該屬性被指定,編譯器將在類型庫中的OldName的所有出現處用結果頭文件中用戶提供的NewName替換。

此屬性用于類型庫中的一個名稱和系統頭文件中的宏定義重合時。若這種情況未被解決,則將產生大量語法錯誤,如C2059和C2061。

注意:這種替換用于類型庫的名稱,而不是用于結果頭文件中的名稱。

這里有一個例子:假設類型庫中有一個名稱為MyParent的屬性,且頭文件中定義了一個用在#import之前的宏GetMyParent。由于GetMyParent是用于錯誤處理屬性get的一個wrapper函數的缺省名稱,所以將產生一個名稱沖突。為解決這個問題,使用#import語句中的以下屬性:

rename("MyParent","MyParentX")

該語句將重新命名類型庫中的名稱MyParent,而試圖重新命名GetMyParentwrapper名稱將會出錯:

rename("GetMyParent","GetMyParentX")

這是因為名稱GetMyParent只出現在結果類型庫頭文件中。

rename_namespace屬性

rename_namespace("NewName")

NewName

名稱空間的新名稱

rename_namespace屬性用于重新命名包含類型庫內容的名稱空間。它帶有一個指定名稱空間新名newname的參量。

消除名稱空間可以使用no_namespace屬性。

C++特殊處結束