Share via

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

  • Artículo

Agrega un gadget instalado al escritorio.

Sintaxis

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

Parámetros

[in] gadgetPath

Tipo: LPCWSTR

Puntero a la ruta de acceso completa (absoluta) de una carpeta .gadget. Un gadget que no está empaquetado con Windows solo se puede ejecutar desde una de las dos ubicaciones siguientes. La instalación del gadget en cualquier otra ubicación hará que este método produzca un error de acceso denegado.

Nota Esta ruta de acceso no debe contener variables de entorno; se debe proporcionar la ruta de acceso totalmente expandida. ExpandEnvironmentStrings se puede usar para expandir la ruta de acceso al formulario necesario en este parámetro.
 

(%ProgramFiles%\Windows Sidebar\Shared Gadgets)

Esta es la ruta recomendada para la instalación de gadgets que no son de Microsoft, disponibles para todos los usuarios.

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

Esta ubicación debe usarse para una instalación de usuario único del gadget.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente o un valor de error, incluido lo siguiente:

Código devuelto Descripción
SCHED_E_ALREADY_RUNNING
 El gadget ya está en ejecución.
E_INVALIDARG
 Error relacionado con la ruta de acceso de la carpeta gadget a la que apunta gadgetPath.

Comentarios

"Ejecutando" un gadget aquí significa que el gadget se agrega al escritorio.

RunGadget solo se puede llamar en un gadget que ya se haya instalado en el sistema. No se puede llamar a en un gadget que ya se esté ejecutando: solo se puede ejecutar una instancia de un gadget en un momento dado a través de este método.

Dado que la instalación de gadgets no tiene ninguna interfaz de usuario propia, este método se suele ejecutar como el último paso en el proceso de instalación o como parte del primer inicio de una aplicación con la que está asociado el gadget. La instalación del gadget en %ProgramFiles%\Windows Sidebar\Shared Gadgets requiere privilegios administrativos. Por lo tanto, se recomienda que la instalación del gadget se realice como parte de una instalación de Microsoft Installer (MSI).

Importante Las aplicaciones no deben llamar a RunGadget sin pedir permiso al usuario por primera vez. Si la opción se asigna al usuario como casilla de verificación, esa casilla debe no estar seleccionada de forma predeterminada.
 
El gadget se agrega al escritorio en una posición determinada por el sistema. El autor de la llamada no puede especificar la ubicación.

Las aplicaciones por usuario deben instalar sus gadgets por usuario. Las aplicaciones por máquina deben instalar sus gadgets por máquina. Esto garantiza una experiencia unificada para el usuario.

Ejemplos

En el ejemplo siguiente se muestra IDesktopGadget::RunGadget en uso.

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

Requisitos

   
Cliente mínimo compatible Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado shobjidl.h