Méthode IDesktopGadget::RunGadget (shobjidl.h)

Article
08/26/2023

Ajoute un gadget installé au bureau.

Syntaxe

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

Paramètres

[in] gadgetPath

Type : LPCWSTR

Pointeur vers le chemin complet (absolu) d’un dossier .gadget. Un gadget qui n’est pas empaqueté avec Windows ne peut être exécuté qu’à partir de l’un des deux emplacements suivants. L’installation du gadget dans n’importe quel autre emplacement entraîne l’échec de cette méthode avec une erreur d’accès refusé.

Note Ce chemin ne doit pas contenir de variables d’environnement ; le chemin d’accès entièrement développé doit être fourni. ExpandEnvironmentStrings peut être utilisé pour développer le chemin d’accès au formulaire requis dans ce paramètre.

(%ProgramFiles%\Windows Sidebar\Shared Gadgets)

Il s’agit du chemin recommandé pour l’installation de gadgets non-Microsoft, disponible pour tous les utilisateurs.

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

Cet emplacement doit être utilisé pour une installation mono-utilisateur du gadget.

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite, ou une valeur d’erreur dans le cas contraire, y compris les éléments suivants :

Code de retour	Description
SCHED_E_ALREADY_RUNNING	Le gadget est déjà en cours d’exécution.
E_INVALIDARG	Une erreur s’est produite concernant le chemin du dossier gadget pointé par gadgetPath.

Remarques

« Exécution » d’un gadget signifie ici que le gadget est ajouté au bureau.

RunGadget ne peut être appelé que sur un gadget qui a déjà été installé sur le système. Il ne peut pas être appelé sur un gadget qui est déjà en cours d’exécution. Une seule instance d’un gadget peut être exécutée à un moment donné via cette méthode.

Étant donné que l’installation du gadget n’a pas de propre interface utilisateur, cette méthode est souvent exécutée comme la dernière étape du processus d’installation ou dans le cadre du premier lancement d’une application à laquelle le gadget est associé. L’installation du gadget sur %ProgramFiles%\Windows Sidebar\Shared Gadgets nécessite des privilèges d’administration. Par conséquent, il est recommandé d’effectuer l’installation du gadget dans le cadre d’une installation de Microsoft Installer (MSI).

Important Les applications ne doivent pas appeler RunGadget sans demander d’abord l’autorisation à l’utilisateur. Si le choix est donné à l’utilisateur en tant que zone de case activée, cette zone case activée doit être désélectionnée par défaut.

Le gadget est ajouté au bureau à une position déterminée par le système. L’appelant ne peut pas spécifier l’emplacement.

Les applications par utilisateur doivent installer leurs gadgets par utilisateur. Les applications par machine doivent installer leurs gadgets par ordinateur. Cela garantit une expérience unifiée pour l’utilisateur.

Exemples

L’exemple suivant montre IDesktopGadget::RunGadget en cours d’utilisation.

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

Configuration requise


Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl.h

Partager via