调度映射

项目
10/16/2023

OLE 自动化提供跨应用程序调用方法和访问属性的方法。 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	定义一个 OLE 自动化属性，该属性采用参数并命名 Get 和 Set 函数。
DISP_DEFVALUE	将现有属性设为对象的默认值。

DECLARE_DISPATCH_MAP

如果程序中的 CCmdTarget 派生类支持 OLE 自动化，则该类必须提供调度映射来公开其方法和属性。

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
指定 theClass 的基类名。

注解

在定义类的成员函数的实现 (.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	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	DATE
VTS_BSTR	LPCSTR
VTS_DISPATCH	LPDISPATCH
VTS_SCODE	SCODE
VTS_BOOL	BOOL
VTS_VARIANT	`const VARIANT*` 或 `VARIANT&`
VTS_UNKNOWN	LPUNKNOWN
VTS_PI2	short*
VTS_PI4	long*
VTS_PR4	float*
VTS_PR8	double*
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	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 参数的备注。请注意，DISP_FUNCTION 备注中列出的 VT_EMPTY 不可作为属性数据类型。

要求

标头：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	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_* 变体参数类型组成的字符串，每个参数对应一个类型。

注解

与 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

参数

备注

要求

另请参阅

反馈

其他资源