Estrutura SHELLEXECUTEINFOA (shellapi.h)
Contém informações usadas por ShellExecuteEx.
Sintaxe
typedef struct _SHELLEXECUTEINFOA {
DWORD cbSize;
ULONG fMask;
HWND hwnd;
LPCSTR lpVerb;
LPCSTR lpFile;
LPCSTR lpParameters;
LPCSTR lpDirectory;
int nShow;
HINSTANCE hInstApp;
void *lpIDList;
LPCSTR lpClass;
HKEY hkeyClass;
DWORD dwHotKey;
union {
HANDLE hIcon;
HANDLE hMonitor;
} DUMMYUNIONNAME;
HANDLE hProcess;
} SHELLEXECUTEINFOA, *LPSHELLEXECUTEINFOA;
Membros
cbSize
Tipo: DWORD
Obrigatórios. O tamanho dessa estrutura, em bytes.
fMask
Tipo: ULONG
Uma combinação de um ou mais dos seguintes valores que indicam o conteúdo e a validade dos outros membros da estrutura:
| SEE_MASK_DEFAULT (0x00000000) | Use valores padrão. |
| SEE_MASK_CLASSNAME (0x00000001) | Use o nome da classe fornecido pelo membro lpClass . Se SEE_MASK_CLASSKEY e SEE_MASK_CLASSNAME estiverem definidos, a chave de classe será usada. |
| SEE_MASK_CLASSKEY (0x00000003) | Use a chave de classe fornecida pelo membro hkeyClass . Se SEE_MASK_CLASSKEY e SEE_MASK_CLASSNAME estiverem definidos, a chave de classe será usada. |
| SEE_MASK_IDLIST (0x00000004) | Use a lista de identificadores de item fornecida pelo membro lpIDList . O membro lpIDList deve apontar para uma estrutura ITEMIDLIST . |
| SEE_MASK_INVOKEIDLIST (0x0000000C) | Use a interface IContextMenu do manipulador de menu de atalho do item selecionado. Use lpFile para identificar o item pelo caminho do sistema de arquivos ou lpIDList para identificar o item por seu PIDL. Esse sinalizador permite que os aplicativos usem ShellExecuteEx para invocar verbos de extensões de menu de atalho em vez dos verbos estáticos listados no registro.
Nota: SEE_MASK_INVOKEIDLIST substitui e implica SEE_MASK_IDLIST.
|
| SEE_MASK_ICON (0x00000010) | Use o ícone fornecido pelo membro hIcon . Esse sinalizador não pode ser combinado com SEE_MASK_HMONITOR.
Nota: Esse sinalizador é usado apenas no Windows XP e anterior. Ele é ignorado a partir do Windows Vista.
|
| SEE_MASK_HOTKEY (0x00000020) | Use o atalho de teclado fornecido pelo membro dwHotKey . |
| SEE_MASK_NOCLOSEPROCESS (0x00000040) | Use para indicar que o membro hProcess recebe o identificador do processo. Normalmente, esse identificador é usado para permitir que um aplicativo descubra quando um processo criado com ShellExecuteEx é encerrado. Em alguns casos, como quando a execução é atendida por meio de uma conversa DDE, nenhum identificador será retornado. O aplicativo de chamada é responsável por fechar o identificador quando ele não é mais necessário. |
| SEE_MASK_CONNECTNETDRV (0x00000080) | Valide o compartilhamento e conecte-se a uma letra da unidade. Isso permite a reconexão de unidades de rede desconectadas. O membro lpFile é um caminho UNC de um arquivo em uma rede. |
| SEE_MASK_NOASYNC (0x00000100) | Aguarde a conclusão da operação de execução antes de retornar. Esse sinalizador deve ser usado por chamadores que estão usando formulários ShellExecute que podem resultar em uma ativação assíncrona, por exemplo, DDE, e criar um processo que pode ser executado em um thread em segundo plano. (Observação: ShellExecuteEx é executado em um thread em segundo plano por padrão se o modelo de threading do chamador não for Apartment.) As chamadas para ShellExecuteEx de processos já em execução em threads em segundo plano sempre devem passar esse sinalizador. Além disso, os aplicativos que saem imediatamente após chamar ShellExecuteEx devem especificar esse sinalizador.
Se a operação de execução for executada em um thread em segundo plano e o chamador não especificar o sinalizador SEE_MASK_ASYNCOK, o thread de chamada aguardará até que o novo processo seja iniciado antes de retornar. Isso normalmente significa que CreateProcess foi chamado, a comunicação DDE foi concluída ou que o delegado de execução personalizada notificou ShellExecuteEx de que ele foi feito. Se o sinalizador SEE_MASK_WAITFORINPUTIDLE for especificado, o ShellExecuteExchamará WaitForInputIdle e aguardará o novo processo ficar ocioso antes de retornar, com um tempo limite máximo de 1 minuto. Para obter mais discussões sobre quando esse sinalizador é necessário, consulte a seção Comentários. |
| SEE_MASK_FLAG_DDEWAIT (0x00000100) | Da mesma forma que SEE_MASK_NOASYNC, o uso dessa opção é preferencial. |
| SEE_MASK_DOENVSUBST (0x00000200) | Expanda todas as variáveis de ambiente especificadas na cadeia de caracteres fornecida pelo membro lpDirectory ou lpFile . |
| SEE_MASK_FLAG_NO_UI (0x00000400) | Não exiba nenhuma interface do usuário (interface do usuário), incluindo caixas de diálogo de erro, avisos de segurança ou outra interface do usuário que normalmente seria apresentada sem essa opção. |
| SEE_MASK_UNICODE (0x00004000) | Use esse sinalizador para indicar um aplicativo Unicode. |
| SEE_MASK_NO_CONSOLE (0x00008000) | Use para herdar o console do pai para o novo processo em vez de fazer com que ele crie um novo console. É o oposto de usar um sinalizador de CREATE_NEW_CONSOLE com CreateProcess. |
| SEE_MASK_ASYNCOK (0x00100000) | A execução pode ser executada em um thread em segundo plano e a chamada deve retornar imediatamente sem esperar a conclusão do thread em segundo plano. Observe que, em determinados casos , ShellExecuteEx ignora esse sinalizador e aguarda a conclusão do processo antes de retornar. |
| SEE_MASK_NOQUERYCLASSSTORE (0x01000000) | Não usado. |
| SEE_MASK_HMONITOR (0x00200000) | Use esse sinalizador ao especificar um monitor em sistemas de vários monitores. O monitor é especificado no membro hMonitor . Esse sinalizador não pode ser combinado com SEE_MASK_ICON. |
| SEE_MASK_NOZONECHECKS (0x00800000) | Não execute um marcar de zona. Esse sinalizador permite que ShellExecuteEx ignore a verificação de zona colocada em prática por IAttachmentExecute. |
| SEE_MASK_WAITFORINPUTIDLE (0x02000000) | Depois que o novo processo for criado, aguarde até que o processo fique ocioso antes de retornar, com um tempo limite de um minuto. Consulte WaitForInputIdle para obter mais detalhes. |
| SEE_MASK_FLAG_LOG_USAGE (0x04000000) | Indica uma inicialização iniciada pelo usuário que permite o acompanhamento de programas usados com frequência e outros comportamentos. |
| SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) | O membro hInstApp é usado para especificar o IUnknown de um objeto que implementa IServiceProvider. Esse objeto será usado como um ponteiro do site. O ponteiro do site é usado para fornecer serviços para a função ShellExecute , o processo de associação do manipulador e manipuladores de verbo invocados.
O ICreatingProcess pode ser fornecido para permitir que o chamador altere alguns parâmetros do processo que está sendo criado. Esse sinalizador tem suporte em Windows 8 e posteriores. Quando essa opção é especificada, a chamada é executada de forma síncrona no thread de chamada. |
hwnd
Digite: HWND
Opcional. Um identificador para a janela de proprietário, usado para exibir e posicionar qualquer interface do usuário que o sistema possa produzir durante a execução dessa função.
lpVerb
Tipo: LPCTSTR
Uma cadeia de caracteres, conhecida como 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. Esse parâmetro pode ser NULL, nesse caso, o verbo padrão será 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. A menos que haja um motivo para limitar a ação a um verbo específico, passe NULL para usar o padrão calculado. Isso é necessário em alguns casos, por exemplo, ao especificar SEE_MASK_FLAG_NO_UI e a intenção é produzir a interface do usuário "Abrir com", se nenhum aplicativo estiver instalado.
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á.
- explore: explora a pasta especificada por lpFile.
- find: inicia uma pesquisa a partir do diretório especificado.
- open: abre o arquivo especificado pelo parâmetro lpFile . O arquivo pode ser um arquivo executável, um arquivo de documento ou uma pasta.
- print: imprime o arquivo de documento especificado por lpFile. Se lpFile não for um arquivo de documento, a função falhará.
- propriedades: exibe as propriedades do arquivo ou da pasta.
- 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.
lpFile
Tipo: LPCTSTR
O endereço de uma cadeia de caracteres terminada em nulo que especifica o nome do arquivo ou objeto no qual ShellExecuteEx executará a ação especificada pelo parâmetro lpVerb . Os verbos do registro do sistema compatíveis com a função ShellExecuteEx incluem "open" para arquivos executáveis e arquivos de documento e "print" para arquivos de documento para os quais um manipulador de impressão foi registrado. Outros aplicativos podem ter adicionado verbos do Shell por meio do registro do sistema, como "reproduzir" para arquivos de .avi e .wav. Para especificar um objeto de namespace shell, passe o nome de análise totalmente qualificado e defina o sinalizador SEE_MASK_INVOKEIDLIST no parâmetro fMask .
lpParameters
Tipo: LPCTSTR
Opcional. O endereço de uma cadeia de caracteres terminada em nulo que contém os parâmetros do aplicativo. Os parâmetros devem ser separados por espaços. Se o membro lpFile especificar um arquivo de documento, lpParameters deverá ser NULL.
lpDirectory
Tipo: LPCTSTR
Opcional. O endereço de uma cadeia de caracteres terminada em nulo que especifica o nome do diretório de trabalho. Se esse membro for NULL, o diretório atual será usado como o diretório de trabalho.
nShow
Tipo: int
Obrigatórios. Sinalizadores que especificam como um aplicativo deve ser mostrado quando ele é aberto; um dos valores de SW_ listados para a função ShellExecute . Se lpFile especificar um arquivo de documento, o sinalizador será simplesmente passado para o aplicativo associado. Cabe ao aplicativo decidir como lidar com ele.
hInstApp
Tipo: HINSTANCE
[out] Se SEE_MASK_NOCLOSEPROCESS for definido e a chamada ShellExecuteEx for bem-sucedida, ele definirá esse membro como um valor maior que 32. Se a função falhar, ela será definida como um valor de erro SE_ERR_XXX que 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 pode ser convertido apenas em um int e comparado a 32 ou os seguintes códigos de erro SE_ERR_XXX.
| Código do Erro | Motivo |
|---|---|
| SE_ERR_FNF (2) | Arquivo não localizado. |
| SE_ERR_PNF (3) | Caminho não encontrado. |
| SE_ERR_ACCESSDENIED (5) | Acesso negado. |
| SE_ERR_OOM (8) | Sem memória. |
| SE_ERR_DLLNOTFOUND (32) | Biblioteca de vínculo dinâmico não encontrada. |
| SE_ERR_SHARE (26) | Não é possível compartilhar um arquivo aberto. |
| SE_ERR_ASSOCINCOMPLETE (27) | Informações de associação de arquivo não concluídas. |
| SE_ERR_DDETIMEOUT (28) | A operação DDE atingiu o tempo limite. |
| SE_ERR_DDEFAIL (29) | Falha na operação DDE. |
| SE_ERR_DDEBUSY (30) | A operação DDE está ocupada. |
| SE_ERR_NOASSOC (31) | Associação de arquivos não disponível. |
lpIDList
Tipo: LPVOID
O endereço de uma estrutura ITEMIDLIST absoluta (PCIDLIST_ABSOLUTE) para conter uma lista de identificadores de item que identifica exclusivamente o arquivo a ser executado. Esse membro será ignorado se o membro fMask não incluir SEE_MASK_IDLIST ou SEE_MASK_INVOKEIDLIST.
lpClass
Tipo: LPCTSTR
O endereço de uma cadeia de caracteres terminada em nulo que especifica um dos seguintes:
- Um ProgId. Por exemplo, "Paint.Picture".
- Um esquema de protocolo URI. Por exemplo, "http".
- Uma extensão de arquivo. Por exemplo, ".txt".
- Um caminho do Registro em HKEY_CLASSES_ROOT que nomeia uma subchave que contém um ou mais verbos do Shell. Essa chave terá uma subchave que está em conformidade com o esquema do registro de verbo do Shell, comoo nome do verbo do shell\.
Esse membro será ignorado se fMask não incluir SEE_MASK_CLASSNAME.
hkeyClass
Tipo: HKEY
Um identificador para a chave do Registro para o tipo de arquivo. Os direitos de acesso para essa chave do Registro devem ser definidos como KEY_READ. Esse membro será ignorado se fMask não incluir SEE_MASK_CLASSKEY.
dwHotKey
Tipo: DWORD
Um atalho de teclado a ser associado ao aplicativo. A palavra de baixa ordem é o código de chave virtual e a palavra de alta ordem é um sinalizador modificador (HOTKEYF_). Para obter uma lista de sinalizadores modificador, consulte a descrição da mensagem WM_SETHOTKEY . Esse membro será ignorado se fMask não incluir SEE_MASK_HOTKEY.
DUMMYUNIONNAME
DUMMYUNIONNAME.hIcon
Tipo: HANDLE
Um identificador para o ícone do tipo de arquivo. Esse membro será ignorado se fMask não incluir SEE_MASK_ICON. Esse valor é usado apenas no Windows XP e anterior. Ele é ignorado a partir do Windows Vista.
DUMMYUNIONNAME.hMonitor
Tipo: HANDLE
Um identificador para o monitor no qual o documento deve ser exibido. Esse membro será ignorado se fMask não incluir SEE_MASK_HMONITOR.
hProcess
Tipo: HANDLE
Um identificador para o aplicativo recém-iniciado. Esse membro é definido no retorno e é sempre NULL , a menos que fMask esteja definido como SEE_MASK_NOCLOSEPROCESS. Mesmo que fMask esteja definido como SEE_MASK_NOCLOSEPROCESS, hProcess será NULL se nenhum processo for iniciado. Por exemplo, se um documento a ser iniciado for uma URL e uma instância da Internet Explorer já estiver em execução, ele exibirá o documento. Nenhum novo processo é iniciado e hProcess será NULL.
Comentários
O sinalizador SEE_MASK_NOASYNC deverá ser especificado se o thread que chama ShellExecuteEx não tiver um loop de mensagem ou se o thread ou processo for encerrado logo após o retorno de ShellExecuteEx . Nessas condições, o thread de chamada não estará disponível para concluir a conversa DDE, portanto, é importante que ShellExecuteEx conclua a conversa antes de retornar o controle para o aplicativo de chamada. A falha ao concluir a conversa pode resultar em uma inicialização malsucedida do documento.
Se o thread de chamada tiver um loop de mensagem e existir por algum tempo após o retorno da chamada para ShellExecuteEx , o sinalizador SEE_MASK_NOASYNC será opcional. Se o sinalizador for omitido, a bomba de mensagem do thread de chamada será usada para concluir a conversa DDE. O aplicativo de chamada recupera o controle mais cedo, já que a conversa DDE pode ser concluída em segundo plano.
Para incluir aspas duplas em lpParameters, coloque cada marca entre aspas, como no exemplo a seguir.
sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";
Nesse caso, o aplicativo recebe três parâmetros: Um, exemplo:, e "texto entre aspas".
Observação
O cabeçalho shellapi.h define SHELLEXECUTEINFO 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
| Requisito | Valor |
|---|---|
| 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] |
| Cabeçalho | shellapi.h |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de