Struttura SHELLEXECUTEINFOA (shellapi.h)
Contiene informazioni utilizzate 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;
Members
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 specificato 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 dal 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 del processo. Questo handle viene in genere usato per consentire a un'applicazione di scoprire quando termina un processo creato con ShellExecuteEx . 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 causare 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 escono immediatamente dopo la chiamata a 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 fino all'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 ricevuto una notifica a ShellExecuteEx che è stata eseguita. 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 questo flag è necessario, 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 invece di 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 usato. |
| SEE_MASK_HMONITOR (0x00200000) | Usare questo flag quando si specifica un monitoraggio nei sistemi multi-monitoraggio. 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 a ShellExecuteEx di ignorare il controllo della zona inserito da 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 IUnknown di un oggetto che implementa IServiceProvider. Questo oggetto verrà usato 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 specificare ICreatingProcess per consentire al chiamante di modificare alcuni parametri del processo creato. Questo flag è supportato in Windows 8 e versioni successive. Quando questa opzione viene specificata, la chiamata viene eseguita in modo sincrono sul thread chiamante. |
hwnd
Tipo: HWND
facoltativo. 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, denominata 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 il valore predefinito calcolato. Ciò è necessario in alcuni casi, ad esempio quando si specifica SEE_MASK_FLAG_NO_UI e l'intenzione è di 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.
- esplora: esplora la cartella specificata da lpFile.
- find: avvia una ricerca a partire dalla directory specificata.
- open: apre il file specificato dal parametro lpFile . Il file può essere un file eseguibile, un file documento o una cartella.
- stampa: stampa il file del 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 di 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 di analisi completo e impostare il flag di SEE_MASK_INVOKEIDLIST nel parametro fMask .
lpParameters
Tipo: LPCTSTR
facoltativo. Indirizzo di una stringa con terminazione null contenente 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
facoltativo. 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 SW_ elencati per la funzione ShellExecute . Se lpFile specifica un file di documento, il flag viene semplicemente passato all'applicazione associata. L'applicazione deve 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, è impostata su un valore di errore SE_ERR_XXX che indica la causa dell'errore. Sebbene hInstApp sia dichiarato come HINSTANCE per la compatibilità con 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 di errore | Motivo |
|---|---|
| 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 di collegamento dinamico non trovata. |
| SE_ERR_SHARE (26) | Impossibile condividere un file aperto. |
| SE_ERR_ASSOCINCOMPLETE (27) | Le informazioni sull'associazione di file non sono complete. |
| 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 di file non disponibile. |
lpIDList
Tipo: LPVOID
Indirizzo di una struttura ITEMIDLIST assoluta (PCIDLIST_ABSOLUTE) per contenere un elenco di identificatori di elemento che identifica in modo univoco il file da eseguire. Questo membro viene ignorato se il membro fMask non include SEE_MASK_IDLIST o SEE_MASK_INVOKEIDLIST.
lpClass
Tipo: LPCTSTR
Indirizzo di una stringa con terminazione null che specifica uno dei seguenti elementi:
- 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 assegna un nome a una sottochiave contenente uno o più verbi shell. Questa chiave avrà una sottochiave conforme allo schema del Registro di sistema della shell, ad esempioil nome verbodella shell\.
Questo membro viene ignorato se fMask non include SEE_MASK_CLASSNAME.
hkeyClass
Tipo: HKEY
Handle della 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 a basso ordine è il codice chiave virtuale e la parola ad ordine elevato è un flag di modifica (HOTKEYF_). Per un elenco di flag di modifica, vedere la descrizione del messaggio WM_SETHOTKEY . Questo membro viene ignorato se fMask non include SEE_MASK_HOTKEY.
DUMMYUNIONNAME
DUMMYUNIONNAME.hIcon
Tipo: HANDLE
Handle all'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 come di Windows Vista.
DUMMYUNIONNAME.hMonitor
Tipo: HANDLE
Handle per il monitoraggio in base al quale 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 sul ritorno ed è sempre NULL a meno che fMask non sia impostato su SEE_MASK_NOCLOSEPROCESS. Anche se fMask è impostato su SEE_MASK_NOCLOSEPROCESS, hProcess sarà 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 sarà NULL.
Commenti
Il flag di SEE_MASK_NOASYNC deve essere specificato se il thread che chiama ShellExecuteEx non ha un ciclo di messaggi o se il thread o il processo verrà terminato subito dopo il ritorno di ShellExecuteEx . In queste condizioni, il thread chiamante non sarà disponibile per completare la conversazione DDE, quindi è importante che ShellExecuteEx completa la conversazione prima di restituire il controllo all'applicazione chiamante. Non è possibile completare la conversazione con 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 , il flag di SEE_MASK_NOASYNC è facoltativo. Se il flag viene omesso, la pompa del messaggio del thread chiamante verrà usata per completare la conversazione DDE. L'applicazione chiamante recupera 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: unesempio: e "testo 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Intestazione | shellapi.h |
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per