Iniciando aplicativos (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

Uma vez que seu aplicativo tenha localizado um objeto de arquivo, a próxima etapa geralmente é agir sobre ele de alguma forma. Por exemplo, seu aplicativo pode querer iniciar outro aplicativo que permita ao usuário modificar um arquivo de dados. Se o arquivo de interesse for um executável, seu aplicativo pode querer simplesmente iniciá-lo. Este documento discute como usar ShellExecute ou ShellExecuteEx para executar essas tarefas.

• Usando ShellExecute e ShellExecuteEx
  • Verbos de objeto
  • Utilizar o ShellExecuteEx para fornecer serviços de ativação a partir de um site
  • Usando ShellExecute para iniciar a caixa de diálogo de Pesquisa
• Um exemplo simples de como usar o ShellExecuteEx

Usando ShellExecute e ShellExecuteEx

Para usar ShellExecute ou ShellExecuteEx, seu aplicativo deve especificar o objeto de arquivo ou pasta que deve ser acionado e um verbo que especifica a operação. Para ShellExecute, atribua esses valores aos parâmetros apropriados. Para ShellExecuteEx, preencha os membros apropriados de uma estrutura SHELLEXECUTEINFO. Há também vários outros membros ou parâmetros que podem ser usados para ajustar o comportamento das duas funções.

Os objetos de arquivo e pasta podem fazer parte do sistema de arquivos ou objetos virtuais e podem ser identificados por caminhos ou ponteiros para listas de identificadores de itens (PIDLs).

Verbos de objeto

Os verbos disponíveis para um objeto são essencialmente os itens que você encontra no menu de atalho de um objeto. Para encontrar quais verbos estão disponíveis, procure no registro em

HKEY_CLASSES_ROOT\CLSID\{object_clsid}\Shell\verbo

onde object_clsid é o identificador de classe (CLSID) do objeto e verbo é o nome do verbo disponível. O verbo\comando subchave contém os dados que indicam o que acontece quando esse verbo é invocado.

Para descobrir quais verbos estão disponíveis para objetos Shell predefinidos, verifique o registo em

HKEY_CLASSES_ROOT\object_name\shell\verbo

onde object_name é o nome do objeto Shell predefinido. Novamente, a subchavedo comando verb \ contém os dados que indicam o que ocorre quando esse verbo é invocado.

Os verbos comumente disponíveis incluem:

Cada verbo corresponde ao comando que seria usado para iniciar o aplicativo a partir de uma janela do console. O verbo abrir é um bom exemplo, pois é comumente suportado. Para os ficheiros .exe, abrir simplesmente lança a aplicação. No entanto, é mais comumente usado para iniciar um aplicativo que opera em um arquivo específico. Por exemplo, .txt arquivos podem ser abertos pelo Microsoft WordPad. O verbo abrir para um arquivo .txt corresponderia assim a algo como o seguinte comando:

"C:\Program Files\Windows NT\Accessories\Wordpad.exe" "%1"

Quando você usa ShellExecute ou ShellExecuteEx para abrir um arquivo .txt, Wordpad.exe é iniciado com o arquivo especificado como argumento. Alguns comandos podem ter argumentos adicionais, como sinalizadores, que podem ser adicionados conforme necessário para iniciar o aplicativo corretamente. Para obter mais informações sobre menus de atalho e verbos, consulte Estendendo menus de atalho.

Em geral, tentar determinar a lista de verbos disponíveis para um determinado arquivo é um pouco complicado. Em muitos casos, você pode simplesmente definir o parâmetro lpVerb como NULL, que invoca o comando padrão para o tipo de arquivo. Este procedimento é geralmente equivalente a definir lpVerb para "abrir", mas alguns tipos de arquivo podem ter um comando padrão diferente. Para obter mais informações, consulte Estendendo menus de atalho e a documentação de referência do ShellExecuteEx.

Usando o ShellExecuteEx para fornecer serviços de ativação de um site

Os serviços de uma cadeia de sites podem controlar muitos comportamentos de ativação de itens. A partir do Windows 8, você pode fornecer um ponteiro para a cadeia de sites para ShellExecuteEx para habilitar esses comportamentos. Para disponibilizar o site para ShellExecuteEx:

• Especifique o sinalizador SEE_MASK_FLAG_HINST_IS_SITE no fMask membro de SHELLEXECUTEINFO.
• Forneça o IUnknown no hInstApp membro de SHELLEXECUTEINFO.

Usando ShellExecute para abrir a caixa de diálogo de pesquisa

Quando um usuário clica com o botão direito do mouse em um ícone de pasta no Windows Explorer, um dos itens de menu é "Pesquisar". Se eles selecionarem esse item, o Shell iniciará seu utilitário de pesquisa. Este utilitário exibe uma caixa de diálogo que pode ser usada para pesquisar arquivos para uma cadeia de texto especificada. Um aplicativo pode iniciar programaticamente o utilitário Search para um diretório chamando ShellExecute, com "find" como o parâmetro lpVerb e o caminho do diretório como o parâmetro lpFile . Por exemplo, a seguinte linha de código inicia o utilitário de pesquisa para o diretório c:\MyPrograms.

ShellExecute(hwnd, "find", "c:\\MyPrograms", NULL, NULL, 0);

Um exemplo simples de como usar ShellExecuteEx

O aplicativo de console de exemplo a seguir ilustra o uso do ShellExecuteEx. A maioria dos códigos de verificação de erros foi omitida para maior clareza.

#include <shlobj.h>
#include <shlwapi.h>
#include <objbase.h>

main()
{
    LPITEMIDLIST pidlWinFiles = NULL;
    LPITEMIDLIST pidlItems = NULL;
    IShellFolder *psfWinFiles = NULL;
    IShellFolder *psfDeskTop = NULL;
    LPENUMIDLIST ppenum = NULL;
    STRRET strDispName;
    TCHAR pszParseName[MAX_PATH];
    ULONG celtFetched;
    SHELLEXECUTEINFO ShExecInfo;
    HRESULT hr;
    BOOL fBitmap = FALSE;

    hr = SHGetFolderLocation(NULL, CSIDL_WINDOWS, NULL, NULL, &pidlWinFiles);

    hr = SHGetDesktopFolder(&psfDeskTop);

    hr = psfDeskTop->BindToObject(pidlWinFiles, NULL, IID_IShellFolder, (LPVOID *) &psfWinFiles);
    hr = psfDeskTop->Release();

    hr = psfWinFiles->EnumObjects(NULL,SHCONTF_FOLDERS | SHCONTF_NONFOLDERS, &ppenum);

    while( hr = ppenum->Next(1,&pidlItems, &celtFetched) == S_OK && (celtFetched) == 1)
    {
        psfWinFiles->GetDisplayNameOf(pidlItems, SHGDN_FORPARSING, &strDispName);
        StrRetToBuf(&strDispName, pidlItems, pszParseName, MAX_PATH);
        CoTaskMemFree(pidlItems);
        if(StrCmpI(PathFindExtension(pszParseName), TEXT( ".bmp")) == 0)
        {
            fBitmap = TRUE;
            break;
        }
    }

    ppenum->Release();

    if(fBitmap)
    {
        ShExecInfo.cbSize = sizeof(SHELLEXECUTEINFO);
        ShExecInfo.fMask = NULL;
        ShExecInfo.hwnd = NULL;
        ShExecInfo.lpVerb = NULL;
        ShExecInfo.lpFile = pszParseName;
        ShExecInfo.lpParameters = NULL;
        ShExecInfo.lpDirectory = NULL;
        ShExecInfo.nShow = SW_MAXIMIZE;
        ShExecInfo.hInstApp = NULL;

        ShellExecuteEx(&ShExecInfo);
    }

    CoTaskMemFree(pidlWinFiles);
    psfWinFiles->Release();

    return 0;
}

O aplicativo primeiro recupera o PIDL do diretório do Windows e enumera seu conteúdo até encontrar o primeiro arquivo .bmp. Ao contrário do exemplo anterior, IShellFolder::GetDisplayNameOf é usado para recuperar o nome de análise do arquivo em vez de seu nome para exibição. Como esta é uma pasta do sistema de arquivos, o nome de análise é um caminho totalmente qualificado, que é o que é necessário para ShellExecuteEx.

Uma vez que o primeiro arquivo .bmp tenha sido localizado, os valores apropriados são atribuídos aos membros de uma estrutura SHELLEXECUTEINFO. O membro lpFile é definido como o nome de interpretação do ficheiro, e o membro lpVerb como NULL, para iniciar a operação padrão. Neste caso, a operação padrão é "open". A estrutura é então passada para ShellExecuteEx, que inicia o manipulador padrão para arquivos bitmap, normalmente MSPaint.exe, para abrir o arquivo. Depois que a função retorna, os PIDLs são liberados e a interface IShellFolder da pasta do Windows é liberada.