IOleObject::D oVerb メソッド (oleidl.h)

[アーティクル]
03/05/2024

エンドユーザーのアクションに応答してオブジェクトがアクションを実行するように要求します。考えられるアクションは、 IOleObject::EnumVerbs のオブジェクトに対して列挙されます。

構文

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

パラメーター

[in] iVerb

IOleObject::EnumVerbs によって返される OLEVERB 構造体の動詞に割り当てられた数値。

[in] lpmsg

動詞を呼び出したイベント (ダブルクリックなど) を記述する MSG 構造体へのポインター。呼び出し元は、構造体メンバーの値を解釈または変更せずに、 MSG 構造体を変更せずに渡す必要があります。

[in] pActiveSite

動詞を呼び出したイベントが発生した、オブジェクトのアクティブなクライアントサイト上の IOleClientSite インターフェイスへのポインター。

[in] lindex

このパラメーターは予約されており、0 である必要があります。

[in] hwndParent

オブジェクトを保持しているドキュメントウィンドウのハンドル。 this と lprcPosRect を組み合わせることで、オブジェクトの一時ウィンドウを開くこともできます。 ここで、hwndParent はオブジェクトのウィンドウを表示する親ウィンドウであり、 lprcPosRect は、その親内でオブジェクトウィンドウを表示するために使用できる領域を定義します。一時ウィンドウは、たとえば、再生用に開くが編集用には開かないマルチメディアオブジェクトに便利です。

[in] lprcPosRect

hwndParent でオブジェクトの外接する四角形を定義する座標 (ピクセル単位) を含む RECT 構造体へのポインター。これと hwndParent を組み合わせることで、再生のためにマルチメディアオブジェクトを開くが、編集は有効にしません。

戻り値

このメソッドは、成功したS_OKを返します。その他の可能な戻り値は次のとおりです。

リターンコード	説明
OLE_E_NOT_INPLACEACTIVE	iVerb が OLEIVERB_UIACTIVATE または OLEIVERB_INPLACEACTIVATE に設定されており、オブジェクトがまだ表示されていません。
OLE_E_CANT_BINDTOSOURCE	オブジェクトハンドラーまたはリンクオブジェクトは、リンクソースに接続できません。
DV_E_LINDEX	lindex が無効です。
OLEOBJ_S_CANNOT_DOVERB_NOW	動詞は有効ですが、オブジェクトの現在の状態では、対応するアクションを実行できません。
OLEOBJ_S_INVALIDHWND	DoVerb は成功しましたが、 hwndParent は無効です。
OLEOBJ_E_NOVERBS	オブジェクトは動詞をサポートしていません。
OLEOBJ_S_INVALIDVERB	リンクソースは、このコンピューター上のドライブに接続されていないネットワーク上にあります。
MK_E_CONNECT	リンクソースは、このコンピューター上のドライブに接続されていないネットワーク上にあります。
OLE_E_CLASSDIFF	リンク元のクラスに変換が行われます。
E_NOTIMPL	オブジェクトは、インプレースアクティブ化をサポートしていないか、負の動詞番号を認識しません。

注釈

"動詞" は、OLE オブジェクトがコンテナーからのメッセージに応答して実行するアクションです。オブジェクトのコンテナーまたはオブジェクトにリンクされているクライアントは、通常、オブジェクトをダブルクリックするなど、エンドユーザーの操作に応じて IOleObject::D oVerb を呼び出します。特定のオブジェクトに対して使用できるさまざまなアクションは、コンテナーが IOleObject::EnumVerbs を呼び出して取得する OLEVERB 構造体に列挙されます。 IOleObject::D oVerb は、iVerb の値を構造体の iVerb メンバーと照合して、呼び出す動詞を決定します。

IOleObject::EnumVerbs を使用すると、コンテナーではなくオブジェクトによって、サポートされる動詞 (つまりアクション) が決まります。 OLE 2 では、すべてのオブジェクトで使用できるが、必ずしも役に立つとは限らない 7 つの動詞が定義されています。さらに、各オブジェクトは、それに固有の追加の動詞を定義できます。次の表では、OLE で定義されている動詞について説明します。

動詞	説明
OLEIVERB_PRIMARY (0L)	エンドユーザーがコンテナー内のオブジェクトをダブルクリックしたときに発生するアクションを指定します。コンテナーではなくオブジェクトによって、このアクションが決定されます。オブジェクトがインプレースアクティブ化をサポートしている場合、一次動詞は通常、そのオブジェクトをインプレースでアクティブ化します。
OLEIVERB_SHOW (-1)	編集または表示のためにオブジェクト自体を表示するように指示します。最初の編集用に新しく挿入されたオブジェクトを表示し、リンクソースを表示するために呼び出されます。通常は、他のオブジェクト定義動詞の別名です。
OLEIVERB_OPEN (-2)	インプレースアクティブ化をサポートするものも含め、オブジェクトに対して、コンテナーとは別のウィンドウで編集できるようにオブジェクトを開くよう指示します。オブジェクトがインプレースアクティブ化をサポートしていない場合、この動詞はOLEIVERB_SHOWと同じセマンティクスを持ちます。
OLEIVERB_HIDE (-3)	オブジェクトのユーザーインターフェイスをビューから削除します。インプレースでアクティブ化されたオブジェクトにのみ適用されます。
OLEIVERB_UIACTIVATE (-4)	コンテナーウィンドウのタイトルバーにあるメニュー、ツールバー、名前など、ユーザーインターフェイスツールの完全なセットと共に、オブジェクトをインプレースでアクティブにします。オブジェクトがインプレースアクティブ化をサポートしていない場合は、E_NOTIMPLを返す必要があります。
OLEIVERB_INPLACEACTIVATE (-5)	エンドユーザーがオブジェクトの動作や外観を変更する必要があるツール (メニューやツールバーなど) を表示せずに、オブジェクトをアクティブにします。このようなオブジェクトを 1 回クリックすると、ユーザーインターフェイスツールの表示がコンテナーとネゴシエートされます。コンテナーが拒否した場合、オブジェクトはアクティブなままですが、ツールは表示されません。
OLEIVERB_DISCARDUNDOSTATE (-6)	オブジェクトを非アクティブ化せずに保持している可能性がある元に戻す状態を破棄するようにオブジェクトに指示するために使用します。

呼び出し元へのメモ

コンテナーは、新しく作成されたオブジェクトの初期化の一環として IOleObject::D oVerb を呼び出します。呼び出しを行う前に、コンテナーは最初に IOleObject::SetClientSite を呼び出して、表示場所をオブジェクトに通知し、 IOleObject::SetHostNames が埋め込みオブジェクトであることをオブジェクトに通知し、編集ウィンドウを開く準備としてオブジェクトアプリケーションのユーザーインターフェイスに適切な変更をトリガーする必要があります。

IOleObject::D oVerb は OLE サーバーアプリケーションを自動的に実行します。動詞の実行中にエラーが発生した場合、オブジェクトアプリケーションはシャットダウンされます。

エンドユーザーがメニューからコマンドを選択する以外の何らかの方法で動詞を呼び出す場合 (たとえば、ダブルクリックするか、オブジェクトを 1 回クリックする頻度が低い場合)、オブジェクトのコンテナーは、適切なメッセージを含む Windows MSG 構造体へのポインターを渡す必要があります。たとえば、オブジェクトをダブルクリックしてエンドユーザーが動詞を呼び出す場合、コンテナーは、WM_LBUTTONDBLCLK、WM_MBUTTONDBLCLK、またはWM_RBUTTONDBLCLKを含む MSG 構造体を渡す必要があります。コンテナーがメッセージを渡さない場合は、lpmsg を NULL に設定する必要があります。オブジェクトは、渡された MSG 構造体の hwnd メンバーを無視する必要がありますが、他のすべての MSG メンバーを使用できます。

オブジェクトの埋め込みコンテナーが IOleObject::D oVerb を呼び出す場合、IOleObject::D oVerb に渡されるクライアントサイトポインター (pClientSite) は埋め込みサイトのポインターと同じです。埋め込みオブジェクトがリンクソースの場合、 IOleObject::D oVerb に渡されるポインターは、リンククライアントのクライアントサイトのポインターです。

OLE リンクで IOleObject::D oVerb が呼び出されると、OLE_E_CLASSDIFFまたはMK_CONNECTMANUALLYが返されることがあります。リンクオブジェクトは、リンクがパッシブである間にリンクソースが何らかの変換を受けた場合に、前のエラーを返します。リンクオブジェクトは、呼び出し元のコンピューターに現在接続されていないネットワークドライブにリンクソースがある場合、後者のエラーを返します。これらの条件下でリンクを接続する唯一の方法は、最初に IUnknown::QueryInterface を呼び出し、 IOleLink を要求し、バインドコンテキストを割り当て、 IOleLink::BindToSource を呼び出してリンクソースを実行することです。

一般的なインプレースアクティブ化をサポートしていないコンテナーアプリケーションでは、引き続き hwndParent パラメーターと lprcPosRect パラメーターを使用して、マルチメディアファイルのインプレース再生をサポートできます。コンテナーは、有効な hwndParent パラメーターと lprcPosRect パラメーターを IOleObject::D oVerb に渡す必要があります。

一部のコードサンプルでは、0 ではなく -1 の lindex 値を渡します。値 -1 は機能しますが、ゼロを優先して回避する必要があります。 lindex パラメーターは予約済みパラメーターであり、一貫性の理由から、すべての予約済みパラメーターにゼロ値を割り当てることをお勧めします。

実装者へのメモ

上記の動詞に加えて、オブジェクトは OLEVERB 構造体自体に固有の追加動詞を定義できます。正の数値は、これらのオブジェクト固有の動詞を指定します。オブジェクトは、不明な正の動詞番号を主動詞であるかのように扱い、呼び出し元の関数にOLEOBJ_S_INVALIDVERBを返す必要があります。オブジェクトは、認識されない負の数値を持つ動詞を無視し、E_NOTIMPLを返す必要があります。

実行されている動詞によってオブジェクトが実行中の状態に配置される場合は、サーバーアプリケーションでリンクがサポートされていない場合でも、実行中のオブジェクトテーブル (ROT) にオブジェクトを登録する必要があります。登録は、ある時点でオブジェクトが埋め込みへのリンクをサポートするコンテナー内のリンクのソースとして機能する可能性があるため、重要です。オブジェクトを ROT に登録すると、リンククライアントはオブジェクトのコンテナーを通過する代わりに、オブジェクトへのポインターを直接取得できます。登録を実行するには、 IOleClientSite::GetMoniker を呼び出してオブジェクトの完全なモニカーを取得し、 GetRunningObjectTable 関数を呼び出して ROT へのポインターを取得し、 IRunningObjectTable::Register を呼び出します。

メモオブジェクトが実行中の状態を離れるときは、 IOleObject::Close を呼び出して、オブジェクトの ROT への登録を取り消してください。オブジェクトの実行中にオブジェクトのコンテナードキュメントの名前が変更された場合は、オブジェクトの登録を取り消し、その新しい名前を使用して ROT に再登録する必要があります。コンテナーは、 IOleObject::SetMoniker を呼び出すか、オブジェクトの呼び出し元の IOleClientSite::GetMoniker に応答することによって、新しいモニカーのオブジェクトに通知する必要があります。

IOleObject::D oVerb の結果としてウィンドウを表示する場合、オブジェクトが編集ウィンドウで SetForegroundWindow を明示的に呼び出すのが非常に重要です。これにより、オブジェクトのウィンドウは、別のプロセスで最初に隠されていた場合でも、ユーザーに表示されます。詳細については、「 SetForegroundWindow 」および「SetActiveWindow」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	oleidl.h