Função ShellExecuteExA (shellapi.h)

  • Artigo

Executa uma operação em um arquivo especificado.

Sintaxe

BOOL ShellExecuteExA(
  [in, out] SHELLEXECUTEINFOA *pExecInfo
);

Parâmetros

[in, out] pExecInfo

Tipo: SHELLEXECUTEINFO*

Um ponteiro para uma estrutura SHELLEXECUTEINFO que contém e recebe informações sobre o aplicativo que está sendo executado.

Valor retornado

Tipo: BOOL

Retorna TRUE se tiver êxito; caso contrário, FALSE. Chame GetLastError para obter informações de erro estendidas.

Comentários

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

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Há instâncias em que ShellExecuteEx não usa um desses tipos de extensão do Shell e essas instâncias não exigem que o COM seja inicializado. No entanto, é uma boa prática sempre inicializar COM antes de usar essa função.

Quando as DLLs são carregadas em seu processo, você adquire um bloqueio conhecido como bloqueio do carregador. A função DllMain sempre é executada sob o bloqueio do carregador. É importante que você não chame ShellExecuteEx enquanto mantém um bloqueio do carregador. Como ShellExecuteEx é extensível, você pode carregar código que não funciona corretamente na presença de um bloqueio do carregador, arriscando um deadlock e, portanto, um thread sem resposta.

Com vários monitores, se você especificar um HWND e definir o membro lpVerb da estrutura SHELLEXECUTEINFO apontada por lpExecInfo como "Propriedades", qualquer janela criada por ShellExecuteEx poderá não aparecer na posição correta.

Se a função for bem-sucedida, ela definirá o membro hInstApp da estrutura SHELLEXECUTEINFO como um valor maior que 32. Se a função falhar, hInstApp será definido como o valor de erro SE_ERR_XXX que melhor indica a causa da falha. Embora hInstApp seja declarado como um HINSTANCE para compatibilidade com aplicativos windows de 16 bits, ele não é um HINSTANCE verdadeiro. Ele só pode ser convertido em um int e pode ser comparado apenas ao valor 32 ou aos códigos de erro SE_ERR_XXX.

Os valores de erro SE_ERR_XXX são fornecidos para compatibilidade com ShellExecute. Para recuperar informações de erro mais precisas, use GetLastError. Ele pode retornar um dos valores a seguir.

Erro Descrição
ERROR_FILE_NOT_FOUND O arquivo especificado não foi encontrado.
ERROR_PATH_NOT_FOUND O caminho especificado não foi encontrado.
ERROR_DDE_FAIL Falha na transação DDE (Troca Dinâmica de Dados).
ERROR_NO_ASSOCIATION Não há nenhum aplicativo associado à extensão de nome de arquivo especificada.
ERROR_ACCESS_DENIED O acesso ao arquivo especificado é negado.
ERROR_DLL_NOT_FOUND Um dos arquivos de biblioteca necessários para executar o aplicativo não pode ser encontrado.
ERROR_CANCELLED A função solicitou ao usuário informações adicionais, mas o usuário cancelou a solicitação.
ERROR_NOT_ENOUGH_MEMORY Não há memória suficiente para executar a ação especificada.
ERROR_SHARING_VIOLATION Ocorreu uma violação de compartilhamento.
 

Abrindo itens de uma URL Você pode registrar seu aplicativo para ativar quando passar URLs. Você também pode especificar quais protocolos seu aplicativo dá suporte. Consulte Registro de Aplicativo para obter mais informações.

Suporte à cadeia de sites A partir do Windows 8, você pode fornecer um ponteiro de cadeia de sites para a função ShellExecuteEx para dar suporte à ativação de item com serviços desse site. Consulte Iniciando aplicativos (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO) para obter mais informações.

Observação

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

Requisitos

   
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shellapi.h
Biblioteca Shell32.lib
DLL Shell32.dll (versão 3.51 ou posterior)

Confira também

Coinitializeex

IShellExecuteHook

Iniciando aplicativos (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecute