Funzione ShellExecuteW (shellapi.h)

Articolo
11/20/2024

Esegue un'operazione su un file specificato.

Sintassi

HINSTANCE ShellExecuteW(
  [in, optional] HWND    hwnd,
  [in, optional] LPCWSTR lpOperation,
  [in]           LPCWSTR lpFile,
  [in, optional] LPCWSTR lpParameters,
  [in, optional] LPCWSTR lpDirectory,
  [in]           INT     nShowCmd
);

Parametri

[in, optional] hwnd

Tipo: HWND

Handle per la finestra padre utilizzata per visualizzare un'interfaccia utente o messaggi di errore. Questo valore può essere null se l'operazione non è associata a una finestra.

[in, optional] lpOperation

Tipo: LPCTSTR

Puntatore a un nullstringa con terminazione, indicato in questo caso come 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. I verbi seguenti vengono comunemente usati:

redigere

Avvia un editor e apre il documento per la modifica. Se lpFile non è un file di documento, la funzione avrà esito negativo.

esplorare

Esplora una cartella specificata da lpFile.

trovare

Avvia una ricerca che inizia nella directory specificata da lpDirectory.

aperto

Apre l'elemento specificato dal parametro lpFile . L'elemento può essere un file o una cartella.

Stampare

Stampa il file specificato da lpFile. Se lpFile non è un file di documento, la funzione ha esito negativo.

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.

NULLO

Il verbo predefinito viene usato, 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.

[in] lpFile

Tipo: LPCTSTR

Puntatore a un nullstringa con terminazione che specifica il file o l'oggetto in cui eseguire il verbo specificato. Per specificare un oggetto spazio dei nomi shell, passare il nome completo dell'analisi. Si noti che non tutti i verbi sono supportati in tutti gli oggetti. Ad esempio, non tutti i tipi di documento supportano il verbo "print". Se viene usato un percorso relativo per il parametro lpDirectory non usare un percorso relativo per lpFile.

[in, optional] lpParameters

Tipo: LPCTSTR

Se lpFile specifica un file eseguibile, questo parametro è un puntatore a un nullstringa con terminazione che specifica i parametri da passare all'applicazione. Il formato di questa stringa è determinato dal verbo che deve essere richiamato. Se lpFile specifica un file di documento, lpParameters deve essere NULL.

[in, optional] lpDirectory

Tipo: LPCTSTR

Puntatore a un nullstringa con terminazione che specifica la directory predefinita (di lavoro) per l'azione. Se questo valore è NULL, viene utilizzata la directory di lavoro corrente. Se viene specificato un percorso relativo in lpFile, non usare un percorso relativo per lpDirectory.

[in] nShowCmd

Tipo: INT

Flag che specificano la modalità di visualizzazione di un'applicazione all'apertura. Se lpFile specifica un file di documento, il flag viene semplicemente passato all'applicazione associata. Spetta all'applicazione decidere come gestirla. Può essere uno qualsiasi dei valori che è possibile specificare nel parametro nCmdShow per la funzione ShowWindow.

Valore restituito

Tipo: HINSTANCE

Se la funzione ha esito positivo, restituisce un valore maggiore di 32. Se la funzione ha esito negativo, restituisce un valore di errore che indica la causa dell'errore. Il valore restituito viene eseguito come HINSTANCE per garantire la compatibilità con le versioni precedenti con le applicazioni Windows a 16 bit. Non è però una vera HINSTANCE. Può essere eseguito il cast solo a un INT_PTR e rispetto a 32 o ai codici di errore seguenti.

Codice restituito	Descrizione
0	Il sistema operativo non è disponibile nella memoria o nelle risorse.
ERROR_FILE_NOT_FOUND	Impossibile trovare il file specificato.
ERROR_PATH_NOT_FOUND	Impossibile trovare il percorso specificato.
ERROR_BAD_FORMAT	Il file di .exe non è valido (.exe o errore non Win32 nell'immagine .exe).
SE_ERR_ACCESSDENIED	Il sistema operativo ha negato l'accesso al file specificato.
SE_ERR_ASSOCINCOMPLETE	L'associazione del nome file non è completa o non è valida.
SE_ERR_DDEBUSY	Impossibile completare la transazione DDE perché sono state elaborate altre transazioni DDE.
SE_ERR_DDEFAIL	Transazione DDE non riuscita.
SE_ERR_DDETIMEOUT	Impossibile completare la transazione DDE perché è stato effettuato il timeout della richiesta.
SE_ERR_DLLNOTFOUND	Impossibile trovare la DLL specificata.
SE_ERR_FNF	Impossibile trovare il file specificato.
SE_ERR_NOASSOC	Nessuna applicazione associata all'estensione del nome file specificata. Questo errore verrà restituito anche se si tenta di stampare un file non stampabile.
SE_ERR_OOM	Memoria insufficiente per completare l'operazione.
SE_ERR_PNF	Impossibile trovare il percorso specificato.
SE_ERR_SHARE	Si è verificata una violazione di condivisione.

Chiamare getLastError per informazioni estese sull'errore.

Osservazioni

Poiché ShellExecute può delegare l'esecuzione alle estensioni shell (origini dati, gestori di menu di scelta rapida, implementazioni verbo) attivate tramite Component Object Model (COM), COM deve essere inizializzato prima di viene chiamato shellExecute. Alcune estensioni della shell richiedono il tipo APARTMENT a thread singolo COM (STA). In tal caso, com deve essere inizializzato come illustrato di seguito:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Esistono certamente istanze in cui ShellExecute non usa uno di questi tipi di estensione shell e tali istanze non richiedono l'inizializzazione di COM. Tuttavia, è consigliabile sempre inizializzare COM prima di usare questa funzione.

Questo metodo consente di eseguire qualsiasi comando nel menu di scelta rapida di una cartella o archiviato nel Registro di sistema.

Per aprire una cartella, usare una delle chiamate seguenti:

ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Per esplorare una cartella, usare la chiamata seguente:

ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Per avviare l'utilità Trova della shell per una directory, usare la chiamata seguente.

ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);

Se lpOperation è null, la funzione apre il file specificato da lpFile. Se lpOperation è "aperto" o "esplora", la funzione tenta di aprire o esplorare la cartella.

Per ottenere informazioni sull'applicazione avviata in seguito alla chiamata di ShellExecute, usare ShellExecuteEx.

Nota Le finestre della cartella di avvio di in un'impostazione di processo separata in Opzioni cartella influiscono su ShellExecute. Se questa opzione è disabilitata (impostazione predefinita), ShellExecute usa una finestra di Esplora risorse aperta anziché avviarne una nuova. Se non è aperta alcuna finestra di Esplora risorse, ShellExecute ne avvia una nuova.

Nota

L'intestazione shellapi.h definisce ShellExecute 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]
piattaforma di destinazione	Finestre
intestazione	shellapi.h
libreria	Shell32.lib
dll	Shell32.dll (versione 3.51 o successiva)