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

Adiciona um gadget instalado à área de trabalho.

Sintaxe

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

Parâmetros

[in] gadgetPath

Tipo: LPCWSTR

Ponteiro para o caminho completo (absoluto) de uma pasta .gadget. Um gadget que não é empacotado com o Windows só pode ser executado em um dos dois locais a seguir. A instalação do gadget em qualquer outro local fará com que esse método falhe com um erro de acesso negado.

(%ProgramFiles%\Windows Sidebar\Shared Gadgets)

Esse é o caminho recomendado para a instalação de gadget que não é da Microsoft, disponível para todos os usuários.

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

Esse local deve ser usado para uma instalação de usuário único do gadget.

Valor retornado

Tipo: HRESULT

Retorna S_OK se tiver êxito ou um valor de erro, caso contrário, incluindo o seguinte:

Comentários

"Executar" um gadget aqui significa que o gadget é adicionado à área de trabalho.

RunGadget só pode ser chamado em um gadget que já foi instalado no sistema. Ele não pode ser chamado em um gadget que já está em execução— apenas uma instância de um gadget pode ser executada a qualquer momento por meio desse método.

Como a instalação do gadget não tem interface do usuário própria, esse método geralmente é executado como a última etapa no processo de instalação ou como parte do primeiro lançamento de um aplicativo ao qual o gadget está associado. A instalação do gadget em %ProgramFiles%\Windows Sidebar\Shared Gadgets requer privilégios administrativos. Portanto, é recomendável que a instalação do gadget seja executada como parte de uma instalação do MSI (Microsoft Installer).

Os aplicativos por usuário devem instalar seus gadgets por usuário. Os aplicativos por computador devem instalar seus gadgets por computador. Isso garante uma experiência unificada para o usuário.

Exemplos

O exemplo a seguir mostra IDesktopGadget::RunGadget em 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