ディスパッチマップ

[アーティクル]
06/16/2023

OLE オートメーションには、メソッドを呼び出し、アプリケーション間でプロパティにアクセスする方法が用意されています。これらの要求をディスパッチするために Microsoft Foundation Class Library によって提供されるメカニズムは、オブジェクト関数とプロパティの内部名と外部名、およびプロパティ自体と関数引数のデータ型を指定する "ディスパッチマップ" です。

マップのディスパッチマクロ	説明
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 オートメーションをサポートしている場合、そのクラスはディスパッチマップを提供して、そのメソッドとプロパティを公開する必要があります。

DECLARE_DISPATCH_MAP()

解説

クラス宣言の最後に DECLARE_DISPATCH_MAP マクロを使用します。次に、クラスのメンバー関数を定義する CPP ファイルでは、BEGIN_DISPATCH_MAP マクロを使用します。次に、クラスの公開されている各メソッドとプロパティ (DISP_FUNCTION、DISP_PROPERTY など) のマクロエントリを含めます。最後に、END_DISPATCH_MAP マクロを使用します。

Note

DECLARE_DISPATCH_MAP後にメンバーを宣言する場合は、新しいアクセスの種類 ( public、 private、または protected) を指定する必要があります。

アプリケーションウィザードとコードウィザードは、Automation クラスの作成とディスパッチマップの維持に役立ちます。ディスパッチマップの詳細については、「 Automation Servers」を参照してください。

例

class CMyServerDoc : public COleServerDoc
{
   DECLARE_DISPATCH_MAP()

   // Remainder of class declaration omitted.

要件

ヘッダー: afxwin.h

BEGIN_DISPATCH_MAP

ディスパッチマップの定義を宣言します。

BEGIN_DISPATCH_MAP(theClass, baseClass)

パラメーター

theClass
このディスパッチマップを所有するクラスの名前を指定します。

baseClass
クラスの基底クラス名を指定します。

解説

クラスのメンバー関数を定義する実装 (.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
関数のパラメーターリストを指定する 1 つ以上の定数のスペース区切りのリスト。

解説

引数 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_* 定数の値のスペース区切りのリストです。これらの値の 1 つ以上をスペース (コンマではなく) で区切って指定すると、関数のパラメーターリストが指定されます。たとえば、にします。

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	短い*
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	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
パラメーターごとに 1 つずつ、スペースで区切られた 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

パラメーター

解説

要件

関連項目

フィードバック

その他のリソース

ディスパッチマップ