Struttura SHELLEXECUTEINFOA (shellapi.h)

Contiene informazioni usate da ShellExecuteEx.

Sintassi

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;

Membri

cbSize

Tipo: DWORD

Obbligatorio. Dimensioni di questa struttura, in byte.

fMask

Tipo: ULONG

Combinazione di uno o più dei valori seguenti che indicano il contenuto e la validità degli altri membri della struttura:

SEE_MASK_DEFAULT (0x00000000) Usare i valori predefiniti.
SEE_MASK_CLASSNAME (0x00000001) Usare il nome della classe specificato dal membro lpClass. Se vengono impostati sia SEE_MASK_CLASSKEY che SEE_MASK_CLASSNAME, viene usata la chiave di classe.
SEE_MASK_CLASSKEY (0x00000003) Usare la chiave di classe specificata dal membro hkeyClass . Se vengono impostati sia SEE_MASK_CLASSKEY che SEE_MASK_CLASSNAME, viene usata la chiave di classe.
SEE_MASK_IDLIST (0x00000004) Usare l'elenco di identificatori di elemento fornito dal membro lpIDList . Il membro lpIDList deve puntare a una struttura ITEMIDLIST .
SEE_MASK_INVOKEIDLIST (0x0000000C) Usare l'interfaccia IContextMenu del gestore di menu di scelta rapida dell'elemento selezionato. Usare lpFile per identificare l'elemento in base al percorso del file system o lpIDList per identificare l'elemento in base al relativo PIDL. Questo flag consente alle applicazioni di usare ShellExecuteEx per richiamare verbi dalle estensioni del menu di scelta rapida anziché dai verbi statici elencati nel Registro di sistema.
Nota: SEE_MASK_INVOKEIDLIST sostituzioni e implica SEE_MASK_IDLIST.
SEE_MASK_ICON (0x00000010) Usare l'icona specificata dal membro hIcon. Questo flag non può essere combinato con SEE_MASK_HMONITOR.
Nota: Questo flag viene usato solo in Windows XP e versioni precedenti. Viene ignorato a partire da Windows Vista.
SEE_MASK_HOTKEY (0x00000020) Usare la scelta rapida da tastiera specificata dal membro dwHotKey.
SEE_MASK_NOCLOSEPROCESS (0x00000040) Usare per indicare che il membro hProcess riceve l'handle di processo. Questo handle viene in genere usato per consentire a un'applicazione di individuare quando un processo creato con ShellExecuteEx termina. In alcuni casi, ad esempio quando l'esecuzione viene soddisfatta tramite una conversazione DDE, non verrà restituito alcun handle. L'applicazione chiamante è responsabile della chiusura dell'handle quando non è più necessaria.
SEE_MASK_CONNECTNETDRV (0x00000080) Convalidare la condivisione e connettersi a una lettera di unità. Ciò consente la riconnessione delle unità di rete disconnesse. Il membro lpFile è un percorso UNC di un file in una rete.
SEE_MASK_NOASYNC (0x00000100) Attendere il completamento dell'operazione di esecuzione prima della restituzione. Questo flag deve essere usato dai chiamanti che usano moduli ShellExecute che potrebbero generare un'attivazione asincrona, ad esempio DDE, e creare un processo che potrebbe essere eseguito in un thread in background. Nota: ShellExecuteEx viene eseguito su un thread in background per impostazione predefinita se il modello di threading del chiamante non è Apartment. Le chiamate a ShellExecuteEx dai processi già in esecuzione nei thread in background devono sempre passare questo flag. Inoltre, le applicazioni che terminano immediatamente dopo aver chiamato ShellExecuteEx devono specificare questo flag.

Se l'operazione di esecuzione viene eseguita su un thread in background e il chiamante non ha specificato il flag di SEE_MASK_ASYNCOK, il thread chiamante attende l'avvio del nuovo processo prima della restituzione. Ciò significa in genere che è stato chiamato CreateProcess, la comunicazione DDE è stata completata o che il delegato di esecuzione personalizzato ha informato ShellExecuteEx che è stato eseguito. Se viene specificato il flag SEE_MASK_WAITFORINPUTIDLE, ShellExecuteEx chiama WaitForInputIdle e attende che il nuovo processo venga inattiva prima della restituzione, con un timeout massimo di 1 minuto.

Per ulteriori informazioni su quando è necessario questo flag, vedere la sezione Osservazioni.

SEE_MASK_FLAG_DDEWAIT (0x00000100) Come SEE_MASK_NOASYNC, è preferibile usare tale opzione.
SEE_MASK_DOENVSUBST (0x00000200) Espandere tutte le variabili di ambiente specificate nella stringa specificata dal membro lpDirectory o lpFile.
SEE_MASK_FLAG_NO_UI (0x00000400) Non visualizzare le finestre di dialogo di errore dell'interfaccia utente che normalmente verrebbero presentate senza questa opzione. Le richieste di sicurezza sono esentate e verranno comunque visualizzate.
SEE_MASK_UNICODE (0x00004000) Usare questo flag per indicare un'applicazione Unicode.
SEE_MASK_NO_CONSOLE (0x00008000) Usare per ereditare la console padre per il nuovo processo anziché crearne una nuova. È l'opposto dell'uso di un flag di CREATE_NEW_CONSOLE con CreateProcess.
SEE_MASK_ASYNCOK (0x00100000) L'esecuzione può essere eseguita su un thread in background e la chiamata deve restituire immediatamente senza attendere il completamento del thread in background. Si noti che in alcuni casi ShellExecuteEx ignora questo flag e attende il completamento del processo prima della restituzione.
SEE_MASK_NOQUERYCLASSSTORE (0x01000000) Non utilizzato.
SEE_MASK_HMONITOR (0x00200000) Usare questo flag quando si specifica un monitoraggio nei sistemi multi-monitor. Il monitoraggio viene specificato nel membro hMonitor. Questo flag non può essere combinato con SEE_MASK_ICON.
SEE_MASK_NOZONECHECKS (0x00800000) Non eseguire un controllo della zona. Questo flag consente ShellExecuteEx di ignorare il controllo della zona inserito IAttachmentExecute.
SEE_MASK_WAITFORINPUTIDLE (0x02000000) Dopo aver creato il nuovo processo, attendere che il processo diventi inattiva prima della restituzione, con un timeout di un minuto. Per altri dettagli, vedere WaitForInputIdle.
SEE_MASK_FLAG_LOG_USAGE (0x04000000) Indica un avvio avviato dall'utente che consente il rilevamento dei programmi usati di frequente e di altri comportamenti.
SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) Il membro hInstApp viene usato per specificare il IUnknown di un oggetto che implementa IServiceProvider. Questo oggetto verrà utilizzato come puntatore del sito. Il puntatore del sito viene usato per fornire servizi alla funzione ShellExecute, al processo di associazione del gestore e ai gestori verbi richiamati.

è possibile fornire ICreatingProcess per consentire al chiamante di modificare alcuni parametri del processo da creare.

Questo flag è supportato in Windows 8 e versioni successive.

Quando questa opzione viene specificata, la chiamata viene eseguita in modo sincrono nel thread chiamante.

hwnd

Tipo: HWND

Opzionale. Handle per la finestra del proprietario, usato per visualizzare e posizionare qualsiasi interfaccia utente che il sistema potrebbe produrre durante l'esecuzione di questa funzione.

lpVerb

Tipo: LPCTSTR

Stringa, definita verbo , che specifica l'azione da eseguire. Il set di verbi disponibili dipende dal file o dalla cartella specifica. In genere, le azioni disponibili dal menu di scelta rapida di un oggetto sono verbi disponibili. Questo parametro può essere NULL, nel qual caso viene usato il verbo predefinito, se disponibile. In caso contrario, viene usato il verbo "open". Se nessun verbo è disponibile, il sistema usa il primo verbo elencato nel Registro di sistema. A meno che non esista un motivo per limitare l'azione a un verbo specifico, passare NULL per usare l'impostazione predefinita calcolata. Ciò è necessario in alcuni casi, ad esempio quando si specifica SEE_MASK_FLAG_NO_UI e l'intenzione è produrre l'interfaccia utente "Apri con", se non sono installate app.

I verbi seguenti vengono comunemente usati:

  • modifica: avvia un editor e apre il documento per la modifica. Se lpFile non è un file di documento, la funzione avrà esito negativo.
  • esplorare: esplora la cartella specificata da lpFile.
  • trovare: avvia una ricerca a partire dalla directory specificata.
  • aprire: apre il file specificato dal parametro lpFile . Il file può essere un file eseguibile, un file di documento o una cartella.
  • openas: avvia un'interfaccia utente di selezione che consente all'utente di selezionare un'app con cui aprire il file specificato dal parametro lpFile.
  • stampa: stampa il file di documento specificato da lpFile. Se lpFile non è un file di documento, la funzione avrà esito negativo.
  • proprietà: visualizza le proprietà del file o della cartella.
  • runas: avvia un'applicazione come amministratore. Controllo account utente richiederà all'utente il consenso per eseguire l'applicazione con privilegi elevati o immettere le credenziali di un account amministratore usato per eseguire l'applicazione.

lpFile

Tipo: LPCTSTR

Indirizzo di una stringa con terminazione Null che specifica il nome del file o dell'oggetto in cui ShellExecuteEx eseguirà l'azione specificata dal parametro lpVerb . I verbi del Registro di sistema supportati dalla funzione ShellExecuteEx includono "open" per file eseguibili e file di documento e "stampa" per i file di documento per i quali è stato registrato un gestore di stampa. Altre applicazioni potrebbero aver aggiunto verbi shell tramite il Registro di sistema, ad esempio "play" per .avi e .wav file. Per specificare un oggetto spazio dei nomi shell, passare il nome completo dell'analisi e impostare il flag di SEE_MASK_INVOKEIDLIST nel parametro fMask.

Nota: Se il flag SEE_MASK_INVOKEIDLIST è impostato, è possibile usare rispettivamente lpFile o lpIDList per identificare l'elemento in base al percorso del file system o al relativo PIDL. È necessario impostare uno dei due valori,lpFile o lpIDList.
Nota: Se il percorso non è incluso con il nome, si presuppone che venga usata la directory corrente.

lpParameters

Tipo: LPCTSTR

Opzionale. Indirizzo di una stringa con terminazione Null che contiene i parametri dell'applicazione. I parametri devono essere separati da spazi. Se il membro lpFile specifica un file di documento, lpParameters deve essere NULL.

lpDirectory

Tipo: LPCTSTR

Opzionale. Indirizzo di una stringa con terminazione Null che specifica il nome della directory di lavoro. Se questo membro è NULL, la directory corrente viene usata come directory di lavoro.

nShow

Tipo: int

Obbligatorio. Flag che specificano la modalità di visualizzazione di un'applicazione quando viene aperta; uno dei valori di SW_ elencati per la funzione ShellExecute . Se lpFile specifica un file di documento, il flag viene semplicemente passato all'applicazione associata. Spetta all'applicazione decidere come gestirla.

hInstApp

Tipo: HINSTANCE

[out] Se SEE_MASK_NOCLOSEPROCESS è impostato e la chiamata ShellExecuteEx ha esito positivo, imposta questo membro su un valore maggiore di 32. Se la funzione ha esito negativo, viene impostata su un valore di errore SE_ERR_XXX che indica la causa dell'errore. Anche se hInstApp è dichiarato come HINSTANCE per la compatibilità con le applicazioni Windows a 16 bit, non è una vera HINSTANCE. Può essere eseguito il cast solo a un int e rispetto a 32 o ai codici di errore seguenti SE_ERR_XXX.


Codice errore Ragione
SE_ERR_FNF (2) File non trovato.
SE_ERR_PNF (3) Percorso non trovato.
SE_ERR_ACCESSDENIED (5) Accesso negato.
SE_ERR_OOM (8) Memoria insufficiente.
SE_ERR_DLLNOTFOUND (32) Libreria a collegamento dinamico non trovata.
SE_ERR_SHARE (26) Impossibile condividere un file aperto.
SE_ERR_ASSOCINCOMPLETE (27) Informazioni sull'associazione di file non completate.
SE_ERR_DDETIMEOUT (28) Timeout dell'operazione DDE.
SE_ERR_DDEFAIL (29) Operazione DDE non riuscita.
SE_ERR_DDEBUSY (30) L'operazione DDE è occupata.
SE_ERR_NOASSOC (31) Associazione file non disponibile.

lpIDList

Tipo: LPVOID

Indirizzo di una struttura ITEMIDLIST (PCIDLIST_ABSOLUTE) assoluta per contenere un elenco di identificatori di elemento che identifica in modo univoco il file da eseguire. Questo membro viene ignorato se il membro non include SEE_MASK_IDLIST o SEE_MASK_INVOKEIDLIST.

lpClass

Tipo: LPCTSTR

Indirizzo di una stringa con terminazione Null che specifica uno dei valori seguenti:

  • A ProgId. Ad esempio, "Paint.Picture".
  • Schema del protocollo URI. Ad esempio, "http".
  • Estensione di file. Ad esempio, ".txt".
  • Percorso del Registro di sistema in HKEY_CLASSES_ROOT che denomina una sottochiave che contiene uno o più verbi shell. Questa chiave avrà una sottochiave conforme allo schema del Registro di sistema dei verbi shell, ad esempio shell\nome verbo.

Questo membro viene ignorato se fMask non include SEE_MASK_CLASSNAME.

hkeyClass

Tipo: HKEY

Handle per la chiave del Registro di sistema per il tipo di file. I diritti di accesso per questa chiave del Registro di sistema devono essere impostati su KEY_READ. Questo membro viene ignorato se fMask non include SEE_MASK_CLASSKEY.

dwHotKey

Tipo: DWORD

Scelta rapida da tastiera da associare all'applicazione. La parola con ordine basso è il codice della chiave virtuale e la parola di ordine elevato è un flag di modificatore (HOTKEYF_). Per un elenco dei flag di modificatore, vedere la descrizione del messaggio di WM_SETHOTKEY. Questo membro viene ignorato se fMask non include SEE_MASK_HOTKEY.

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

Tipo: HANDLE

Handle per l'icona per il tipo di file. Questo membro viene ignorato se fMask non include SEE_MASK_ICON. Questo valore viene usato solo in Windows XP e versioni precedenti. Viene ignorato a partire da Windows Vista.

DUMMYUNIONNAME.hMonitor

Tipo: HANDLE

Handle per il monitor su cui deve essere visualizzato il documento. Questo membro viene ignorato se fMask non include SEE_MASK_HMONITOR.

hProcess

Tipo: HANDLE

Handle per l'applicazione appena avviata. Questo membro viene impostato in caso di restituzione ed è sempre null a meno che fMask sia impostato su SEE_MASK_NOCLOSEPROCESS. Anche se fMask è impostato su SEE_MASK_NOCLOSEPROCESS, hProcess verrà NULL se non è stato avviato alcun processo. Ad esempio, se un documento da avviare è un URL e un'istanza di Internet Explorer è già in esecuzione, verrà visualizzato il documento. Non viene avviato alcun nuovo processo e hProcess verrà NULL.

Nota:shellExecuteEx non restituisce sempre un hProcess, anche se viene avviato un processo come risultato della chiamata. Ad esempio, un hProcess non restituisce quando si usa SEE_MASK_INVOKEIDLIST per richiamare IContextMenu.

Osservazioni

Il flag SEE_MASK_NOASYNC deve essere specificato se il thread che chiama ShellExecuteEx non dispone di un ciclo di messaggi o se il thread o il processo terminerà subito dopo che ShellExecuteEx restituisce. In tali condizioni, il thread chiamante non sarà disponibile per completare la conversazione DDE, quindi è importante che ShellExecuteEx completare la conversazione prima di restituire il controllo all'applicazione chiamante. Il mancato completamento della conversazione può comportare un avvio non riuscito del documento.

Se il thread chiamante ha un ciclo di messaggi e sarà presente per qualche tempo dopo la chiamata a ShellExecuteEx restituisce, il flag SEE_MASK_NOASYNC è facoltativo. Se il flag viene omesso, il message pump del thread chiamante verrà usato per completare la conversazione DDE. L'applicazione chiamante riprende il controllo prima, poiché la conversazione DDE può essere completata in background.

Per includere virgolette doppie in lpParameters, racchiudere ogni segno in una coppia di virgolette, come nell'esempio seguente.

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

In questo caso, l'applicazione riceve tre parametri: Un, esempio:e "testo tra virgolette".

Nota

L'intestazione shellapi.h definisce SHELLEXECUTEINFO come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito Valore
client minimo supportato Windows XP [solo app desktop]
server minimo supportato Windows 2000 Server [solo app desktop]
intestazione shellapi.h