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 |
| SEE_MASK_CLASSKEY (0x00000003) | Usare la chiave di classe specificata dal membro hkeyClass |
| SEE_MASK_IDLIST (0x00000004) | Usare l'elenco di identificatori di elemento fornito dal membro lpIDList |
| SEE_MASK_INVOKEIDLIST (0x0000000C) | Usare l'interfaccia IContextMenu
Nota: SEE_MASK_INVOKEIDLIST sostituzioni e implica SEE_MASK_IDLIST.
|
| SEE_MASK_ICON (0x00000010) | Usare l'icona specificata dal membro
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 |
| SEE_MASK_NOCLOSEPROCESS (0x00000040) | Usare per indicare che il membro hProcess |
| 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 |
| 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 è 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
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
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
hInstApp
Tipo: HINSTANCE
[out] Se SEE_MASK_NOCLOSEPROCESS è impostato e la chiamata ShellExecuteEx
| 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
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.
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 |