ホーム › System.Ole › IOleUILinkContainerA
IOleUILinkContainerA
COM公式ドキュメント
コンテナーによって実装され、OLE 共通ダイアログボックスから使用されます。コンテナーのリンクを管理するために必要なメソッドを提供することで、これらのダイアログボックスをサポートします。(ANSI)
解説(Remarks)
メモ
oledlg.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして IOleUILinkContainer を定義します。エンコーディング非依存のエイリアスの使用と、エンコーディング非依存でないコードの使用を混在させると、不一致が生じ、コンパイルエラーや実行時エラーの原因となる場合があります。詳細については、関数プロトタイプの規則を参照してください。
メソッド 8
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
コンテナー内のリンクを列挙します。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。この値はこのインターフェイスの他のメソッドに渡されるだけなので、コンテナーがリンクを一意に識別できる任意の値を使用できます。コンテナーではこの値として、リンクのコンテナーサイトオブジェクトへのポインターを使用することがよくあります。 |
戻り値
コンテナーのリンク識別子を順に返します。最後のリンクを返した場合は NULL を返します。
解説(Remarks)
呼び出し元への注意
コンテナー内のリンクを列挙するには、このメソッドを呼び出します。dwLink に渡された値が NULL の場合、コンテナーは最初のリンクの識別子を返します。dwLink がコンテナー内の最後のリンクを識別する場合、コンテナーは NULL を返します。リンクの更新オプションを自動または手動に設定します。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。IOleUILinkContainer::GetNextLink を参照してください。 |
| dwUpdateOpt | DWORD | in | 更新オプション。自動 (OLEUPDATE_ALWAYS) または手動 (OLEUPDATE_ONCALL) を指定できます。 |
戻り値
このメソッドは成功すると S_OK を返します。その他に返される可能性のある値は次のとおりです。
| 戻り値 | 説明 |
|---|---|
| アクセス許可が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
実装者への注意
コンテナーは、OLE リンクに対してこのメソッドを実装する際、単にリンクオブジェクトに対して IOleLink::SetUpdateOptions を呼び出すだけで実装できます。リンクの現在の更新オプションを取得します。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。IOleUILinkContainer::GetNextLink を参照してください。 |
| lpdwUpdateOpt | DWORD* | out | 現在の更新オプションが書き込まれる場所へのポインター。 |
戻り値
このメソッドは成功すると S_OK を返します。その他に返される可能性のある値は次のとおりです。
| 戻り値 | 説明 |
|---|---|
| アクセス許可が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
実装者への注意
コンテナーは、OLE リンクに対してこのメソッドを実装する際、単にリンクオブジェクトに対して IOleLink::SetUpdateOptions を呼び出すだけで実装できます。vtbl 6 HRESULT SetLinkSource(DWORD dwLink, LPSTR lpszDisplayName, DWORD lenFileName, DWORD* pchEaten, BOOL fValidateSource)
リンクのソースを変更します。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。IOleUILinkContainer::GetNextLink を参照してください。 |
| lpszDisplayName | LPSTR | 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, LPSTR* lplpszDisplayName, DWORD* lplenFileName, LPSTR* lplpszFullLinkType, LPSTR* lplpszShortLinkType, BOOL* lpfSourceAvailable, BOOL* lpfIsSelected)
リンクダイアログボックスに表示できるリンクに関する情報を取得します。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。IOleUILinkContainer::GetNextLink を参照してください。 |
| lplpszDisplayName | LPSTR* | outoptional | リンクソースの完全な表示名文字列へのポインターを受け取るポインター変数のアドレス。リンクダイアログボックスがこの文字列を解放します。 |
| lplenFileName | DWORD* | out | lplpszDisplayName 文字列の先頭のファイル名部分の長さへのポインター。リンクのソースがファイルに格納されていない場合、lplenFileName は 0 にする必要があります。OLE リンクの場合は、IOleLink::GetSourceDisplayName を呼び出します。 |
| lplpszFullLinkType | LPSTR* | outoptional | リンクダイアログボックスの下部に表示される完全なリンク種類文字列へのポインターを受け取るポインター変数のアドレス。この文字列は呼び出し元が割り当てます。リンクダイアログボックスがこの文字列を解放します。OLE リンクの場合、これは完全なユーザー種類名にする必要があります。IOleObject::GetUserType を使用し、dwFormOfType に USERCLASSTYPE_FULL を指定します。 |
| lplpszShortLinkType | LPSTR* | outoptional | リンクダイアログボックスのリストボックスに表示される短いリンク種類文字列へのポインターを受け取るポインター変数のアドレス。この文字列は呼び出し元が割り当てます。リンクダイアログボックスがこの文字列を解放します。OLE リンクの場合、これは短いユーザー種類名にする必要があります。IOleObject::GetUserType を使用し、dwFormOfType に USERCLASSTYPE_SHORT を指定します。 |
| lpfSourceAvailable | BOOL* | out | リンクが既知だが使用不可のドキュメントを指しているためにリンクが使用不可であることがわかっている場合に FALSE を返すポインター。そのような場合、今すぐ更新などの特定のオプションは無効化されます(ユーザーインターフェイス上でグレー表示になります)。 |
| lpfIsSelected | BOOL* | out | このリンクのエントリをダイアログの複数選択リストボックスで選択するべきであることを リンクの編集ダイアログボックスに伝える変数へのポインター。OleUIEditLinks は、リンクリストに配置される各項目に対して、このメソッドを少なくとも 1 回呼び出します。いずれも TRUE を返さない場合、ダイアログボックスが最初に表示されたときにはどれも選択されません。すべてが TRUE を返す場合は、すべてが表示されます。つまり、このリンクが現在、基となるドキュメント内の選択範囲の一部である場合は TRUE を、そうでない場合は FALSE を返します。基となるドキュメント内で選択されているリンクは、ダイアログボックス内でも選択されます。これにより、ユーザーはリンクのセットを選択し、ダイアログボックスを使用してそれらを一括で更新したり、ソースを一括で変更したりできます。 |
戻り値
このメソッドは成功すると S_OK を返します。その他に返される可能性のある値は次のとおりです。
| 戻り値 | 説明 |
|---|---|
| アクセス許可が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
リンクのソースを開きます。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。コンテナーではこの値として、リンクのコンテナーサイトへのポインターを使用できます。 |
戻り値
このメソッドは成功すると S_OK を返します。その他に返される可能性のある値は次のとおりです。
| 戻り値 | 説明 |
|---|---|
| アクセス許可が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
呼び出し元への注意
IOleUILinkContainer::OpenLinkSource メソッドは、リンクダイアログボックスで ソースを開くボタンが選択されたときに呼び出されます。OLE リンクの場合は、IOleObject::DoVerb を呼び出し、iVerb に OLEIVERB_SHOW を指定します。選択されたリンクを強制的にソースに接続させ、現在の情報を取得します。(ANSI)
| dwLink | DWORD | in | 単一のリンクに対するコンテナー定義の一意の識別子。コンテナーではこの値として、リンクのコンテナーサイトへのポインターを使用できます。 |
| fErrorMessage | BOOL | in | リンクの更新に失敗した場合に、呼び出し元(IOleUILinkContainer の実装者)がエラーメッセージを表示するべきかどうかを決定します。リンクの更新ダイアログボックスはこれを FALSE に設定します。オブジェクトのプロパティダイアログボックスおよびリンクダイアログボックスはこれを TRUE に設定します。 |
| fReserved | BOOL | in | このパラメーターは予約されており、FALSE に設定する必要があります。 |
戻り値
このメソッドは成功すると S_OK を返します。その他に返される可能性のある値は次のとおりです。
| 戻り値 | 説明 |
|---|---|
| アクセス許可が不足しています。 | |
| 操作に失敗しました。 | |
| 指定された識別子が無効です。 | |
| この操作に使用できるメモリが不足しています。 |
解説(Remarks)
呼び出し元への注意
ユーザーが明示的にボタンを押してリンクを更新させる場合、つまりリンクの 今すぐ更新ボタンを押す場合は、fErrorMessage を TRUE に設定してこのメソッドを呼び出します。コンテナーがエラーメッセージを一切表示すべきでない場合、つまり大量の操作が実行されており、エラーを後でユーザーに伝えるべき場合(リンクの更新の進行状況メーターで発生し得るような場合)は、FALSE を設定して呼び出します。失敗がある場合、失敗ごとに 1 つのメッセージを提供するのではなく、操作の最後にすべての失敗に対して 1 つのメッセージを提供します。実装者への注意
OLE リンクの場合は、IOleObject::Update を呼び出します。選択されたリンクを切断します。(ANSI)
| 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_IOleUILinkContainerA "{}" #usecom global IOleUILinkContainerA IID_IOleUILinkContainerA "{}" #comfunc global IOleUILinkContainerA_GetNextLink 3 int #comfunc global IOleUILinkContainerA_SetLinkUpdateOptions 4 int,int #comfunc global IOleUILinkContainerA_GetLinkUpdateOptions 5 int,var #comfunc global IOleUILinkContainerA_SetLinkSource 6 int,str,int,var,int #comfunc global IOleUILinkContainerA_GetLinkSource 7 int,var,var,var,var,var,var #comfunc global IOleUILinkContainerA_OpenLinkSource 8 int #comfunc global IOleUILinkContainerA_UpdateLink 9 int,int,int #comfunc global IOleUILinkContainerA_CancelLink 10 int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IOleUILinkContainerA "{}" #usecom global IOleUILinkContainerA IID_IOleUILinkContainerA "{}" #comfunc global IOleUILinkContainerA_GetNextLink 3 int #comfunc global IOleUILinkContainerA_SetLinkUpdateOptions 4 int,int #comfunc global IOleUILinkContainerA_GetLinkUpdateOptions 5 int,sptr #comfunc global IOleUILinkContainerA_SetLinkSource 6 int,str,int,sptr,int #comfunc global IOleUILinkContainerA_GetLinkSource 7 int,sptr,sptr,sptr,sptr,sptr,sptr #comfunc global IOleUILinkContainerA_OpenLinkSource 8 int #comfunc global IOleUILinkContainerA_UpdateLink 9 int,int,int #comfunc global IOleUILinkContainerA_CancelLink 10 int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。