ホーム › System.Ole › IOleUILinkContainerW
IOleUILinkContainerW
COM公式ドキュメント
コンテナーによって実装され、OLE 共通ダイアログボックスによって使用されます。コンテナーのリンクを管理するために必要なメソッドを提供することで、これらのダイアログボックスをサポートします。(Unicode)
解説(Remarks)
メモ
oledlg.h ヘッダーは IOleUILinkContainer をエイリアスとして定義しており、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択します。エンコーディング非依存のエイリアスの使用を、エンコーディング非依存でないコードと混在させると、不一致が生じ、コンパイルエラーや実行時エラーの原因となる場合があります。詳細については、関数プロトタイプの規約を参照してください。
メソッド 8
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
コンテナー内のリンクを列挙します。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。この値はこのインターフェイスの他のメソッドに渡されるだけであるため、コンテナーにとってリンクを一意に識別できる任意の値を使用できます。コンテナーでは、この値としてリンクのコンテナーサイトオブジェクトへのポインターがよく使用されます。 |
戻り値
コンテナーのリンク識別子を順番に返します。最後のリンクを返し終えた場合は NULL を返します。
解説(Remarks)
呼び出し元への注意
コンテナー内のリンクを列挙するには、このメソッドを呼び出します。dwLink に渡された値が NULL の場合、コンテナーは最初のリンクの識別子を返す必要があります。dwLink がコンテナー内の最後のリンクを識別している場合、コンテナーは NULL を返す必要があります。リンクの更新オプションを自動または手動に設定します。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。IOleUILinkContainer::GetNextLink を参照してください。 |
| dwUpdateOpt | DWORD | in | 更新オプションです。自動 (OLEUPDATE_ALWAYS) または手動 (OLEUPDATE_ONCALL) を指定できます。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
実装者への注意
コンテナーは、OLE リンクに対してこのメソッドを実装する際に、リンクオブジェクトに対して IOleLink::SetUpdateOptions を呼び出すだけで実装できます。リンクの現在の更新オプションを取得します。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。IOleUILinkContainer::GetNextLink を参照してください。 |
| lpdwUpdateOpt | DWORD* | out | 現在の更新オプションが書き込まれる場所へのポインターです。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
実装者への注意
コンテナーは、OLE リンクに対してこのメソッドを実装する際に、リンクオブジェクトに対して IOleLink::SetUpdateOptions を呼び出すだけで実装できます。vtbl 6 HRESULT SetLinkSource(DWORD dwLink, LPWSTR lpszDisplayName, DWORD lenFileName, DWORD* pchEaten, BOOL fValidateSource)
リンクのソースを変更します。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。IOleUILinkContainer::GetNextLink を参照してください。 |
| lpszDisplayName | LPWSTR | in | 解析対象となる新しいソース文字列へのポインターです。 |
| lenFileName | DWORD | in | lpszDisplayName 文字列の先頭にあるファイル名部分の長さです。リンクのソースがファイルに格納されていない場合、lenFileName は 0 にする必要があります。OLE リンクの場合は、IOleLink::GetSourceDisplayName を呼び出します。 |
| pchEaten | DWORD* | out | lpszDisplayName のうち正常に解析された文字数へのポインターです。 |
| fValidateSource | BOOL | in | モニカーを検証する必要がある場合は TRUE です。OLE リンクの場合は MkParseDisplayName を呼び出す必要があります。モニカーを検証しない場合は FALSE です。可能であれば、リンクは検証されていないソースを受け入れ、自身を使用不可としてマークする必要があります。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
呼び出し元への注意
このメソッドは [リンク元の変更] ダイアログボックスから、fValidateSource を最初は TRUE に設定して呼び出します。[リンク元の変更] は直接呼び出すことも、[リンク] ダイアログボックスから呼び出すこともできます。この IOleUILinkContainer::SetLinkSource の呼び出しがエラーを返した場合(例えば、ソースが使用できなかったために MkParseDisplayName が失敗した場合など)、[無効なリンク元] メッセージを表示し、ユーザーがソースを修正するかどうかを決定できるようにする必要があります。ユーザーがソースの修正を選択した場合、入力文字列の無効な部分が強調表示された状態で [リンク元の変更] ダイアログボックスに戻る必要があります。ユーザーがソースを修正しないことを選択した場合、fValidateSource を FALSE に設定して IOleUILinkContainer::SetLinkSource を再度呼び出し、リンクが [使用不可] とマークされた状態で [リンク] ダイアログボックスに戻る必要があります。vtbl 7 HRESULT GetLinkSource(DWORD dwLink, LPWSTR* lplpszDisplayName, DWORD* lplenFileName, LPWSTR* lplpszFullLinkType, LPWSTR* lplpszShortLinkType, BOOL* lpfSourceAvailable, BOOL* lpfIsSelected)
[リンク] ダイアログボックスに表示できる、リンクに関する情報を取得します。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。IOleUILinkContainer::GetNextLink を参照してください。 |
| lplpszDisplayName | LPWSTR* | outoptional | リンク元の完全な表示名文字列へのポインターを受け取るポインター変数のアドレスです。この文字列は [リンク] ダイアログボックスによって解放されます。 |
| lplenFileName | DWORD* | out | lplpszDisplayName 文字列の先頭にあるファイル名部分の長さへのポインターです。リンクのソースがファイルに格納されていない場合、lplenFileName は 0 にする必要があります。OLE リンクの場合は、IOleLink::GetSourceDisplayName を呼び出します。 |
| lplpszFullLinkType | LPWSTR* | outoptional | [リンク] ダイアログボックスの下部に表示される完全なリンク種類文字列へのポインターを受け取るポインター変数のアドレスです。この文字列は呼び出し元が割り当てます。この文字列は [リンク] ダイアログボックスによって解放されます。OLE リンクの場合、これは完全なユーザー種類名になります。IOleObject::GetUserType を使用し、dwFormOfType に USERCLASSTYPE_FULL を指定します。 |
| lplpszShortLinkType | LPWSTR* | outoptional | [リンク] ダイアログボックスのリストボックスに表示される短いリンク種類文字列へのポインターを受け取るポインター変数のアドレスです。この文字列は呼び出し元が割り当てます。この文字列は [リンク] ダイアログボックスによって解放されます。OLE リンクの場合、これは短いユーザー種類名になります。IOleObject::GetUserType を使用し、dwFormOfType に USERCLASSTYPE_SHORT を指定します。 |
| lpfSourceAvailable | BOOL* | out | 既知だが使用できないドキュメントへのリンクであるためにリンクが使用不可であることが判明している場合に FALSE を返すポインターです。このような場合、[今すぐ更新] などの特定のオプションは無効化されます(ユーザーインターフェイスで灰色表示されます)。 |
| lpfIsSelected | BOOL* | out | このリンクのエントリをダイアログの複数選択リストボックスで選択状態にすべきであることを [リンクの編集] ダイアログボックスに伝える変数へのポインターです。OleUIEditLinks は、リンク一覧に配置される各項目に対して、このメソッドを少なくとも 1 回呼び出します。それらのいずれも TRUE を返さない場合、ダイアログボックスが最初に表示されるときにはいずれも選択されません。それらすべてが TRUE を返す場合、すべてが表示されます。すなわち、このリンクが基になるドキュメント内で現在選択されている一部である場合は TRUE を、そうでない場合は FALSE を返します。基になるドキュメント内で選択されているリンクは、ダイアログボックスでも選択されます。これにより、ユーザーはリンクのセットを選択し、ダイアログボックスを使用してそれらを同時に更新したり、ソースを変更したりできます。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
リンクのソースを開きます。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。コンテナーでは、この値としてリンクのコンテナーサイトへのポインターを使用できます。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
呼び出し元への注意
IOleUILinkContainer::OpenLinkSource メソッドは、[リンク] ダイアログボックスで [ソースを開く] ボタンが選択されたときに呼び出されます。OLE リンクの場合は、IOleObject::DoVerb を呼び出し、iVerb に OLEIVERB_SHOW を指定します。選択されたリンクを、そのソースに強制的に接続させ、現在の情報を取得させます。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。コンテナーでは、この値としてリンクのコンテナーサイトへのポインターを使用できます。 |
| fErrorMessage | BOOL | in | リンクの更新に失敗した際に、呼び出し元(IOleUILinkContainer の実装者)がエラーメッセージを表示すべきかどうかを決定します。[リンクの更新] ダイアログボックスはこれを FALSE に設定します。[オブジェクトのプロパティ] ダイアログボックスと [リンク] ダイアログボックスはこれを TRUE に設定します。 |
| fReserved | BOOL | in | このパラメーターは予約されており、FALSE に設定する必要があります。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
呼び出し元への注意
ユーザーがリンクを更新するためにボタンを明示的に押した場合、すなわちリンクの [今すぐ更新] ボタンを押した場合には、fErrorMessage を TRUE に設定してこのメソッドを呼び出します。コンテナーがエラーメッセージを一切表示すべきでない場合、すなわち多数の操作が実行されており、エラーを後でユーザーに通知すべき場合([リンクの更新] の進行状況メーターで発生し得るような場合)には、FALSE を設定して呼び出します。失敗があると仮定して失敗ごとに 1 つのメッセージを表示するのではなく、操作の最後にすべての失敗に対して単一のメッセージを表示します。実装者への注意
OLE リンクの場合は、IOleObject::Update を呼び出します。選択されたリンクの接続を切断します。(Unicode)
| dwLink | DWORD | in | 単一のリンクを識別するための、コンテナー定義の一意な識別子です。コンテナーでは、この値としてリンクのコンテナーサイトへのポインターを使用できます。 |
戻り値
このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には、次のものがあります。
| 戻り値 | 説明 |
|---|---|
| アクセス権限が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
呼び出し元への注意
ユーザーが [リンク] ダイアログボックスで [リンクの解除] ボタンを選択したときに、IOleUILinkContainer::CancelLink を呼び出します。リンクは図に変換される必要があります。OLE リンクの場合、[リンク] ダイアログボックスは閉じられません。実装者への注意
OLE リンクの場合、リンクの IDataObject インターフェイスをソースとして使用して静的な図オブジェクトを作成するために、OleCreateStaticFromData を使用できます。出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
出力引数:
#define global IID_IOleUILinkContainerW "{}" #usecom global IOleUILinkContainerW IID_IOleUILinkContainerW "{}" #comfunc global IOleUILinkContainerW_GetNextLink 3 int #comfunc global IOleUILinkContainerW_SetLinkUpdateOptions 4 int,int #comfunc global IOleUILinkContainerW_GetLinkUpdateOptions 5 int,var #comfunc global IOleUILinkContainerW_SetLinkSource 6 int,wstr,int,var,int #comfunc global IOleUILinkContainerW_GetLinkSource 7 int,var,var,var,var,var,var #comfunc global IOleUILinkContainerW_OpenLinkSource 8 int #comfunc global IOleUILinkContainerW_UpdateLink 9 int,int,int #comfunc global IOleUILinkContainerW_CancelLink 10 int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IOleUILinkContainerW "{}" #usecom global IOleUILinkContainerW IID_IOleUILinkContainerW "{}" #comfunc global IOleUILinkContainerW_GetNextLink 3 int #comfunc global IOleUILinkContainerW_SetLinkUpdateOptions 4 int,int #comfunc global IOleUILinkContainerW_GetLinkUpdateOptions 5 int,sptr #comfunc global IOleUILinkContainerW_SetLinkSource 6 int,wstr,int,sptr,int #comfunc global IOleUILinkContainerW_GetLinkSource 7 int,sptr,sptr,sptr,sptr,sptr,sptr #comfunc global IOleUILinkContainerW_OpenLinkSource 8 int #comfunc global IOleUILinkContainerW_UpdateLink 9 int,int,int #comfunc global IOleUILinkContainerW_CancelLink 10 int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。