IDesktopGadget::RunGadget-Methode (shobjidl.h)

Artikel
08/26/2023

Fügt dem Desktop ein installiertes Gadget hinzu.

Syntax

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

Parameter

[in] gadgetPath

Typ: LPCWSTR

Zeiger auf den vollständigen (absoluten) Pfad eines GADGET-Ordners. Ein Gadget, das nicht mit Windows gepackt ist, kann nur an einem der beiden folgenden Speicherorte ausgeführt werden. Die Installation des Gadgets an einem anderen Speicherort führt dazu, dass diese Methode mit einem Fehler vom Zugriff verweigert fehlschlägt.

Hinweis Dieser Pfad sollte keine Umgebungsvariablen enthalten. der vollständig erweiterte Pfad muss angegeben werden. ExpandEnvironmentStrings kann verwendet werden, um den Pfad zu dem in diesem Parameter erforderlichen Formular zu erweitern.

(%ProgramFiles%\Windows Sidebar\Shared Gadgets)

Dies ist der empfohlene Pfad für die Installation von Nicht-Microsoft-Gadgets, der allen Benutzern zur Verfügung steht.

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

Dieser Speicherort sollte für eine Einzelbenutzerinstallation des Gadgets verwendet werden.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK oder andernfalls einen Fehlerwert zurück, einschließlich der folgenden:

Rückgabecode	Beschreibung
SCHED_E_ALREADY_RUNNING	Das Gadget wird bereits ausgeführt.
E_INVALIDARG	Fehler beim Pfad des Gadgetordners, auf den gadgetPath verweist.

Hinweise

"Ausführen" eines Gadgets bedeutet, dass das Gadget dem Desktop hinzugefügt wird.

RunGadget kann nur für ein Gadget aufgerufen werden, das bereits auf dem System installiert wurde. Es kann nicht für ein Gadget aufgerufen werden, das bereits ausgeführt wird. Nur ein instance eines Gadgets kann zu einem bestimmten Zeitpunkt über diese Methode ausgeführt werden.

Da die Gadgetinstallation über keine eigene Benutzeroberfläche verfügt, wird diese Methode häufig als letzter Schritt im Installationsvorgang oder als Teil des ersten Starts einer Anwendung ausgeführt, der das Gadget zugeordnet ist. Die Installation des Gadgets in %ProgramFiles%\Windows Sidebar\Shared Gadgets erfordert Administratorrechte. Daher wird empfohlen, die Installation des Gadgets im Rahmen einer Msi-Installation (Microsoft Installer) durchzuführen.

Wichtig Anwendungen sollten RunGadget nicht aufrufen, ohne den Benutzer zuvor um die Berechtigung zu fragen. Wenn der Benutzer die Auswahl als Kontrollkästchen erhält, sollte dieses Kontrollkästchen standardmäßig deaktiviert sein.

Das Gadget wird dem Desktop an einer vom System festgelegten Position hinzugefügt. Der Aufrufer kann den Speicherort nicht angeben.

Benutzerspezifische Anwendungen sollten ihre Gadgets pro Benutzer installieren. Computerspezifische Anwendungen sollten ihre Gadgets pro Computer installieren. Dadurch wird eine einheitliche Benutzererfahrung für den Benutzer sichergestellt.

Beispiele

Das folgende Beispiel zeigt , wie IDesktopGadget::RunGadget verwendet wird.

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;
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shobjidl.h

Freigeben über