IOleObject::D oVerb メソッド (oleidl.h)
エンド ユーザーのアクションに応答してオブジェクトがアクションを実行するように要求します。 考えられるアクションは、 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を返します。 その他の可能な戻り値は次のとおりです。
| リターン コード | 説明 |
|---|---|
|
iVerb が OLEIVERB_UIACTIVATE または OLEIVERB_INPLACEACTIVATE に設定されており、オブジェクトがまだ表示されていません。 |
|
オブジェクト ハンドラーまたはリンク オブジェクトは、リンク ソースに接続できません。 |
|
lindex が無効です。 |
|
動詞は有効ですが、オブジェクトの現在の状態では、対応するアクションを実行できません。 |
|
DoVerb は成功しましたが、 hwndParent は無効です。 |
|
オブジェクトは動詞をサポートしていません。 |
|
リンク ソースは、このコンピューター上のドライブに接続されていないネットワーク上にあります。 |
|
リンク ソースは、このコンピューター上のドライブに接続されていないネットワーク上にあります。 |
|
リンク元のクラスに変換が行われます。 |
|
オブジェクトは、インプレース アクティブ化をサポートしていないか、負の動詞番号を認識しません。 |
注釈
"動詞" は、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 を呼び出します。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | oleidl.h |