COM_INTERFACE_ENTRY宏

發行項
08/03/2024

這些宏會在物件的 COM 對應中輸入物件的介面，以便由 QueryInterface存取它們。 COM 對應中項目的順序是順序介面會在期間 QueryInterface檢查是否有相符的 IID。

Macro	描述
COM_INTERFACE_ENTRY	在 COM 介面對應中輸入介面。
COM_INTERFACE_ENTRY2	使用此巨集來釐清兩個繼承分支。
COM_INTERFACE_ENTRY_IID	使用此巨集將介面輸入 COM 對應，並指定其 IID。
COM_INTERFACE_ENTRY2_IID	與 COM_INTERFACE_ENTRY2相同，不同之處在於您可以指定不同的 IID。
COM_INTERFACE_ENTRY_AGGREGATE	當查詢 iid 所識別的介面時，`COM_INTERFACE_ENTRY_AGGREGATE`會轉送至 `punk`。
COM_INTERFACE_ENTRY_AGGREGATE_BLIND	與 COM_INTERFACE_ENTRY_AGGREGATE相同，不同之處在於查詢任何 IID 會導致將查詢轉送至 punk。
COM_INTERFACE_ENTRY_AUTOAGGREGATE	與COM_INTERFACE_ENTRY_AGGREGATE相同，除非 punk 為 NULL，否則會自動建立 clsid 所描述的匯總。
COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND	與COM_INTERFACE_ENTRY_AUTOAGGREGATE相同，不同之處在於查詢任何 IID 會導致將查詢轉送至 punk，如果 punk 為 NULL，則會自動建立 clsid 所描述的匯總。
COM_INTERFACE_ENTRY_BREAK	讓程式在查詢指定的介面時呼叫 DebugBreak 。
COM_INTERFACE_ENTRY_CACHED_TEAR_OFF	儲存每個實例的介面特定數據。
COM_INTERFACE_ENTRY_TEAR_OFF	公開您的卸除介面。
COM_INTERFACE_ENTRY_CHAIN	當處理到達 COM 對應中的這個專案時，處理基類的 COM 對應。
COM_INTERFACE_ENTRY_FUNC	連結至 ATL 邏輯的 `QueryInterface` 一般機制。
COM_INTERFACE_ENTRY_FUNC_BLIND	與 COM_INTERFACE_ENTRY_FUNC相同，不同之處在於查詢任何 IID 會導致呼叫 func。
COM_INTERFACE_ENTRY_NOINTERFACE	傳回E_NOINTERFACE，並在查詢指定的介面時終止 COM 對應處理。

需求

標頭： atlcom.h

COM_INTERFACE_ENTRY

在 COM 介面對應中輸入介面。

語法

COM_INTERFACE_ENTRY( x )

參數

x
[in]類別物件衍生自的介面名稱。

備註

一般而言，這是您最常使用的項目類型。

範例

BEGIN_COM_MAP(CThisExample)
   COM_INTERFACE_ENTRY(IThisExample)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()

需求

標頭： atlcom.h

COM_INTERFACE_ENTRY2

使用此巨集來釐清兩個繼承分支。

COM_INTERFACE_ENTRY2(x, x2)

參數

x
[in]您要從物件公開的介面名稱。

x2
[in]公開 x 之繼承分支的名稱。

備註

例如，如果您從兩個雙重介面衍生類別物件，您可以使用 COM_INTERFACE_ENTRY2 公開 IDispatch ，因為 IDispatch 可以從其中一個介面取得。

範例

class ATL_NO_VTABLE CEntry2Example :
   public CEntry2ExampleBase, // CEntry2ExampleBase derives from IDispatch
   public IDispatchImpl<IEntry2Example, &IID_IEntry2Example, &LIBID_NVC_ATL_WindowingLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public CComCoClass<CEntry2Example, &CLSID_Entry2Example>
{
public:
   CEntry2Example()
   {
   }

BEGIN_COM_MAP(CEntry2Example)
   COM_INTERFACE_ENTRY(IEntry2Example)
   COM_INTERFACE_ENTRY2(IDispatch, IEntry2Example)
END_COM_MAP()
};

COM_INTERFACE_ENTRY_IID

使用此巨集將介面輸入 COM 對應，並指定其 IID。

COM_INTERFACE_ENTRY_IID(iid, x)

參數

iid
[in]公開之介面的 GUID。

x
[in]類別的名稱，其 vtable 將會公開為 iid 所識別的介面。

範例

BEGIN_COM_MAP(CExample)
   COM_INTERFACE_ENTRY(IExample)
   COM_INTERFACE_ENTRY_IID(IID_IDispatch, CExampleDispatch)
   COM_INTERFACE_ENTRY(IExampleBase)
   COM_INTERFACE_ENTRY(ISupportErrorInfo)
END_COM_MAP()

COM_INTERFACE_ENTRY2_IID

與 COM_INTERFACE_ENTRY2相同，不同之處在於您可以指定不同的 IID。

COM_INTERFACE_ENTRY2_IID(iid, x, x2)

參數

iid
[in]您為介面指定的 GUID。

x
[in]類別物件直接衍生自的介面名稱。

x2
[in]類別物件直接衍生自的第二個介面名稱。

COM_INTERFACE_ENTRY_AGGREGATE

當查詢 iid 所識別的介面時，COM_INTERFACE_ENTRY_AGGREGATE會轉送至 punk。

COM_INTERFACE_ENTRY_AGGREGATE(iid, punk)

參數

iid
[in]查詢介面的 GUID。

朋克
[in]指標的名稱 IUnknown 。

備註

punk 參數假設指向匯總的內部未知或 NULL，在此情況下會忽略專案。一般而言，您會 CoCreate 在中 FinalConstruct匯總。

範例

BEGIN_COM_MAP(COuter1)
   COM_INTERFACE_ENTRY_AGGREGATE(__uuidof(IAgg), m_punkAgg)
END_COM_MAP()

COM_INTERFACE_ENTRY_AGGREGATE_BLIND

與 COM_INTERFACE_ENTRY_AGGREGATE相同，不同之處在於查詢任何 IID 會導致將查詢轉送至 punk。

COM_INTERFACE_ENTRY_AGGREGATE_BLIND(punk)

參數

朋克
[in]指標的名稱 IUnknown 。

備註

如果介面查詢失敗，COM 對應處理會繼續。

範例

BEGIN_COM_MAP(COuter2)
   COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_punkAggBlind)
END_COM_MAP()

COM_INTERFACE_ENTRY_AUTOAGGREGATE

與COM_INTERFACE_ENTRY_AGGREGATE相同，除非 punk 為 NULL，否則會自動建立 clsid 所描述的匯總。

COM_INTERFACE_ENTRY_AUTOAGGREGATE(iid, punk, clsid)

參數

iid
[in]查詢介面的 GUID。

朋克
[in]指標的名稱 IUnknown 。必須是包含 COM 對應之類別的成員。

clsid
[in]如果 punk 為 NULL，將會建立之匯總的標識碼。

備註

範例

BEGIN_COM_MAP(COuter3)
   COM_INTERFACE_ENTRY_AUTOAGGREGATE(__uuidof(IAutoAgg), m_punkAutoAgg, CLSID_CAutoAgg)
END_COM_MAP()

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND

與COM_INTERFACE_ENTRY_AUTOAGGREGATE相同，不同之處在於查詢任何 IID 會導致將查詢轉送至 punk，如果 punk 為 NULL，則會自動建立 clsid 所描述的匯總。

COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(punk, clsid)

參數

朋克
[in]指標的名稱 IUnknown 。必須是包含 COM 對應之類別的成員。

clsid
[in]如果 punk 為 NULL，將會建立之匯總的標識碼。

備註

如果介面查詢失敗，COM 對應處理會繼續。

範例

BEGIN_COM_MAP(COuter4)
   COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND(m_punkAutoAggB, CLSID_CAutoAggB)
END_COM_MAP()

COM_INTERFACE_ENTRY_BREAK

讓程式在查詢指定的介面時呼叫 DebugBreak 。

COM_INTERFACE_ENTRY_BREAK(x)

參數

x
[in]用來建構介面標識碼的文字。

備註

介面 IID 會藉由將 x 附加至 IID_來建構。例如，如果 x 是 IPersistStorage，則 IID 會是 IID_IPersistStorage。

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF

儲存每個實例的介面特定數據。

COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(iid, x, punk)

參數

iid
[in]卸除介面的 GUID。

x
[in]實作介面的類別名稱。

朋克
[in]指標的名稱 IUnknown 。必須是包含 COM 對應之類別的成員。應該在類別物件的建構函式中初始化為 NULL。

備註

如果未使用介面，這會降低對象的整體實例大小。

範例

BEGIN_COM_MAP(COuter)
   COM_INTERFACE_ENTRY(IOuter)
   COM_INTERFACE_ENTRY_CACHED_TEAR_OFF(IID_ITearOff, CTearOff, punkTearOff)
END_COM_MAP()

COM_INTERFACE_ENTRY_TEAR_OFF

公開您的卸除介面。

COM_INTERFACE_ENTRY_TEAR_OFF(iid, x)

參數

iid
[in]卸除介面的 GUID。

x
[in]實作介面的類別名稱。

備註

卸除介面會實作為個別物件，每次查詢它所代表的介面時，就會具現化該物件。一般而言，如果介面很少使用，您就會將介面建置為卸除，因為這會將 vtable 指標儲存在主要物件的每個實例中。當參考計數變成零時，就會刪除卸除。實作卸除的類別應該衍生自 CComTearOffObjectBase 並有自己的 COM 對應。

範例

BEGIN_COM_MAP(CBeeper)
   COM_INTERFACE_ENTRY(IBeeper)
   COM_INTERFACE_ENTRY(IDispatch)
   COM_INTERFACE_ENTRY_TEAR_OFF(IID_ISupportErrorInfo, CBeeper2)
END_COM_MAP()

COM_INTERFACE_ENTRY_CHAIN

當處理到達 COM 對應中的這個專案時，處理基類的 COM 對應。

COM_INTERFACE_ENTRY_CHAIN(classname)

參數

classname
[in]目前物件的基類。

備註

例如，在下列程式代碼中：

BEGIN_COM_MAP(COuterObject)
   COM_INTERFACE_ENTRY2(IDispatch, IOuterObject)
   COM_INTERFACE_ENTRY_CHAIN(CBase)
END_COM_MAP()

請注意，COM 對應中的第一個項目必須是包含 COM 對應之物件的介面。因此，您無法使用 COM_INTERFACE_ENTRY_CHAIN 來啟動 COM 對應專案，這會導致在物件 COM 對應中出現COM_INTERFACE_ENTRY_CHAIN（COtherObject） 的點搜尋不同物件的 COM 對應。如果您想要先搜尋另一個物件的 COM 對應，請將的 IUnknown 介面專案新增至 COM 對應，然後鏈結另一個物件的 COM 對應。例如：

BEGIN_COM_MAP(CThisObject)
   COM_INTERFACE_ENTRY(IUnknown)
   COM_INTERFACE_ENTRY_CHAIN(CBase)
END_COM_MAP()

COM_INTERFACE_ENTRY_FUNC

連結至 ATL 邏輯的 QueryInterface 一般機制。

COM_INTERFACE_ENTRY_FUNC(iid, dw, func)

參數

iid
[in]公開之介面的 GUID。

dw
[in]傳遞至 func 的參數。

func
[in]將傳回 iid 的函式指標。

備註

如果 iid 符合查詢介面的 IID，則會呼叫 func 指定的函式。函式的宣告應該是：

HRESULT WINAPI func(void* pv, REFIID riid, LPVOID* ppv, DWORD_PTR dw);

呼叫函式時， pv 會指向您的類別物件。 riid 參數是指要查詢的介面，ppv是函式應儲存介面指標至介面的位置指標，而 dw 是您在專案中指定的參數。如果函式選擇不傳回介面，函式應將 * ppv 設定為 NULL，並傳回E_NOINTERFACE或S_FALSE。 E_NOINTERFACE時，COM 對應處理會終止。使用S_FALSE時，即使未傳回介面指標，COM 地圖處理仍會繼續。如果函式傳回介面指標，它應該會傳回S_OK。

COM_INTERFACE_ENTRY_FUNC_BLIND

與 COM_INTERFACE_ENTRY_FUNC相同，不同之處在於查詢任何 IID 會導致呼叫 func。

COM_INTERFACE_ENTRY_FUNC_BLIND(dw, func)

參數