分派對應

發行項
08/04/2024

OLE Automation 提供方法呼叫方法，以及存取跨應用程式的屬性。 Microsoft基礎類別庫為分派這些要求所提供的機制是「分派對應」，可指定物件函式和屬性的內部和外部名稱，以及屬性本身和函式自變數的數據類型。

分派對應巨集	描述
DECLARE_DISPATCH_MAP	宣告分派對應將用來公開類別的方法和屬性（必須在類別宣告中使用）。
BEGIN_DISPATCH_MAP	啟動分派對應的定義。
END_DISPATCH_MAP	結束分派對應的定義。
DISP_FUNCTION	用於分派對應，以定義 OLE 自動化函式。
DISP_PROPERTY	定義 OLE 自動化屬性。
DISP_PROPERTY_EX	定義 OLE 自動化屬性，並將 Get 和 Set 函式命名為。
DISP_PROPERTY_NOTIFY	使用通知定義 OLE 自動化屬性。
DISP_PROPERTY_PARAM	定義採用參數和名稱 Get 和 Set 函式的 OLE 自動化屬性。
DISP_DEFVALUE	將現有的屬性設為物件的預設值。

DECLARE_DISPATCH_MAP

CCmdTarget如果您的程式中的衍生類別支援 OLE Automation，該類別必須提供分派對應來公開其方法和屬性。

DECLARE_DISPATCH_MAP()

備註

在類別宣告結尾使用 DECLARE_DISPATCH_MAP 巨集。然後在中。定義類別成員函式的 CPP 檔案，請使用 BEGIN_DISPATCH_MAP 巨集。然後包含每個類別公開方法和屬性的巨集專案（DISP_FUNCTION、DISP_PROPERTY等等）。最後，使用 END_DISPATCH_MAP 巨集。

注意

如果您在DECLARE_DISPATCH_MAP之後宣告任何成員，則必須為其指定新的存取類型（ public、 private或 protected）。

應用程式精靈和程式代碼精靈可協助建立自動化類別和維護分派對應。如需分派對應的詳細資訊，請參閱自動化伺服器。

範例

class CMyServerDoc : public COleServerDoc
{
   DECLARE_DISPATCH_MAP()

   // Remainder of class declaration omitted.

需求

標題: afxwin.h

BEGIN_DISPATCH_MAP

宣告您的分派對應的定義。

BEGIN_DISPATCH_MAP(theClass, baseClass)

參數

theClass
指定擁有此分派對應之類別的名稱。

baseClass
指定Class的基類名稱。

備註

在定義類別成員函式的實作（.cpp）檔案中，使用 BEGIN_DISPATCH_MAP 巨集啟動分派對應、新增每個分派函式和屬性的巨集專案，並使用 END_DISPATCH_MAP 巨集完成分派對應。

需求

標頭： afxdisp.h

END_DISPATCH_MAP

結束您的分派對應的定義。

END_DISPATCH_MAP()

備註

它必須與BEGIN_DISPATCH_MAP搭配使用。

需求

標頭： afxdisp.h

DISP_FUNCTION

在分派對應中定義 OLE 自動化函式。

DISP_FUNCTION(
    theClass,
    pszName,
    pfnMember,
    vtRetVal,
    vtsParams)

參數

theClass
類別的名稱。

pszName
函式的外部名稱。

pfnMember
成員函式的名稱。

vtRetVal
值，指定函式的傳回型別。

vtsParams
一個或多個常數的空間分隔清單，指定函式的參數清單。

備註

vtRetVal 自變數的類型為 VARTYPE。這個自變數的下列可能值取自 VARENUM 列舉：

符號	傳回類型
VT_EMPTY	`void`
VT_I2	`short`
VT_I4	`long`
VT_R4	`float`
VT_R8	`double`
VT_CY	CY
VT_DATE	日期
VT_BSTR	BSTR
VT_DISPATCH	LPDISPATCH
VT_ERROR	SCODE
VT_BOOL	BOOL
VT_Variant	VARIANT
VT_UNKNOWN	LPUNKNOWN

vtsParams 自變數是常數中以空格分隔的值VTS_*清單。以空格分隔的其中一或多個值（不是逗號）會指定函式的參數清單。例如，

VTS_I2 VTS_PI2

指定清單，其中包含簡短整數，後面接著短整數的指標。

VTS_常數及其意義如下：

符號	參數類型
VTS_I2	`short`
VTS_I4	`long`
VTS_R4	`float`
VTS_R8	`double`
VTS_CY	`const CY` 或 `CY*`
VTS_DATE	日期
VTS_BSTR	LPCSTR
VTS_DISPATCH	LPDISPATCH
VTS_SCODE	SCODE
VTS_BOOL	BOOL
VTS_VARIANT	`const VARIANT*` 或 `VARIANT&`
VTS_UNKNOWN	LPUNKNOWN
VTS_PI2	短*
VTS_PI4	長*
VTS_PR4	浮*
VTS_PR8	雙*
VTS_PCY	`CY*`
VTS_PDATE	`DATE*`
VTS_PBSTR	`BSTR*`
VTS_PDISPATCH	`LPDISPATCH*`
VTS_PSCODE	`SCODE*`
VTS_PBOOL	`BOOL*`
VTS_PVARIANT	`VARIANT*`
VTS_PUNKNOWN	`LPUNKNOWN*`
VTS_NONE	無參數

需求

標頭： afxdisp.h

DISP_PROPERTY

在分派對應中定義 OLE 自動化屬性。

DISP_PROPERTY(
    theClass,
    pszName,
    memberName,
    vtPropType)

參數

theClass
類別的名稱。

pszName
屬性的外部名稱。

memberName
屬性儲存所在的成員變數名稱。

vtPropType
值，指定屬性的類型。

備註

vtPropType 自變數的類型為 VARTYPE。此自變數的可能值取自 VARENUM 列舉：

符號	屬性類型
VT_I2	`short`
VT_I4	`long`
VT_R4	`float`
VT_R8	`double`
VT_CY	CY
VT_DATE	日期
VT_BSTR	`CString`
VT_DISPATCH	LPDISPATCH
VT_ERROR	SCODE
VT_BOOL	BOOL
VT_Variant	VARIANT
VT_UNKNOWN	LPUNKNOWN

當外部客戶端變更屬性時，memberName 所指定成員變數的值會變更;不會通知變更。

需求

標頭： afxdisp.h

DISP_PROPERTY_EX

定義 OLE 自動化屬性，並命名用來取得和設定分派對應中屬性值的函式。

DISP_PROPERTY_EX(
    theClass,
    pszName,
    memberGet,
    memberSet,
    vtPropType)

參數

theClass
類別的名稱。

pszName
屬性的外部名稱。

memberGet
用來取得屬性的成員函式名稱。

memberSet
用來設定屬性的成員函式名稱。

vtPropType
值，指定屬性的類型。

備註

memberGet 和 memberSet 函式具有 vtPropType 自變數所決定的簽章。 memberGet 函式不會接受任何自變數，並傳回 vtPropType 所指定的型別值。 memberSet 函式接受 vtPropType 所指定類型的自變數，且不會傳回任何內容。

vtPropType 自變數的類型為 VARTYPE。此自變數的可能值取自 VARENUM 列舉。如需這些值的清單，請參閱 DISP_FUNCTION 中 vtRetVal 參數的。請注意，VT_EMPTY，列在DISP_FUNCTION備註中，不允許做為屬性數據類型。

需求

標頭： afxdisp.h

DISP_PROPERTY_NOTIFY

在分派對應中定義具有通知的 OLE 自動化屬性。

DISP_PROPERTY_NOTIFY(
    theClass,
    szExternalName,
    memberName,
    pfnAfterSet,
    vtPropType)

參數

theClass
類別的名稱。

szExternalName
屬性的外部名稱。

memberName
屬性儲存所在的成員變數名稱。

pfnAfterSet
szExternalName 的通知函式名稱。

vtPropType
值，指定屬性的類型。

備註

不同於使用 DISP_PROPERTY 定義的屬性，以 DISP_PROPERTY_NOTIFY 定義的屬性會在屬性變更時自動呼叫 pfnAfterSet 指定的函式。

vtPropType 自變數的類型為 VARTYPE。此自變數的可能值取自 VARENUM 列舉：

符號	屬性類型
VT_I2	`short`
VT_I4	`long`
VT_R4	`float`
VT_R8	`double`
VT_CY	CY
VT_DATE	日期
VT_BSTR	`CString`
VT_DISPATCH	LPDISPATCH
VT_ERROR	SCODE
VT_BOOL	BOOL
VT_Variant	VARIANT
VT_UNKNOWN	LPUNKNOWN

需求

標頭： afxdisp.h

DISP_PROPERTY_PARAM

定義使用個別 Get 和 Set 成員函式存取的屬性。

DISP_PROPERTY_PARAM(
    theClass,
    pszExternalName,
    pfnGet,
    pfnSet,
    vtPropType,
    vtsParams)

參數

theClass
類別的名稱。

pszExternalName
屬性的外部名稱。

pfnGet
用來取得屬性的成員函式名稱。

pfnSet
用來設定屬性的成員函式名稱。

vtPropType
值，指定屬性的類型。

vtsParams
以空格分隔 VTS_* 的 variant 參數類型字串，每個參數各一個。

備註

不同於DISP_PROPERTY_EX巨集，這個巨集可讓您指定屬性的參數清單。這適用於實作已編製索引或參數化的屬性。

範例

請考慮下列 get 和 set 成員函式的宣告，以允許使用者在存取屬性時要求特定資料列和資料行：

SHORT GetArray(SHORT row, SHORT column);
void SetArray(SHORT row, SHORT column, SHORT newVal);

這些對應至控件分派對應中的下列DISP_PROPERTY_PARAM巨集：

DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Array", GetArray, SetArray, VT_I2, VTS_I2 VTS_I2)

另一個範例中，請考慮下列 get 和 set 成員函式：

IDispatch* GetItem(SHORT index1, SHORT index2, SHORT index3);
void SetItem(SHORT index1, SHORT index2, SHORT index3, IDispatch* pVal);

這些對應至控件分派對應中的下列DISP_PROPERTY_PARAM巨集：

DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Item", GetItem, SetItem, VT_DISPATCH, VTS_I2 VTS_I2 VTS_I2)

需求

標頭： afxdisp.h

DISP_DEFVALUE

將現有的屬性設為物件的預設值。

DISP_DEFVALUE(theClass, pszName)

參數

theClass
類別的名稱。

pszName
屬性外部名稱，表示物件的｢值｣。

備註

使用預設值可以使設計 Visual Basic 應用程式的自動化物件時更為簡單。

您的物件的「預設值」就是物件的參考不指定屬性或成員函式時，所擷取或設定的屬性。

需求

標頭： afxdisp.h

另請參閱

巨集和全域

共用方式為

分派對應

DECLARE_DISPATCH_MAP

備註

範例

需求

BEGIN_DISPATCH_MAP

參數

備註

需求

END_DISPATCH_MAP

備註

需求

DISP_FUNCTION

參數

備註

需求

DISP_PROPERTY

參數

備註

需求

DISP_PROPERTY_EX

參數

備註

需求

DISP_PROPERTY_NOTIFY

參數

備註

需求

DISP_PROPERTY_PARAM

參數

備註

範例

需求

DISP_DEFVALUE

參數

備註

需求

另請參閱

意見反應

其他資源