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
Necessário. 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 |
| SEE_MASK_CLASSKEY (0x00000003) | Use a chave de classe fornecida pelo membro hkeyClass |
| SEE_MASK_IDLIST (0x00000004) | Use a lista de identificadores de item fornecida pelo membro lpIDList |
| SEE_MASK_INVOKEIDLIST (0x0000000C) | Use a interface IContextMenu
Observação: 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.
Observação: Esse sinalizador é usado somente no Windows XP e anteriores. 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 do hProcess recebe o identificador do processo. Esse identificador normalmente é usado para permitir que um aplicativo descubra quando um processo criado com ShellExecuteEx termina. Em alguns casos, como quando a execução é atendida por meio de uma conversa de 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 devem sempre 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 tiver especificado 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 personalizado notificou ShellExecuteEx que ele foi feito. Se o sinalizador SEE_MASK_WAITFORINPUTIDLE for especificado, ShellExecuteEx chamará 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) | O mesmo que SEE_MASK_NOASYNC, o uso dessa opção é preferencial. |
| SEE_MASK_DOENVSUBST (0x00000200) | Expanda 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 as caixas de diálogo de erro da interface do usuário que normalmente seriam apresentadas sem essa opção. Os prompts de segurança são isentos e ainda serão mostrados. |
| 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 que o thread em segundo plano seja concluído. 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 do hMonitor. Esse sinalizador não pode ser combinado com SEE_MASK_ICON. |
| SEE_MASK_NOZONECHECKS (0x00800000) | Não execute uma verificação de zona. Esse sinalizador permite que ShellExecuteEx ignore a verificação de zona colocada em prática 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 à função ShellExecute, ao processo de associação do manipulador e aos manipuladores de verbo invocados.
ICreatingProcess pode ser fornecido para permitir que o chamador altere alguns parâmetros do processo que está sendo criado. Esse sinalizador tem suporte no Windows 8 e posterior. Quando essa opção é especificada, a chamada é executada de forma síncrona no thread de chamada. |
hwnd
Tipo: HWND
Opcional. Um identificador para a janela do 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 computado. 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á.
- explorar: explora a pasta especificada por lpFile.
- localizar: inicia uma pesquisa a partir do diretório especificado.
abrir : abre o arquivo especificado pelo parâmetro lpFile. O arquivo pode ser um arquivo executável, um arquivo de documento ou uma pasta. - abrir como: inicia uma interface do usuário do seletor permitindo que o usuário selecione um aplicativo com o qual abrir o arquivo especificado pelo parâmetro lpFile.
- imprimir: 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.
- executar como: 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 shell por meio do registro do sistema, como "reproduzir" para arquivos .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
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
Necessário. Sinalizadores que especificam como um aplicativo deve ser mostrado quando ele é aberto; um dos valores SW_ listados para a função
hInstApp
Tipo: HINSTANCE
[out] Se SEE_MASK_NOCLOSEPROCESS estiver definida 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, não é uma HINSTANCE verdadeira. Ele pode ser convertido apenas em um int e comparado a 32 ou os seguintes códigos de erro SE_ERR_XXX.
| Código de erro | Razão |
|---|---|
| SE_ERR_FNF (2) | Arquivo não encontrado. |
| 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 de ITEMIDLIST de
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 shell. Essa chave terá uma subchave que esteja em conformidade com o esquema do registro de verbo shell, como shell\nome do verbo.
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 da 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 de 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 está 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 tiver sido iniciado. Por exemplo, se um documento a ser iniciado for uma URL e uma instância do Internet Explorer já estiver em execução, ele exibirá o documento. Nenhum novo processo é iniciado e hProcess será NULL.
Observações
O sinalizador SEE_MASK_NOASYNC deve ser especificado se a chamada de thread ShellExecuteEx não tiver um loop de mensagem ou se o thread ou processo terminar logo após ShellExecuteEx retornar. Nessas condições, o thread de chamada não estará disponível para concluir a conversa DDE, portanto, é importante que ShellExecuteEx concluir a conversa antes de retornar o controle para o aplicativo de chamada. A falha na conclusão da 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 a chamada para ShellExecuteEx retornar, 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 em um par de 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".
Nota
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. 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] |
| cabeçalho | shellapi.h |