Função ShellExecuteExA (shellapi.h)

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 de retorno

Tipo: BOOL

Retorna verdadeiro se bem-sucedido; caso contrário, FALSE . Chame GetLastError para obter informações de erro estendidas.

Observações

Como ShellExecuteEx pode delegar a execução a extensões do Shell (fontes de dados, manipuladores de menu de contexto, implementações de verbo) ativadas usando o COM (Component Object Model), a COM deve ser inicializada antes que ShellExecuteEx seja 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)

Há instâncias em que ShellExecuteEx não usa um desses tipos de extensão 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 de 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 de carregador. Como ShellExecuteEx é extensível, você pode carregar um 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 lpVerb membro da estrutura SHELLEXECUTEINFO apontada por lpExecInfo como "Propriedades", qualquer janela criada pelo ShellExecuteEx poderá não aparecer na posição correta.

Se a função for bem-sucedida, ela definirá o hInstApp membro da estrutura de 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, não é uma HINSTANCE verdadeira. 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 (Dynamic Data Exchange).
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.

 

Abrir 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 de 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 aplicativos de inicialização (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO) para obter mais informações.

Nota

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

IShellExecuteHook

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

ShellExecute