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_MAPDeclares that a dispatch map will be used to expose a class's methods and properties (must be used in the class declaration).
BEGIN_DISPATCH_MAPStarts the definition of a dispatch map.
END_DISPATCH_MAPEnds the definition of a dispatch map.
DISP_FUNCTIONUsed in a dispatch map to define an OLE automation function.
DISP_PROPERTYDefines an OLE automation property.
DISP_PROPERTY_EXDefines an OLE automation property and names the Get and Set functions.
DISP_PROPERTY_NOTIFYDefines an OLE automation property with notification.
DISP_PROPERTY_PARAMDefines an OLE automation property that takes parameters and names the Get and Set functions.
DISP_DEFVALUEMakes an existing property the default value of an object.

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.

System_CAPS_ICON_note.jpg 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.

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.

Ends the definition of your dispatch map.

END_DISPATCH_MAP()  

Remarks

It must be used in conjunction with BEGIN_DISPATCH_MAP.

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:

SymbolReturn type
VT_EMPTYvoid
VT_I2short
VT_I4long
VT_R4float
VT_R8double
VT_CYCY
VT_DATEDATE
VT_BSTRBSTR
VT_DISPATCHLPDISPATCH
VT_ERRORSCODE
VT_BOOLBOOL
VT_VARIANTVARIANT
VT_UNKNOWNLPUNKNOWN

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:

SymbolParameter type
VTS_I2Short
VTS_I4Long
VTS_R4Float
VTS_R8Double
VTS_CYconst CY or CY*
VTS_DATEDATE
VTS_BSTRLPCSTR
VTS_DISPATCHLPDISPATCH
VTS_SCODESCODE
VTS_BOOLBOOL
VTS_VARIANTconst VARIANT* or VARIANT&
VTS_UNKNOWNLPUNKNOWN
VTS_PI2short*
VTS_PI4long*
VTS_PR4float*
VTS_PR8double*
VTS_PCYCY*
VTS_PDATEDATE*
VTS_PBSTRBSTR*
VTS_PDISPATCHLPDISPATCH*
VTS_PSCODESCODE*
VTS_PBOOLBOOL*
VTS_PVARIANTVARIANT*
VTS_PUNKNOWNLPUNKNOWN*
VTS_NONENo parameters

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:

SymbolProperty type
VT_I2short
VT_I4long
VT_R4float
VT_R8double
VT_CYCY
VT_DATEDATE
VT_BSTRCString
VT_DISPATCHLPDISPATCH
VT_ERRORSCODE
VT_BOOLBOOL
VT_VARIANTVARIANT
VT_UNKNOWNLPUNKNOWN

When an external client changes the property, the value of the member variable specified by memberName changes; there is no notification of the change.

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.

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:

SymbolProperty type
VT_I2short
VT_I4long
VT_R4float
VT_R8double
VT_CYCY
VT_DATEDATE
VT_BSTRCString
VT_DISPATCHLPDISPATCH
VT_ERRORSCODE
VT_BOOLBOOL
VT_VARIANTVARIANT
VT_UNKNOWNLPUNKNOWN

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)

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.

Macros and Globals

Show: