Função ShellExecuteW (shellapi.h)

Executa uma operação em um arquivo especificado.

Sintaxe

HINSTANCE ShellExecuteW(
  [in, optional] HWND    hwnd,
  [in, optional] LPCWSTR lpOperation,
  [in]           LPCWSTR lpFile,
  [in, optional] LPCWSTR lpParameters,
  [in, optional] LPCWSTR lpDirectory,
  [in]           INT     nShowCmd
);

Parâmetros

[in, optional] hwnd

Tipo: HWND

Um identificador para a janela pai usada para exibir uma interface do usuário ou mensagens de erro. Esse valor poderá ser NULL se a operação não estiver associada a uma janela.

[in, optional] lpOperation

Tipo: LPCTSTR

Um ponteiro para um cadeia de caracteresterminada nula, referida neste caso como umde verbo , que especifica a ação a ser executada. O conjunto de verbos disponíveis depende do arquivo ou pasta específico. Em geral, as ações disponíveis no menu de atalho de um objeto estão disponíveis. Os seguintes verbos são comumente usados:

editar

Inicia um editor e abre o documento para edição. Se lpFile não for um arquivo de documento, a função falhará.

explorar

Explora uma pasta especificada por lpFile.

encontrar

Inicia uma pesquisa começando no diretório especificado por lpDirectory.

abrir

Abre o item especificado pelo parâmetro lpFile. O item pode ser um arquivo ou pasta.

imprimir

Imprime o arquivo especificado por lpFile. Se lpFile não for um arquivo de documento, a função falhará.

runas

Inicia um aplicativo como Administrador. O UAC (Controle de Conta de Usuário) solicitará ao usuário consentimento para executar o aplicativo com privilégios elevados ou inserir as credenciais de uma conta de administrador usada para executar o aplicativo.

ZERO

O verbo padrão é usado, se disponível. Caso contrário, o verbo "abrir" será usado. Se nenhum dos verbos estiver disponível, o sistema usará o primeiro verbo listado no registro.

[in] lpFile

Tipo: LPCTSTR

Um ponteiro para um cadeia de caracteresterminada nula que especifica o arquivo ou objeto no qual executar o verbo especificado. Para especificar um objeto de namespace shell, passe o nome de análise totalmente qualificado. Observe que nem todos os verbos têm suporte em todos os objetos. Por exemplo, nem todos os tipos de documento dão suporte ao verbo "print". Se um caminho relativo for usado para o parâmetro lpDirectory não use um caminho relativo para lpFile.

[in, optional] lpParameters

Tipo: LPCTSTR

Se lpFile especificar um arquivo executável, esse parâmetro será um ponteiro para um cadeia de caracteres nulaterminada que especifica os parâmetros a serem passados para o aplicativo. O formato dessa cadeia de caracteres é determinado pelo verbo que deve ser invocado. Se lpFile especificar um arquivo de documento, lpParameters deverão ser NULL.

[in, optional] lpDirectory

Tipo: LPCTSTR

Um ponteiro para um cadeia de caracteresterminada nulo que especifica o diretório padrão (funcionando) para a ação. Se esse valor for NULL, o diretório de trabalho atual será usado. Se um caminho relativo for fornecido em lpFile, não use um caminho relativo para lpDirectory.

[in] nShowCmd

Tipo: INT

Os sinalizadores que especificam como um aplicativo deve ser exibido quando ele é aberto. Se lpFile especificar um arquivo de documento, o sinalizador será simplesmente passado para o aplicativo associado. Cabe ao aplicativo decidir como lidar com ele. Pode ser qualquer um dos valores que podem ser especificados no parâmetro nCmdShow para a função ShowWindow.

Valor de retorno

Tipo: HINSTANCE

Se a função for bem-sucedida, ela retornará um valor maior que 32. Se a função falhar, ela retornará um valor de erro que indica a causa da falha. O valor retornado é convertido como um HINSTANCE para compatibilidade com versões anteriores com aplicativos Windows de 16 bits. No entanto, não é um verdadeiro HINSTANCE. Ele pode ser convertido apenas em um INT_PTR e comparado a 32 ou aos seguintes códigos de erro abaixo.

Código de retorno	Descrição
0	O sistema operacional está sem memória ou recursos.
ERROR_FILE_NOT_FOUND	O arquivo especificado não foi encontrado.
ERROR_PATH_NOT_FOUND	O caminho especificado não foi encontrado.
ERROR_BAD_FORMAT	O arquivo .exe é inválido (não Win32 .exe ou erro em .exe imagem).
SE_ERR_ACCESSDENIED	O sistema operacional negou acesso ao arquivo especificado.
SE_ERR_ASSOCINCOMPLETE	A associação de nome de arquivo é incompleta ou inválida.
SE_ERR_DDEBUSY	A transação DDE não pôde ser concluída porque outras transações DDE estavam sendo processadas.
SE_ERR_DDEFAIL	Falha na transação DDE.
SE_ERR_DDETIMEOUT	A transação DDE não pôde ser concluída porque a solicitação atingiu o tempo limite.
SE_ERR_DLLNOTFOUND	A DLL especificada não foi encontrada.
SE_ERR_FNF	O arquivo especificado não foi encontrado.
SE_ERR_NOASSOC	Não há nenhum aplicativo associado à extensão de nome de arquivo fornecida. Esse erro também será retornado se você tentar imprimir um arquivo que não seja imprimível.
SE_ERR_OOM	Não havia memória suficiente para concluir a operação.
SE_ERR_PNF	O caminho especificado não foi encontrado.
SE_ERR_SHARE	Ocorreu uma violação de compartilhamento.

Chame GetLastError para obter informações de erro estendidas.

Observações

Como shellExecute pode delegar a execução a extensões shell (fontes de dados, manipuladores de menu de contexto, implementações de verbo) que são ativadas usando COM (Component Object Model), COM deve ser inicializada antes de ShellExecute é chamado. Algumas extensões do Shell exigem o tipo STA (apartamento com thread único) COM. Nesse caso, o COM deve ser inicializado, conforme mostrado aqui:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Certamente há instâncias em que ShellExecute não usa um desses tipos de extensão shell e essas instâncias não exigiriam que COM fosse inicializado. No entanto, é uma boa prática sempre inicializar COM antes de usar essa função.

Esse método permite executar todos os comandos no menu de atalho de uma pasta ou armazenados no Registro.

Para abrir uma pasta, use uma das seguintes chamadas:

ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

ou

ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Para explorar uma pasta, use a seguinte chamada:

ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Para iniciar o utilitário Find do Shell para um diretório, use a chamada a seguir.

ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);

Se lpOperation for NULL, a função abrirá o arquivo especificado por lpFile. Se lpOperation for "open" ou "explore", a função tentará abrir ou explorar a pasta.

Para obter informações sobre o aplicativo que é iniciado como resultado da chamada ShellExecute, use ShellExecuteEx.

Observação As janelas da pasta iniciar em um processo separado configuração em Opções de Pasta afeta ShellExecute. Se essa opção estiver desabilitada (a configuração padrão), ShellExecute usará uma janela aberta do Explorer em vez de iniciar uma nova. Se nenhuma janela do Explorer estiver aberta, ShellExecute iniciará uma nova.

 

Nota

O cabeçalho shellapi.h define ShellExecute como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shellapi.h
biblioteca	Shell32.lib
de DLL	Shell32.dll (versão 3.51 ou posterior)

Consulte também

CoInitializeEx

CreateProcessW

IShellExecuteHook

aplicativos de inicialização (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecuteEx