ホーム › System.Ole › IOleCommandTarget

IOleCommandTarget

COM

📘 Microsoft Learn (日本語) · English

IIDb722bccb-4e68-101b-a2bc-00aa00404770継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

オブジェクトとそのコンテナーが相互にコマンドをディスパッチできるようにします。たとえば、オブジェクトのツールバーには、印刷、印刷プレビュー、保存、新規作成、ズームなどのコマンドのボタンを含めることができます。

メソッド 2

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT QueryStatus(GUID* pguidCmdGroup, DWORD cCmds, OLECMD* prgCmds, OLECMDTEXT* pCmdText)

ユーザーインターフェースイベントによって生成された 1 つ以上のコマンドの状態をオブジェクトに照会します。

pguidCmdGroup	GUID*	in	コマンドグループの一意の識別子。標準グループを指定するには NULL を指定できます。prgCmds 配列で渡されるすべてのコマンドは、pguidCmdGroup で指定されたグループに属している必要があります。
cCmds	DWORD	in	prgCmds 配列内のコマンドの数。
prgCmds	OLECMD*	inout	呼び出し元が状態情報を必要とするコマンドを示す、呼び出し元が割り当てた OLECMD 構造体の配列です。このメソッドは、各構造体の cmdf メンバーに OLECMDF 列挙型の値を設定します。
pCmdText	OLECMDTEXT*	inout	単一コマンドの名前や状態情報を返す OLECMDTEXT 構造体へのポインター。このパラメーターに NULL を指定すると、呼び出し元がこの情報を必要としないことを示します。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、以下のものがあります。

戻り値	説明
E_FAIL	操作に失敗しました。
E_UNEXPECTED	予期しないエラーが発生しました。
E_POINTER	prgCmds 引数が NULL です。
OLECMDERR_E_UNKNOWNGROUP	pguidCmdGroup パラメーターが NULL ではありませんが、認識されるコマンドグループを指定していません。

解説(Remarks)

呼び出し元は QueryStatus を使用して、ターゲットオブジェクトがどのコマンドをサポートしているかを判別します。呼び出し元は、そのオブジェクトにルーティングされるはずの利用できないコマンドを無効化できます。また、このメソッドを使用して、単一コマンドの名前や状態を取得することもできます。

vtbl 4 HRESULT Exec(GUID* pguidCmdGroup, DWORD nCmdID, DWORD nCmdexecopt, VARIANT* pvaIn, VARIANT* pvaOut)

指定されたコマンドを実行するか、そのコマンドのヘルプを表示します。

pguidCmdGroup	GUID*	in	コマンドグループの一意の識別子。標準グループを指定するには NULL を指定できます。
nCmdID	DWORD	in	実行するコマンド。このコマンドは、pguidCmdGroup で指定されたグループに属している必要があります。
nCmdexecopt	DWORD	in	オブジェクトがコマンドをどのように実行すべきかを指定します。指定可能な値は OLECMDEXECOPT および OLECMDID_WINDOWSTATE_FLAG 列挙型から取得されます。
pvaIn	VARIANT*	in	入力引数を格納する VARIANTARG 構造体へのポインター。このパラメーターは NULL にできます。
pvaOut	VARIANT*	inout	コマンドの出力を受け取る VARIANTARG 構造体へのポインター。このパラメーターは NULL にできます。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、以下のものがあります。

戻り値	説明
OLECMDERR_E_UNKNOWNGROUP	pguidCmdGroup パラメーターが NULL ではありませんが、認識されるコマンドグループを指定していません。
OLECMDERR_E_NOTSUPPORTED	nCmdID パラメーターが、pguidCmdGroup で識別されるグループ内の有効なコマンドではありません。
OLECMDERR_E_DISABLED	nCmdID で識別されるコマンドは現在無効化されており、実行できません。
OLECMDERR_E_NOHELP	呼び出し元が nCmdID で識別されるコマンドのヘルプを要求しましたが、ヘルプは利用できません。
OLECMDERR_E_CANCELED	ユーザーがコマンドの実行をキャンセルしました。

解説(Remarks)

コマンドの入力引数と出力引数のリスト、およびそれらのパッケージ化の方法は、各コマンドに固有です。こうした情報は、コマンドグループの仕様とともに文書化されるべきです。(OLECMDID 列挙型の OLECMDID_ZOOM の説明を参照してください。) 具体的な情報がない場合、そのコマンドは引数を取らず、戻り値を持たないものと見なされます。

呼び出し元への注意

pguidCmdGroup パラメーターと nCmdID パラメーターを合わせて、呼び出すコマンドを一意に識別します。nCmdExecOpt パラメーターは、実行される正確なアクションを指定します。(詳細については OLECMDEXECOPT 列挙型を参照してください。)

ほとんどのコマンドは、引数を取らず戻り値も返しません。そのようなコマンドの場合、呼び出し元は pvaIn および pvaOut に NULL を渡すことができます。1 つ以上の入力値を期待するコマンドの場合、呼び出し元は VARIANTARG 変数を宣言して初期化し、その変数へのポインターを pvaIn に渡すことができます。コマンドへの入力が単一の値であれば、その引数を VARIANTARG 構造体に直接格納して関数に渡すことができます。コマンドが複数の引数を期待する場合、それらの引数は、サポートされている型(IDispatch や SAFEARRAY など)のいずれかを使用して、VARIANTARG 内に適切にパッケージ化する必要があります。

コマンドが 1 つ以上の引数を返す場合、呼び出し元は VARIANTARG を宣言し、それを VT_EMPTY に初期化し、そのアドレスを pvaOut に渡すことが期待されます。コマンドが単一の値を返す場合、オブジェクトはその値を pvaOut に直接格納できます。コマンドが複数の出力値を持つ場合、オブジェクトはそれらを VARIANTARG に適した何らかの方法でパッケージ化します。

pvaIn と pvOut はどちらも呼び出し元が割り当てるため、呼び出し元と呼び出しを受け取るオブジェクトの両方でスタック変数を使用できます。入力で 0 個または 1 個の引数を取り、0 個または 1 個の値を返すコマンドの場合、追加のメモリ割り当ては不要です。VARIANTARG がサポートする型の大半はメモリ割り当てを必要としません。例外には SAFEARRAY と BSTR があります。

実装者への注意

コマンドターゲットはこの関数を実装する必要があります。E_NOTIMPL は有効な戻り値ではありません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IOleCommandTarget "{B722BCCB-4E68-101B-A2BC-00AA00404770}"
#usecom global IOleCommandTarget IID_IOleCommandTarget "{}"
#comfunc global IOleCommandTarget_QueryStatus  3 var,int,var,var
#comfunc global IOleCommandTarget_Exec         4 var,int,int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IOleCommandTarget "{B722BCCB-4E68-101B-A2BC-00AA00404770}"
#usecom global IOleCommandTarget IID_IOleCommandTarget "{}"
#comfunc global IOleCommandTarget_QueryStatus  3 sptr,int,sptr,sptr
#comfunc global IOleCommandTarget_Exec         4 sptr,int,int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。