Funzione ShellExecuteW (shellapi.h)

Articolo
08/26/2023

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 una stringa con terminazione Null, definita 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:

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 una cartella specificata da lpFile.

trovare

Avvia una ricerca che inizia nella directory specificata da lpDirectory.

apre

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

print

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 dell'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.

NULL

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 una stringa con terminazione Null che specifica il file o l'oggetto in cui eseguire il verbo specificato. Per specificare un oggetto spazio dei nomi shell, passare il nome di analisi completo. 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 per il parametro lpDirectory viene usato un percorso relativo non viene usato un percorso relativo per lpFile.

[in, optional] lpParameters

Tipo: LPCTSTR

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

[in, optional] lpDirectory

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null che specifica la directory predefinita (di lavoro) per l'azione. Se questo valore è NULL, viene utilizzata la directory di lavoro corrente. Se viene fornito 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 è tuttavia 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	Il percorso specificato non è stato trovato.
ERROR_BAD_FORMAT	Il file di .exe non è valido (non Win32 .exe o errore nell'immagine di .exe).
SE_ERR_ACCESSDENIED	Il sistema operativo ha negato l'accesso al file specificato.
SE_ERR_ASSOCINCOMPLETE	L'associazione di nomi file è incompleta 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	La DLL specificata non è stata trovata.
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	Il percorso specificato non è stato trovato.
SE_ERR_SHARE	Si è verificata una violazione di condivisione.

Chiamare GetLastError per informazioni sugli errori estese.

Commenti

Poiché ShellExecute può delegare l'esecuzione alle estensioni shell (origini dati, gestori di menu di scelta rapida, implementazioni verbhe) attivate tramite Component Object Model (COM), COM deve essere inizializzato prima di chiamare ShellExecute . Alcune estensioni shell richiedono il tipo di apartment a thread singolo (STA) COM. 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 richiederebbero l'inizializzazione di COM. Tuttavia, è consigliabile inizializzare sempre 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);

oppure

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à Find 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 "explore", la funzione tenta di aprire o esplorare la cartella.

Per ottenere informazioni sull'applicazione avviata come risultato della chiamata a ShellExecute, usare ShellExecuteEx.

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

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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shellapi.h
Libreria	Shell32.lib
DLL	Shell32.dll (versione 3.51 o successiva)