Dispatch Maps
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Dispatch Maps.
OLE Automation provides ways to call methods and to access properties across applications. The mechanism supplied by the Microsoft Foundation Class Library for dispatching these requests is the "dispatch map," which designates the internal and external names of object functions and properties, as well as the data types of the properties themselves and of function arguments.
Dispatch Maps
| DECLARE_DISPATCH_MAP | Declares that a dispatch map will be used to expose a class's methods and properties (must be used in the class declaration). |
| BEGIN_DISPATCH_MAP | Starts the definition of a dispatch map. |
| END_DISPATCH_MAP | Ends the definition of a dispatch map. |
| DISP_FUNCTION | Used in a dispatch map to define an OLE automation function. |
| DISP_PROPERTY | Defines an OLE automation property. |
| DISP_PROPERTY_EX | Defines an OLE automation property and names the Get and Set functions. |
| DISP_PROPERTY_NOTIFY | Defines an OLE automation property with notification. |
| DISP_PROPERTY_PARAM | Defines an OLE automation property that takes parameters and names the Get and Set functions. |
| DISP_DEFVALUE | Makes an existing property the default value of an object. |
DECLARE_DISPATCH_MAP
If a CCmdTarget-derived class in your program supports OLE Automation, that class must provide a dispatch map to expose its methods and properties.
DECLARE_DISPATCH_MAP
()
Remarks
Use the DECLARE_DISPATCH_MAP macro at the end of your class declaration. Then, in the .CPP file that defines the member functions for the class, use the BEGIN_DISPATCH_MAP macro. Then include macro entries for each of your class's exposed methods and properties ( DISP_FUNCTION, DISP_PROPERTY, and so on). Finally, use the END_DISPATCH_MAP macro.
Note
If you declare any members after DECLARE_DISPATCH_MAP, you must specify a new access type ( public, private, or protected) for them.
The Application Wizard and code wizards assist in creating Automation classes and in maintaining dispatch maps. For more information on dispatch maps, see Automation Servers.
Example
class CMyServerDoc : public COleServerDoc
{
DECLARE_DISPATCH_MAP()
// Remainder of class declaration omitted.
BEGIN_DISPATCH_MAP
Declares the definition of your dispatch map.
BEGIN_DISPATCH_MAP
(theClass, baseClass)
Parameters
theClass
Specifies the name of the class that owns this dispatch map.
baseClass
Specifies the base class name of theClass.
Remarks
In the implementation (.cpp) file that defines the member functions for your class, start the dispatch map with the BEGIN_DISPATCH_MAP macro, add macro entries for each of your dispatch functions and properties, and complete the dispatch map with the END_DISPATCH_MAP macro.
END_DISPATCH_MAP
Ends the definition of your dispatch map.
END_DISPATCH_MAP
()
Remarks
It must be used in conjunction with BEGIN_DISPATCH_MAP.
DISP_FUNCTION
Defines an OLE automation function in a dispatch map.
DISP_FUNCTION(
theClass,
pszName,
pfnMember,
vtRetVal,
vtsParams)
Parameters
theClass
Name of the class.
pszName
External name of the function.
pfnMember
Name of the member function.
vtRetVal
A value specifying the function's return type.
vtsParams
A space-separated list of one or more constants specifying the function's parameter list.
Remarks
The vtRetVal argument is of type VARTYPE. The following possible values for this argument are taken from the VARENUM enumeration:
| Symbol | Return type |
|---|---|
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 |
The vtsParams argument is a space-separated list of values from the VTS_ constants. One or more of these values separated by spaces (not commas) specifies the function's parameter list. For example,
VTS_I2 VTS_PI2
specifies a list containing a short integer followed by a pointer to a short integer.
The VTS_ constants and their meanings are as follows:
| Symbol | Parameter type |
|---|---|
| VTS_I2 | Short |
| VTS_I4 | Long |
| VTS_R4 | Float |
| VTS_R8 | Double |
| VTS_CY | const CY or CY* |
| VTS_DATE | DATE |
| VTS_BSTR | LPCSTR |
| VTS_DISPATCH | LPDISPATCH |
| VTS_SCODE | SCODE |
| VTS_BOOL | BOOL |
| VTS_VARIANT | const VARIANT* or 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 | No parameters |
DISP_PROPERTY
Defines an OLE automation property in a dispatch map.
DISP_PROPERTY(
theClass,
pszName,
memberName,
vtPropType)
Parameters
theClass
Name of the class.
pszName
External name of the property.
memberName
Name of the member variable in which the property is stored.
vtPropType
A value specifying the property's type.
Remarks
The vtPropType argument is of type VARTYPE. Possible values for this argument are taken from the VARENUM enumeration:
| Symbol | Property type |
|---|---|
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 |
When an external client changes the property, the value of the member variable specified by memberName changes; there is no notification of the change.
DISP_PROPERTY_EX
Defines an OLE automation property and name the functions used to get and set the property's value in a dispatch map.
DISP_PROPERTY_EX(
theClass,
pszName,
memberGet,
memberSet,
vtPropType)
Parameters
theClass
Name of the class.
pszName
External name of the property.
memberGet
Name of the member function used to get the property.
memberSet
Name of the member function used to set the property.
vtPropType
A value specifying the property's type.
Remarks
The memberGet and memberSet functions have signatures determined by the vtPropType argument. The memberGet function takes no arguments and returns a value of the type specified by vtPropType. The memberSet function takes an argument of the type specified by vtPropType and returns nothing.
The vtPropType argument is of type VARTYPE. Possible values for this argument are taken from the VARENUM enumeration. For a list of these values, see the Remarks for the vtRetVal parameter in DISP_FUNCTION. Note that VT_EMPTY, listed in the DISP_FUNCTION remarks, is not permitted as a property data type.
DISP_PROPERTY_NOTIFY
Defines an OLE automation property with notification in a dispatch map.
DISP_PROPERTY_NOTIFY(
theClass,
szExternalName,
memberName,
pfnAfterSet,
vtPropType)
Parameters
theClass
Name of the class.
szExternalName
External name of the property.
memberName
Name of the member variable in which the property is stored.
pfnAfterSet
Name of the notification function for szExternalName.
vtPropType
A value specifying the property's type.
Remarks
Unlike properties defined with DISP_PROPERTY, a property defined with DISP_PROPERTY_NOTIFY will automatically call the function specified by pfnAfterSet when the property is changed.
The vtPropType argument is of type VARTYPE. Possible values for this argument are taken from the VARENUM enumeration:
| Symbol | Property type |
|---|---|
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 |
DISP_PROPERTY_PARAM
Defines a property accessed with separate Get and Set member functions.
DISP_PROPERTY_PARAM(
theClass,
pszExternalName,
pfnGet,
pfnSet,
vtPropType,
vtsParams)
Parameters
theClass
Name of the class.
pszExternalName
External name of the property.
pfnGet
Name of the member function used to get the property.
pfnSet
Name of the member function used to set the property.
vtPropType
A value specifying the property's type.
vtsParams
A string of space-separated VTS_ variant parameter types, one for each parameter.
Remarks
Unlike the DISP_PROPERTY_EX macro, this macro allows you to specify a parameter list for the property. This is useful for implementing properties that are indexed or parameterized.
Example
Consider the following declaration of get and set member functions that allow the user to request a specific row and column when accessing the property:
SHORT GetArray(SHORT row, SHORT column);
void SetArray(SHORT row, SHORT column, SHORT newVal);
These correspond to the following DISP_PROPERTY_PARAM macro in the control dispatch map:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Array", GetArray, SetArray, VT_I2, VTS_I2 VTS_I2 )
As another example, consider the following get and set member functions:
IDispatch* GetItem(SHORT index1, SHORT index2, SHORT index3);
void SetItem(SHORT index1, SHORT index2, SHORT index3, IDispatch* pVal);
These correspond to the following DISP_PROPERTY_PARAM macro in the control dispatch map:
DISP_PROPERTY_PARAM(CMFCActiveXControlCtrl, "Item", GetItem, SetItem, VT_DISPATCH, VTS_I2 VTS_I2 VTS_I2)
DISP_DEFVALUE
Makes an existing property the default value of an object.
DISP_DEFVALUE
(theClass, pszName)
Parameters
theClass
Name of the class.
pszName
External name of the property that represents the "value" of the object.
Remarks
Using a default value can make programming your automation object simpler for Visual Basic applications.
The "default value" of your object is the property that is retrieved or set when a reference to an object does not specify a property or member function.