Win32 API 日本語リファレンス
ホーム › UI.Shell › IDesktopGadget

IDesktopGadget

COM
📘 Microsoft Learn (日本語) · English
IIDc1646bc4-f298-4f91-a204-eb2dd1709d1a継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

インストール済みのガジェットをプログラムからユーザーのデスクトップに追加するためのメソッドを公開します。

解説(Remarks)

実装する場合

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

使用する場合

このインターフェイスは、ガジェットを実行するために使用します。実行中のガジェットはデスクトップに表示されます。この操作は、ガジェットまたはアプリケーションのインストールの最後に行われることがよくあります。

メソッド 1

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT RunGadget(LPWSTR gadgetPath)

インストール済みのガジェットをデスクトップに追加します。

gadgetPathLPWSTRin

.gadget フォルダーのフル(絶対)パスへのポインター。Windows に付属していないガジェットは、次の 2 つの場所のいずれかからのみ実行できます。それ以外の場所にガジェットをインストールすると、このメソッドはアクセス拒否エラーで失敗します。

注意 このパスには環境変数を含めないでください。完全に展開されたパスを指定する必要があります。ExpandEnvironmentStrings を使用すると、このパラメーターで必要とされる形式にパスを展開できます。

(%ProgramFiles%\Windows Sidebar\Shared Gadgets)

これは、すべてのユーザーが利用できる、Microsoft 以外のガジェットをインストールする際の推奨パスです。

(%LOCALAPPDATA%\Microsoft\Windows Sidebar\Gadgets)

この場所は、ガジェットを単一ユーザー向けにインストールする場合に使用します。

戻り値

型: HRESULT

成功した場合は S_OK を、それ以外の場合は次のようなエラー値を返します。

戻り値 説明
SCHED_E_ALREADY_RUNNING
 ガジェットは既に実行中です。
E_INVALIDARG
 gadgetPath が指すガジェットフォルダーのパスに関するエラーが発生しました。

解説(Remarks)

ここでガジェットを「実行する」とは、ガジェットがデスクトップに追加されることを意味します。

RunGadget は、システムに既にインストールされているガジェットに対してのみ呼び出すことができます。既に実行中のガジェットに対しては呼び出せません。このメソッドを通じて、任意の時点で実行できるガジェットのインスタンスは 1 つだけです。

ガジェットのインストールには独自の UI がないため、このメソッドはインストール処理の最後の手順として、またはそのガジェットが関連付けられているアプリケーションの初回起動処理の一部として実行されることがよくあります。%ProgramFiles%\Windows Sidebar\Shared Gadgets へのガジェットのインストールには管理者権限が必要です。そのため、ガジェットのインストールは Microsoft Installer (MSI) インストールの一部として実行することが推奨されます。

重要 アプリケーションは、まずユーザーに許可を求めることなく RunGadget を呼び出すべきではありません。この選択をチェックボックスとしてユーザーに提示する場合、そのチェックボックスは既定でオフにしておく必要があります。
ガジェットは、システムによって決定される位置にデスクトップへ追加されます。呼び出し側で場所を指定することはできません。

ユーザー単位のアプリケーションは、ガジェットをユーザー単位でインストールすべきです。マシン単位のアプリケーションは、ガジェットをマシン単位でインストールすべきです。これにより、ユーザーに統一された操作感が提供されます。

例

次の例は、IDesktopGadget::RunGadget の使用方法を示しています。

HRESULT RunMyGadget(PCWSTR pszGadgetPath)
{
    IDesktopGadget *pDG;

    HRESULT hr = CoCreateInstance(CLSID_DesktopGadget, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&pDG));
    if (SUCCEEDED(hr))
    {
        hr = pDG->RunGadget(pszGadgetPath);
        pDG->Release();
    }

    return hr;
}
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IDesktopGadget "{C1646BC4-F298-4F91-A204-EB2DD1709D1A}"
#usecom global IDesktopGadget IID_IDesktopGadget "{924CCC1B-6562-4C85-8657-D177925222B6}"
#comfunc global IDesktopGadget_RunGadget  3 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。