IOleObject

埋め込みオブジェクトが、そのコンテナーに対して基本的な機能を提供し、コンテナーと通信するための主要な手段を提供します。

埋め込みオブジェクトに対して、コンテナー内での表示位置(「クライアントサイト」と呼ばれます)を通知します。

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

戻り値	説明
E_UNEXPECTED	予期しないエラーが発生しました。

複合ドキュメント内では、各埋め込みオブジェクトが独自のクライアントサイトを持ちます。クライアントサイトとは、オブジェクトが表示される場所であり、そのストレージ、ユーザーインターフェイス、およびその他のリソースに関する情報をオブジェクトが受け取る経路でもあります。IOleObject::SetClientSite は、埋め込みオブジェクトが自身のクライアントサイトへのポインターを取得できる唯一のメソッドです。

呼び出し側への注意事項

コンテナーは、オブジェクトの作成時、またはその後のオブジェクトの初期化時に、オブジェクトへそのクライアントサイトを通知できます。

オブジェクトの作成または読み込みを行う際、コンテナーは(他の引数とともに)クライアントサイトへのポインターを次のいずれかのヘルパー関数に渡すことができます。OleCreate、OleCreateFromFile、OleCreateFromData、または OleLoad です。これらのヘルパー関数は、新しいオブジェクトのオブジェクトハンドラーを読み込み、新しいオブジェクトへのポインターを返す前に、コンテナーに代わって IOleObject::SetClientSite を呼び出します。

クライアントサイトへのポインターを渡すことは、クライアントサイトが要求を処理する準備ができていることをオブジェクトハンドラーに通知します。ハンドラーが読み込まれた直後にクライアントサイトの準備が整わない可能性がある場合は、コンテナーからヘルパー関数へ NULL のクライアントサイトポインターを渡すとよいでしょう。NULL ポインターは、利用可能なクライアントサイトが存在しないことを示し、これによってオブジェクトが初期化されるまでオブジェクトハンドラーへのクライアントサイトの通知を延期します。これに応じて、ヘルパー関数はオブジェクトへのポインターを返しますが、コンテナーはそのポインターを受け取った際に、新しいオブジェクトの初期化の一環として IOleObject::SetClientSite を呼び出す必要があります。

実装側への注意事項

実装は、クライアントサイトへのポインターの参照カウントを増やし、そのポインターを格納するだけで済みます。

埋め込みオブジェクトのクライアントサイトへのポインターを取得します。

このメソッドは、成功すると S_OK を返します。

リンククライアントは通常、入れ子になったオブジェクトの階層をたどるために、IOleObject::GetClientSite メソッドを IOleClientSite::GetContainer メソッドと組み合わせて呼び出します。リンククライアントは、リンクソースのクライアントサイトへのポインターを取得するために IOleObject::GetClientSite を呼び出します。次にクライアントは IOleClientSite::GetContainer を呼び出して、リンクソースのコンテナーへのポインターを取得します。最後に、クライアントは QueryInterface を呼び出して IOleObject を取得し、IOleObject::GetClientSite を呼び出して、そのコンテナーが属するコンテナー内でのクライアントサイトを取得します。この一連の呼び出しを繰り返すことで、呼び出し側は最終的に、他のすべてのオブジェクトが入れ子になっているマスターコンテナーへのポインターを取得できます。

呼び出し側への注意事項

埋め込みオブジェクトがまだ自身のクライアントサイトを通知されていない場合、返されるクライアントサイトポインターは NULL になります。これは、コンテナーがオブジェクト作成用ヘルパー関数のいずれかに NULL のクライアントサイトポインターを渡したものの、オブジェクトの初期化の一環として IOleObject::SetClientSite をまだ呼び出していない、新しく読み込まれた、または作成されたオブジェクトに該当します。

オブジェクトに対して、そのコンテナーアプリケーションの名前と、オブジェクトが埋め込まれている複合ドキュメントの名前を提供します。

このメソッドは、成功すると S_OK を返します。

呼び出し側への注意事項

IOleObject::SetHostNames は埋め込みオブジェクトに対してのみ呼び出してください。リンクされたオブジェクトの場合、リンクソースが独自の編集ウィンドウとタイトルバー情報を提供するためです。

実装側への注意事項

オブジェクトによる IOleObject::SetHostNames の適用には、オブジェクトの埋め込み状態に適したユーザーインターフェイスの変更を含めるべきです。そのような変更には通常、メニューコマンドの追加や削除、編集ウィンドウのタイトルバーに表示されるテキストの変更が含まれます。

SDI コンテナーアプリケーション、または子ウィンドウが最大化された MDI アプリケーションにおける埋め込みオブジェクトの完全なウィンドウタイトルは、次のように表示されるべきです。

<object application name> - <object short type> in <container document>

それ以外の場合、タイトルは次のようになります。

<object application name> - <container document>

「object short type」とは、リストボックスに全体を表示できる程度に短い、オブジェクト名の一形式を指します。これらの識別用文字列はオブジェクトの永続状態の一部として保存されないため、IOleObject::SetHostNames はオブジェクトが読み込まれる、または実行されるたびに呼び出す必要があります。

埋め込みオブジェクトを実行状態から読み込み済み状態に変更します。リンクされたオブジェクトの場合は、リンクソースから切断します。

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

戻り値	説明
OLE_E_PROMPTSAVECANCELLED	ユーザーは保存を求められましたが、確認メッセージボックスで キャンセル ボタンを選択しました。

呼び出し側への注意事項

コンテナーアプリケーションは、オブジェクトを実行状態から読み込み済み状態に移行させたいときに IOleObject::Close を呼び出します。この呼び出しの後、オブジェクトは依然としてコンテナー内に表示されますが、編集のために開かれた状態ではありません。読み込まれてはいるが実行されていないオブジェクトに対して IOleObject::Close を呼び出しても、何も起こりません。リンクされたオブジェクトを閉じることは、単にそれを切断することを意味します。

実装側への注意事項

IOleObject::Close の呼び出しを受け取ると、実行中のオブジェクトは次のことを行うべきです。

• オブジェクトが最後に編集のために開かれてから変更されている場合、dwSaveOption で指定された指示に従って、保存を要求するか、しないかを決定します。保存するオプションが指定されている場合は、コンテナーの IOleClientSite::SaveObject インターフェイスを呼び出す必要があります。
• オブジェクトに ADVF_DATAONSTOP フラグを伴う IDataObject::DAdvise 接続がある場合は、IAdviseSink::OnDataChange 通知を送信する必要があります。詳細については IDataObject::DAdvise を参照してください。
• オブジェクトが現在クリップボードを所有している場合は、OleFlushClipboard を呼び出してクリップボードを空にする必要があります。
• オブジェクトが現在表示されている場合は、fshow 引数を FALSE に設定して IOleClientSite::OnShowWindow を呼び出し、コンテナーに通知します。
• 適切なアドバイスシンクに IAdviseSink::OnClose 通知を送信します。
• 最後に、CoDisconnectObject を呼び出して、すべてのリモートクライアントを強制的に切断します。

オブジェクトアプリケーションがローカルサーバー(DLL ではなく EXE)である場合、オブジェクトを閉じることでオブジェクトアプリケーションもシャットダウンされるべきです。ただし、そのアプリケーションが他の実行中のオブジェクトをサポートしている場合や、実行状態を維持する別の理由がある場合を除きます。そのような理由には、IClassFactory::LockServer によるロックの存在、エンドユーザーによるアプリケーションの制御、またはアプリケーションへのアクセスを必要とする他の開いているドキュメントの存在などが含まれます。

リンクされたオブジェクトに対して IOleObject::Close を呼び出すと、そのソースアプリケーションから切断されますが、ソースアプリケーションはシャットダウンされません。オブジェクトが閉じられた時点でユーザーに表示されているソースアプリケーションは、切断後も表示され実行され続け、リンクコンテナーへ IAdviseSink::OnClose 通知を送信しません。

オブジェクトに対して、そのコンテナーのモニカー、コンテナーを基準としたオブジェクト自身のモニカー、またはオブジェクトの完全なモニカーを通知します。

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

戻り値	説明
E_FAIL	操作が失敗しました。

埋め込みオブジェクトへのリンクをサポートするコンテナーは、埋め込みオブジェクトのモニカーが変更されたときに、そのオブジェクトへ通知できなければなりません。そうしないと、以降にリンククライアントがそのオブジェクトへバインドしようとしても失敗します。IOleObject::SetMoniker メソッドは、コンテナーがこの情報を通知する手段の1つを提供します。

コンテナーは、自身のモニカー、コンテナーを基準としたオブジェクトのモニカー、またはオブジェクトの完全なモニカーのいずれかを渡すことができます。実際には、コンテナーがオブジェクトの完全なモニカー以外のものを渡した場合、各オブジェクトはコンテナーを呼び返して完全なモニカーの割り当てを要求します。オブジェクトは、実行中オブジェクトテーブルに自身を登録するために完全なモニカーを必要とするためです。

コンテナーを基準としたオブジェクトのモニカーは、オブジェクトの永続状態の一部としてオブジェクトハンドラーによって保存されます。しかし、オブジェクトのコンテナーのモニカーは、コンテナーがいつでも名前を変更される可能性があるため、オブジェクト内に永続的に保存してはなりません。

呼び出し側への注意事項

コンテナーは、コンテナーの名前が変更され、かつコンテナーの埋め込みオブジェクトが現在または将来的にリンクソースとして機能しうる場合に、IOleObject::SetMoniker を呼び出します。埋め込みオブジェクトはすでに自身のモニカーを認識しているため、コンテナーが SetMoniker を呼び出すのは主にリンクの文脈においてです。リンクの文脈においてさえ、このメソッドの呼び出しは省略可能です。オブジェクトは IOleClientSite::GetMoniker を呼び出して新しいモニカーの割り当てを強制できるためです。

実装側への注意事項

IOleObject::SetMoniker の呼び出しを受け取ると、オブジェクトは自身の完全なモニカーを実行中オブジェクトテーブルに登録し、そのオブジェクトに対して存在するすべてのアドバイスシンクへ IAdviseSink::OnRename 通知を送信するべきです。

埋め込みオブジェクトのモニカーを取得します。呼び出し側はこれを使用してオブジェクトへリンクできます。

このメソッドは、成功すると S_OK を返します。

IOleObject::GetMoniker メソッドは、オブジェクトのモニカーを返します。IOleObject::SetMoniker と同様に、このメソッドが重要となるのは埋め込みオブジェクトへのリンクを管理する文脈においてのみであり、その場合でも省略可能です。オブジェクトへバインドするためにそのモニカーを必要とする潜在的なリンククライアントは、このメソッドを呼び出してそのモニカーを取得できます。IOleObject::GetMoniker の既定の実装は IOleClientSite::GetMoniker を呼び出し、オブジェクトが実行されていない場合、またはクライアントサイトへの有効なポインターを持っていない場合は E_UNEXPECTED を返します。

新しく作成されたオブジェクトを、指定されたデータオブジェクトのデータで初期化します。データオブジェクトは、同じコンテナー内、またはクリップボード上のいずれにあってもかまいません。

このメソッドは、pDataObject が NULL でない場合、オブジェクトが提供されたデータからの自身の初期化を試みることに成功したときに S_OK を返します。pDataObject が NULL の場合は、オブジェクトが初期化を試みることが可能なときに S_OK を返します。その他に返される可能性のある値には次のものがあります。

戻り値	説明
S_FALSE	pDataObject が NULL でない場合、オブジェクトは自身の初期化を試みませんでした。pDataObject が NULL の場合、オブジェクトは提供されたデータから自身を初期化することを試みられません。
E_NOTIMPL	オブジェクトは InitFromData をサポートしていません。
OLE_E_NOTRUNNING	オブジェクトが実行されていないため、この操作を実行できません。

このメソッドは、コンテナードキュメントが、コンテナー内の現在のデータ選択範囲に基づいて内容を持つ新しいオブジェクトを、自身の内部に挿入できるようにします。たとえば、スプレッドシートドキュメントは、選択されたセル範囲のデータに基づいてグラフオブジェクトを作成したい場合があります。

このメソッドを使用すると、コンテナーは埋め込みオブジェクトの内容を、別のソースから転送されたデータで置き換えることもできます。これは埋め込みオブジェクトを更新する便利な方法を提供します。

呼び出し側への注意事項

初期化後、コンテナーは IOleObject::GetMiscStatus を呼び出して OLEMISC_INSERTNOTREPLACE ビットの値を確認するべきです。このビットがオンの場合、新しいオブジェクトは選択されたデータの後に自身を挿入します。ビットがオフの場合、新しいオブジェクトは選択されたデータを置き換えます。

実装側への注意事項

コンテナーは、fCreation パラメーターに TRUE または FALSE を渡すことで、新しいオブジェクトを現在の選択範囲に基づかせるかどうかを指定します。

fCreation が TRUE の場合、コンテナーはオブジェクトの新しいインスタンスの作成を試みており、データオブジェクトによって指定された選択済みデータでそれを初期化します。

fCreation が FALSE の場合、呼び出し側はオブジェクトの現在の内容を pDataObject が指すものに置き換えようとしています。貼り付け操作中にオブジェクトへ適用される通常の制約が、ここでも適用されるべきです。たとえば、提供されたデータの型が受け入れられないものである場合、オブジェクトは初期化に失敗し S_FALSE を返すべきです。

オブジェクトが S_FALSE を返す場合、提供されたデータから自身を初期化することはできません。

このメソッドが呼び出された埋め込みオブジェクトの現在の内容を含むデータオブジェクトを取得します。このデータオブジェクトへのポインターを使用すると、元のオブジェクトと同じデータを持つ新しい埋め込みオブジェクトを作成できます。

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

戻り値	説明
E_NOTIMPL	GetClipboardData はサポートされていません。
OLE_E_NOTRUNNING	オブジェクトが実行されていません。

IOleObject::GetClipboardData メソッドを使用すると、リンクされたオブジェクトを埋め込みオブジェクトに変換できます。その場合、コンテナーアプリケーションは IOleObject::GetClipboardData を呼び出し、受け取ったデータを OleCreateFromData に渡します。このメソッドは、標準のコピー操作によってクリップボードへ渡されるものと同一のデータオブジェクトへのポインターを返します。

呼び出し側への注意事項

埋め込みオブジェクトの現在の内容の安定したスナップショットが必要な場合は、IOleObject::GetClipboardData を呼び出します。データが変更された場合は、更新されたスナップショットを得るために関数を再度呼び出す必要があります。呼び出し側がデータに発生する変更の通知を受け取りたい場合は、QueryInterface を呼び出し、次に IDataObject::DAdvise を呼び出します。

実装側への注意事項

この関数を実装する場合は、データが変化しないオブジェクトに対する IDataObject ポインターを返す必要があります。

エンドユーザーの操作に応じて、オブジェクトにアクションを実行するよう要求します。指定可能なアクションは、IOleObject::EnumVerbs でオブジェクトについて列挙されます。

このメソッドは、成功すると 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	オブジェクトがインプレースアクティブ化をサポートしていないか、負の動詞番号を認識しません。

「動詞(verb)」とは、OLE オブジェクトがそのコンテナーからのメッセージに応じて行うアクションのことです。オブジェクトのコンテナー、またはオブジェクトへリンクされたクライアントは、通常、オブジェクトをダブルクリックするなどの何らかのエンドユーザー操作に応じて IOleObject::DoVerb を呼び出します。特定のオブジェクトで利用できるさまざまなアクションは OLEVERB 構造体に列挙されており、コンテナーは IOleObject::EnumVerbs を呼び出すことでこれを取得します。IOleObject::DoVerb は、どの動詞を呼び出すかを決定するために、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)	エンドユーザーがオブジェクトの動作や外観を変更するために必要とするメニューやツールバーなどのツールを表示せずに、オブジェクトをインプレースでアクティブ化します。このようなオブジェクトをシングルクリックすると、オブジェクトはそのユーザーインターフェイスツールの表示についてコンテナーと交渉します。コンテナーが拒否した場合、オブジェクトはアクティブなままですが、ツールは表示されません。
OLEIVERB_DISCARDUNDOSTATE (-6)	オブジェクトを非アクティブ化せずに、オブジェクトが保持している可能性のある元に戻す(undo)状態を破棄するよう、オブジェクトに指示するために使用されます。

呼び出し側への注意事項

コンテナーは、新しく作成されたオブジェクトの初期化の一環として IOleObject::DoVerb を呼び出します。この呼び出しの前に、コンテナーはまず IOleObject::SetClientSite を呼び出してオブジェクトにその表示位置を通知し、次に IOleObject::SetHostNames を呼び出して、そのオブジェクトが埋め込みオブジェクトであることを知らせ、編集ウィンドウを開く準備としてオブジェクトアプリケーションのユーザーインターフェイスに適切な変更を促すべきです。

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

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

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

IOleObject::DoVerb が OLE リンクに対して呼び出されると、OLE_E_CLASSDIFF または MK_CONNECTMANUALLY を返す場合があります。リンクオブジェクトは、リンクが非アクティブな間にリンクソースが何らかの変換を受けた場合に前者のエラーを返します。リンクオブジェクトは、リンクソースが現在呼び出し側のコンピューターに接続されていないネットワークドライブ上にある場合に後者のエラーを返します。このような状況でリンクを接続する唯一の方法は、まず IUnknown::QueryInterface を呼び出して IOleLink を要求し、バインドコンテキストを割り当て、IOleLink::BindToSource を呼び出してリンクソースを実行することです。

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

一部のコードサンプルでは、lindex の値としてゼロではなく -1 が渡されています。-1 という値も機能しますが、ゼロを優先して避けるべきです。lindex パラメーターは予約済みのパラメーターであり、一貫性の観点から、Microsoft はすべての予約済みパラメーターにゼロの値を割り当てることを推奨しています。

実装側への注意事項

上記の動詞に加えて、オブジェクトはそれ自身に固有の追加の動詞を OLEVERB 構造体内で定義できます。正の数がこれらのオブジェクト固有の動詞を指定します。オブジェクトは、認識できない任意の正の動詞番号をプライマリ動詞として扱い、呼び出し元の関数へ OLEOBJ_S_INVALIDVERB を返すべきです。オブジェクトは、認識できない負の番号を持つ動詞を無視し、E_NOTIMPL を返すべきです。

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

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

オブジェクトで利用可能な動詞を動詞番号の昇順で列挙するプルダウンメニューを公開します。

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

戻り値	説明
OLE_S_USEREG	既定のハンドラーに委任し、レジストリ内のエントリを使用して列挙を提供させます。
OLEOBJ_E_NOVERBS	オブジェクトはいずれの動詞もサポートしていません。

オブジェクトハンドラーまたはリンクオブジェクトのデータキャッシュまたはビューキャッシュを更新します。

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

戻り値	説明
E_FAIL	操作が失敗しました。
OLE_E_CANT_BINDTOSOURCE	更新されたデータを取得するためにオブジェクトを実行できません。何らかの理由でオブジェクトが呼び出し側から利用できません。
CACHE_E_NOCACHE_UPDATED	キャッシュは1つも更新されませんでした。
CACHE_S_SOMECACHES_NOTUPDATED	一部のキャッシュは更新されませんでした。

Update メソッドは、コンテナーがリンクされたオブジェクトや埋め込みオブジェクト内のデータを最新の状態に保つための手段を提供します。リンクソースが更新された場合、リンクオブジェクトは古くなる可能性があります。他のオブジェクトへのリンクを含む埋め込みオブジェクトも古くなる可能性があります。リンクを含まない埋め込みオブジェクトは、そのデータが別のソースにリンクされていないため、古くなることはありません。

実装側への注意事項

コンテナーがリンクオブジェクトの IOleObject::Update メソッドを呼び出すと、リンクオブジェクトはリンクソースを見つけ、そこから新しいプレゼンテーションを取得します。この処理には、1つ以上のオブジェクトアプリケーションの実行が伴う場合があり、時間がかかることがあります。

コンテナーが埋め込みオブジェクトの IOleObject::Update メソッドを呼び出すと、それはオブジェクトが含むすべてのリンクオブジェクトを更新するよう要求していることになります。これに応じて、オブジェクトハンドラーは自身の各リンクオブジェクトに対して IOleObject::Update を再帰的に呼び出し、必要に応じてそれぞれを実行します。

オブジェクトが最新の状態かどうかを確認します。

このメソッドは、オブジェクトが最新の状態である場合は S_OK を返し、そうでない場合は S_FALSE を返します。その他に返される可能性のある値には次のものがあります。

戻り値	説明
OLE_E_UNAVAILABLE	オブジェクトの状態を短時間で判定できません。

IOleObject::IsUpToDate メソッドは、コンテナーがすべてのオブジェクトが最新の状態かどうかを再帰的に確認するための手段を提供します。つまり、コンテナーが最初のオブジェクトに対してこのメソッドを呼び出すと、そのオブジェクトは今度は自身のすべてのオブジェクトに対してそれを呼び出し、それらもまた自身のすべてのオブジェクトに対して呼び出す、というようにして、すべてのオブジェクトが確認されるまで続きます。

実装側への注意事項

IOleObject::IsUpToDate の再帰的な性質のため、オブジェクト、特に1つ以上の他のオブジェクトを含むオブジェクトが古くなっているかどうかを判定することは、そもそもオブジェクトを更新するのと同じくらい時間がかかる場合があります。この種の長時間にわたるクエリを避けたい場合は、IOleObject::IsUpToDate が OLE_E_UNAVAILABLE を返すようにしてください。クエリ対象のオブジェクトが小さく、それ自身が他のオブジェクトを含んでおらず、効率的なクエリが可能な場合には、このメソッドは S_OK または S_FALSE のいずれかを返すことができます。

オブジェクトのクラス識別子、すなわちエンドユーザーに対してオブジェクトを識別する文字列に対応する CLSID を取得します。

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

戻り値	説明
E_FAIL	操作が失敗しました。

IOleObject::GetUserClassID は、登録データベース内でオブジェクトに関連付けられた CLSID を返します。通常、この値は IPersist::GetClassID によって返される、オブジェクトとともに保存されている CLSID と同一です。リンクされたオブジェクトの場合、これは最後にバインドされたリンクソースの CLSID です。オブジェクトが作成されたアプリケーションとは異なるアプリケーションで実行されており、編集のためにコンテナーアプリケーションが認識するクラスをエミュレートしている場合、返される CLSID はオブジェクト自身のクラスのものではなく、エミュレートされているクラスのものになります。

メニュー、リストボックス、ダイアログボックスなどのユーザーインターフェイス要素に表示するための、オブジェクトのユーザータイプ名を取得します。

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

戻り値	説明
OLE_S_USEREG	既定のハンドラーの実装に委任し、レジストリを使用して要求された情報を提供させます。

コンテナーは、リストボックス、メニュー、ダイアログボックスにおいて埋め込みオブジェクトを、その通常のユーザーが認識できる名前で表現するために IOleObject::GetUserType を呼び出します。例としては「Word Document」、「Excel Chart」、「Paintbrush Object」などがあります。IOleObject::GetUserType によって返される情報は、IOleObject::GetUserClassID によって返されるバイナリクラス識別子の、ユーザーが読める形式に相当します。

呼び出し側への注意事項

既定のハンドラーによる IOleObject::GetUserType の実装は、オブジェクトのクラス識別子(IOleObject::GetUserClassID によって返される pClsid パラメーター)と dwFormOfType パラメーターを組み合わせて、レジストリへのキーとして使用します。キーに完全に一致するエントリが見つかった場合、そのエントリで指定されたユーザータイプが返されます。キーの CLSID 部分のみが一致する場合、利用可能な中で最も番号の小さいエントリ(通常はフルネーム)が使用されます。CLSID が見つからない場合、またはそのクラスに対して登録されたユーザータイプが存在しない場合、オブジェクトのストレージ内に現在存在するユーザータイプが使用されます。

IOleObject::GetUserType から返された文字列をキャッシュすべきではありません。代わりに、その文字列が必要になるたびに毎回このメソッドを呼び出してください。これにより、埋め込みオブジェクトが呼び出し側の知らないうちにある型から別の型へ変換されている場合でも、正しい結果が保証されます。既定のハンドラーはこのメソッドをレジストリを使用して実装しているため、このメソッドの呼び出しはコストがかかりません。

実装側への注意事項

アプリケーションのこのメソッドの実装として OLE_S_USEREG を返すことで、既定のハンドラーが提供する実装を使用できます。ユーザータイプ名が空文字列の場合は、「Unknown Object」というメッセージが返されます。

OLE のヘルパー関数 OleRegGetUserType を呼び出して、適切なユーザータイプを返すこともできます。

オブジェクトに対して、そのコンテナーがどれだけの表示領域を割り当てたかを通知します。

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

戻り値	説明
E_FAIL	操作が失敗しました。
OLE_E_NOTRUNNING	オブジェクトが実行されていません。

コンテナーは、埋め込みオブジェクトが表示されるサイズをオブジェクトに指定する必要があるときに IOleObject::SetExtent を呼び出します。多くの場合、この呼び出しはエンドユーザーがオブジェクトウィンドウのサイズを変更したことに応じて発生します。この呼び出しを受け取ると、オブジェクトは可能であれば、新しいウィンドウに収まるように自身を適切に再構成するべきです。

可能な限り、コンテナーはオブジェクトをその最も精細な解像度(オブジェクトのネイティブサイズと呼ばれることもあります)で表示しようとします。しかし、すべてのオブジェクトには、そのアプリケーションによって指定された既定の表示サイズがあり、他の制約がない場合には、これが自身を表示する際に使用するサイズとなります。オブジェクトは、その最適な表示サイズをコンテナーよりもよく把握しているため、コンテナーは通常、実行中のオブジェクトから IOleObject::SetExtent を呼び出すことでそのサイズを要求します。コンテナーがオブジェクトから返された値に対応できない場合にのみ、IOleObject::SetExtent を呼び出してオブジェクトの優先サイズを上書きします。

呼び出し側への注意事項

IOleObject::SetExtent をオブジェクトに対して呼び出せるのは、オブジェクトが実行中の場合のみです。オブジェクトが実行されていないときにコンテナーがオブジェクトのサイズを変更する場合、コンテナーはオブジェクトの新しいサイズを記録しておき、ユーザーがオブジェクトをアクティブ化するまで IOleObject::SetExtent の呼び出しを延期するべきです。オブジェクトに OLEMISC_RECOMPOSEONRESIZE ビットが設定されている場合、コンテナーは IOleObject::SetExtent を呼び出す前に、オブジェクトを強制的に実行させるべきです。

上記のとおり、コンテナーは IOleObject::SetExtent を呼び出すことで、オブジェクトの表示サイトのサイズ設定の責任をオブジェクト自身に委任したい場合があります。

実装側への注意事項

オブジェクトが、コンテナー内で利用できる最大領域にできるだけ近づくように自身を再スケーリングするよう、このメソッドを実装したい場合があります。

オブジェクトのサイズが固定されている場合、すなわちコンテナーによって設定できない場合、IOleObject::SetExtent は E_FAIL を返すべきです。これは、サイズがコンテナーではなくリンクソースによって設定されるリンクされたオブジェクトの場合には常に当てはまります。

実行中のオブジェクトの現在の表示サイズを取得します。

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

戻り値	説明
E_INVALIDARG	指定された dwDrawAspect の値が無効です。

コンテナーは、実行中のオブジェクトに対して IOleObject::GetExtent を呼び出し、その現在の表示サイズを取得します。コンテナーがそのサイズに対応できる場合、通常はそれに従います。結局のところ、オブジェクトは自身がどのサイズであるべきかをコンテナーよりもよく把握しているためです。コンテナーは通常、オブジェクトの初期化の一環としてこの呼び出しを行います。

IOleObject::GetExtent によって返される表示サイズは、IOleObject::SetExtent によって最後に設定されたサイズと異なる場合があります。後者のメソッドは、呼び出された時点でのオブジェクトの表示領域を指定するものの、オブジェクトのアプリケーションによって決定されるオブジェクトのネイティブサイズを必ずしも変更するわけではないためです。

dwAspect で新しいアスペクトのいずれかが要求された場合、このメソッドは失敗するか、DVASPECT_CONTENT アスペクトの場合と同じ矩形を返すことができます。

呼び出し側への注意事項

コンテナーはこの呼び出しを実行中のオブジェクトに対してのみ行えるため、読み込み済みオブジェクトの表示サイズをそのキャッシュから取得したい場合は、代わりに IViewObject2::GetExtent を呼び出す必要があります。

実装側への注意事項

実装は、sizel 構造体にオブジェクトの高さと幅を格納することで構成されます。

複合ドキュメントオブジェクトと、呼び出し側オブジェクトのアドバイスシンクとの間にアドバイザリ接続を確立します。これを通じて、複合ドキュメントオブジェクトの名前変更、保存、またはクローズが行われたときに、呼び出し側オブジェクトが通知を受け取ります。

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

戻り値	説明
E_OUTOFMEMORY	この操作に利用できるメモリが不足しています。

IOleObject::Advise メソッドは、オブジェクトとそのコンテナーとの間にアドバイザリ接続を設定します。これを通じて、オブジェクトはコンテナーのアドバイスシンクに対して、オブジェクト内で発生したクローズ、保存、名前変更、リンクソースの変更のイベントを通知します。コンテナーは、通常はオブジェクトの初期化の一環として、自身のアドバイザリシンクをオブジェクトに登録するためにこのメソッドを呼び出します。その見返りとして、オブジェクトは IAdviseSink または IAdviseSink2 を呼び出すことで、コンテナーへ複合ドキュメント通知を送信します。

コンテナーとオブジェクトがアドバイザリ接続の確立に成功した場合、呼び出しを受け取ったオブジェクトは pdwConnection を通じてコンテナーへゼロ以外の値を返します。アドバイザリ接続の確立の試みが失敗した場合、オブジェクトはゼロを返します。アドバイザリ接続を削除するには、コンテナーは IOleObject::Unadvise を呼び出し、このゼロ以外のトークンをオブジェクトへ渡します。

オブジェクトは、アドバイザリイベントの管理と追跡の作業を OLE アドバイスホルダーに委任できます。このホルダーへのポインターは、CreateOleAdviseHolder を呼び出すことで取得します。返される IOleAdviseHolder インターフェイスには、アドバイザリ通知を送信するための3つのメソッドに加え、IOleObject のものと同一の IOleAdviseHolder::Advise、IOleAdviseHolder::Unadvise、IOleAdviseHolder::EnumAdvise メソッドがあります。IOleObject::Advise、IOleObject::Unadvise、または IOleObject::EnumAdvise への呼び出しは、アドバイスホルダー内の対応するメソッドに委任されます。

アドバイスホルダーを破棄するには、IOleAdviseHolder インターフェイスに対して IUnknown::Release を呼び出すだけです。

以前に確立したアドバイザリ接続を削除します。(IOleObject.Unadvise)

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

戻り値	説明
E_FAIL	操作が失敗しました。
OLE_E_NOCONNECTION	dwConnection が有効なアドバイザリ接続を表していません。

通常、コンテナーはシャットダウン時、またはオブジェクトが削除されるときに IOleObject::Unadvise を呼び出します。特定のケースでは、コンテナーは、複数のアドバイザリ接続を維持するオーバーヘッドを削減する方法として、実行中ではあるが現在表示されていないオブジェクトに対してこのメソッドを呼び出すことができます。このメソッドを実装する最も簡単な方法は、呼び出しを IOleObject::Unadvise に委任することです。

オブジェクトに登録されているアドバイザリ接続を列挙するために使用できる列挙子へのポインターを取得します。これにより、コンテナーはシャットダウンする前に何を解放すべきかを把握できます。

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

戻り値	説明
E_NOTIMPL	IOleObject::EnumAdvise は実装されていません。

IOleObject::EnumAdvise メソッドは、コンテナーが自身のオブジェクトに登録されたアドバイザリ接続を追跡する手段を提供する列挙子を供給します。コンテナーは通常、シャットダウンする前にオブジェクトへそのアドバイザリ接続をそれぞれ解放するよう指示できるように、この関数を呼び出します。

IOleObject::EnumAdvise を通じてアクセスできる列挙子は、STATDATA 型の項目を列挙します。ポインターを受け取ると、コンテナーは STATDATA をループで処理し、列挙された各接続に対して IOleObject::Unadvise を呼び出すことができます。

この関数を実装する通常の方法は、呼び出しを IOleAdviseHolder インターフェイスに委任することです。IOleObject::EnumAdvise に関係するのは、STATDATA の pAdvise メンバーと dwConnection メンバーのみです。

作成時および読み込み時のオブジェクトの状態を取得します。

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

戻り値	説明
OLE_S_USEREG	さまざまな状態情報の取得を、既定のハンドラーによるこのメソッドの実装に委任します。
CO_E_CLASSNOTREG	オブジェクトに登録された CLSID がありません。
CO_E_READREGDB	レジストリへのアクセス中にエラーが発生しました。

コンテナーは通常、オブジェクトの表示方法とサポートする動作の種類を判断するために、オブジェクトを作成または読み込む際に IOleObject::GetMiscStatus を呼び出します。

オブジェクトは状態情報をレジストリに保存します。オブジェクトが実行されていない場合、既定のハンドラーによる IOleObject::GetMiscStatus の実装は、この情報をレジストリから取得します。オブジェクトが実行中の場合、既定のハンドラーはオブジェクト自身に対して IOleObject::GetMiscStatus を呼び出します。

レジストリに実際に保存される情報は、個々のオブジェクトによって異なります。返される状態値は列挙型 OLEMISC で定義されています。

指定された DVASPECT に対応するサブキーが見つからない場合、IOleObject::GetMiscStatus の既定値が使用されます。OLE コントロールを設定するには、DVASPECT==1 を指定します。これにより、レジストリで次のことが発生します。

HKEY_CLASSES_ROOT\CLSID\ . . .
   MiscStatus = 1

実装側への注意事項

実装は通常、呼び出しを既定のハンドラーに委任することで構成されます。

オブジェクトアプリケーションが指定されたオブジェクトを編集する際に使用すべきカラーパレットを指定します。

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

戻り値	説明
E_NOTIMPL	オブジェクトはパレットの設定をサポートしていません。
OLE_E_PALETTE	pLogPal が指す LOGPALETTE 構造体が無効です。
OLE_E_NOTRUNNING	この操作を実行するには、オブジェクトが実行中である必要があります。

IOleObject::SetColorScheme メソッドは、コンテナーアプリケーションの推奨カラーパレットをオブジェクトアプリケーションへ送信します。オブジェクトアプリケーションはそれを使用する義務はありません。

#define global IID_IOleObject "{00000112-0000-0000-C000-000000000046}"
#usecom global IOleObject IID_IOleObject "{}"
#comfunc global IOleObject_SetClientSite     3 sptr
#comfunc global IOleObject_GetClientSite     4 sptr
#comfunc global IOleObject_SetHostNames      5 wstr,wstr
#comfunc global IOleObject_Close             6 int
#comfunc global IOleObject_SetMoniker        7 int,sptr
#comfunc global IOleObject_GetMoniker        8 int,int,sptr
#comfunc global IOleObject_InitFromData      9 sptr,int,int
#comfunc global IOleObject_GetClipboardData  10 int,sptr
#comfunc global IOleObject_DoVerb            11 int,var,sptr,int,sptr,var
#comfunc global IOleObject_EnumVerbs         12 sptr
#comfunc global IOleObject_Update            13
#comfunc global IOleObject_IsUpToDate        14
#comfunc global IOleObject_GetUserClassID    15 var
#comfunc global IOleObject_GetUserType       16 int,var
#comfunc global IOleObject_SetExtent         17 int,var
#comfunc global IOleObject_GetExtent         18 int,var
#comfunc global IOleObject_Advise            19 sptr,var
#comfunc global IOleObject_Unadvise          20 int
#comfunc global IOleObject_EnumAdvise        21 sptr
#comfunc global IOleObject_GetMiscStatus     22 int,var
#comfunc global IOleObject_SetColorScheme    23 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。