Share via

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

  • Artigo

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.

Nota Esse caminho não deve conter variáveis de ambiente; o caminho totalmente expandido deve ser fornecido. ExpandEnvironmentStrings pode ser usado para expandir o caminho para o formulário necessário nesse parâmetro.
 

(%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:

Código de retorno Descrição
SCHED_E_ALREADY_RUNNING
 O gadget já está funcionando.
E_INVALIDARG
 Ocorreu um erro envolvendo o caminho da pasta gadget apontado por gadgetPath.

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).

Importante Os aplicativos não devem chamar RunGadget sem primeiro pedir permissão ao usuário. Se a opção for dada ao usuário como uma caixa de marcar, essa caixa de marcar deverá ser desmarcada por padrão.
 
O gadget é adicionado à área de trabalho em uma posição determinada pelo sistema. O chamador não pode especificar o local.

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

   
Cliente mínimo com suporte Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shobjidl.h