IApplicationDestinations

アプリケーションがジャンプリストの「最近使ったもの」または「よく使うもの」カテゴリから、1 つまたはすべての宛先を削除できるようにするメソッドを公開します。

実装するタイミング

このインターフェイスの実装は、Windows において CLSID_ApplicationDestinations として提供されています。このインターフェイスがサードパーティによって実装されることはありません。

使用するタイミング

アプリケーションは、ジャンプリストの自動生成された宛先から項目を削除したい場合に、このインターフェイスのメソッドを呼び出します。これらの宛先は 最近使ったもの または よく使うもの カテゴリに表示され、SHAddToRecentDocs の呼び出しによって生成されます。この呼び出しは明示的に行われるか、ファイルが Windows エクスプローラー経由で開かれたとき、あるいは共通ファイルダイアログを使用してファイルを開く、保存する、または作成したときに、システムによって行われます。

アプリケーションは、次のような状況で IApplicationDestinations のメソッドを呼び出す必要があります。

• アプリケーションがアンインストールされたとき。
• ユーザーが履歴をクリアしたとき。
• ユーザーがアプリケーションの設定またはオプションのページで宛先の追跡を無効にしたとき。
• ユーザーがアプリケーション内から宛先を削除したとき。これは、ファイルではない宛先の場合に特に重要です。ファイル以外の宛先（常にではありませんが、一般的には IShellLink 項目）の場合、宛先がもはや存在しないことを検出したときにリストからその宛先を削除するのは、アプリケーションの責任です。

ユーザーがアプリケーションのプライバシー設定で使用状況の追跡をオフにした場合、アプリケーションは既存のデータをクリアするとともに、以後その項目に関する使用状況データをシステムが収集しないようにする責任を負います。これは、アプリケーションのすべてのファイルタイプ登録に NoRecentDocs 値を設定することで行います。詳細については FTA_NoRecentDocs を参照してください。

IApplicationDestinations のメソッドは、自動生成された 最近使ったもの または よく使うもの カテゴリでのみ使用されます。これらのメソッドは、ユーザーがジャンプリストにピン留めした項目を削除することはありません。ピン留めされた項目はプログラムによって削除することはできず、ユーザーのみが削除できます。また、これらのメソッドは カスタムカテゴリ やタスクリストには影響を与えません。

このインターフェイスのメソッドが宛先を削除する対象となる、タスクバーボタンのジャンプリストを持つアプリケーションに対して、一意の Application User Model ID (AppUserModelID) を指定します。このメソッドは省略可能です。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

アプリケーションが明示的な AppUserModelID を持つ場合、RemoveAllDestinations または RemoveDestination を呼び出す前に、このメソッドを呼び出す必要があります。

オブジェクトの SetAppID メソッドを通じて AppUserModelID が指定されると、その AppUserModelID はオブジェクトの有効期間中そのオブジェクト内に保存されます。ただし、別の SetAppID の呼び出しによって上書きされないことが条件です。

一部のアプリケーションは明示的な AppUserModelID を宣言しないため、このメソッドを呼び出すべきではありません。その場合、アプリケーションの識別情報は IApplicationDestinations::RemoveDestination または IApplicationDestinations::RemoveAllDestinations が呼び出されたときに推測されます。ただし、これらの計算を回避することにはパフォーマンス上の利点があるため、カスタムジャンプリストを提供するアプリケーションでは 明示的な AppUserModelID の使用が推奨されます。

ジャンプリストの「最近使ったもの」および「よく使うもの」カテゴリから、1 つの宛先を削除します。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は標準的な COM エラー値を返します。punk が指すオブジェクトが IShellItem でも IShellLink でもない場合、このメソッドは E_INVALIDARG を返します。

1 つの宛先が 最近使ったもの と よく使うもの の両方のカテゴリに表示されることがあります。その場合、このメソッドは両方のカテゴリから宛先を削除します。

項目がユーザーによってリストにピン留めされている場合、その項目は削除されませんが、使用状況データはクリアされます。

アプリケーションは、punk が指す項目が現在リストに存在するかどうかを知らなくても RemoveDestination を呼び出すことができます。項目に関する既存のデータが存在しない場合（つまり 最近使ったもの または よく使うもの リストに存在しない場合）、このメソッドは何もせず S_OK を返します。

アプリケーションが明示的な Application User Model ID (AppUserModelID) を持つ場合、このメソッドを呼び出す前に IApplicationDestinations::SetAppID を呼び出す必要があります。

アプリケーションのジャンプリストの「最近使ったもの」および「よく使うもの」カテゴリから、すべての宛先エントリをクリアします。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは、ユーザーがジャンプリストにピン留めした項目を削除しません。ピン留めされた項目はプログラムによって削除することはできず、ユーザーのみが削除できます。ただし、これらのピン留めされた項目の使用状況データは削除します。また、カスタムカテゴリやタスクリストから項目を削除することもできません。

アプリケーションが明示的な Application User Model ID (AppUserModelID) を持つ場合、このメソッドを呼び出す前に IApplicationDestinations::SetAppID を呼び出す必要があります。

#define global IID_IApplicationDestinations "{12337D35-94C6-48A0-BCE7-6A9C69D4D600}"
#usecom global IApplicationDestinations IID_IApplicationDestinations "{86C14003-4D6B-4EF3-A7B4-0506663B2E68}"
#comfunc global IApplicationDestinations_SetAppID               3 wstr
#comfunc global IApplicationDestinations_RemoveDestination      4 sptr
#comfunc global IApplicationDestinations_RemoveAllDestinations  5
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。