Funzione ShellExecuteA (shellapi.h)

Articolo
08/26/2023

Esegue un'operazione in un file specificato.

Sintassi

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

Parametri

[in, optional] hwnd

Tipo: HWND

Handle alla finestra padre usata 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 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 i 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 a partire dalla 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 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.

NULL

Il verbo predefinito viene usato, se disponibile. In caso contrario, viene usato il verbo "aperto". 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 "stampa". Se per il parametro lpDirectory viene usato un percorso relativo per lpDirectory, non usare 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 che deve essere richiamato. 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 (funzionante) per l'azione. Se questo valore è NULL, viene usata 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 quando viene aperta. Se lpFile specifica un file di documento, il flag viene semplicemente passato all'applicazione associata. L'applicazione deve decidere come gestirla. Può essere uno 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 il cast come HINSTANCE per la compatibilità con le versioni precedenti con applicazioni Windows a 16 bit. Non è tuttavia una vera HINSTANCE. Può essere eseguito il cast solo in un INT_PTR e rispetto a 32 o ai codici di errore seguenti.

Codice restituito	Descrizione
0	Il sistema operativo non è in memoria o risorse.
ERROR_FILE_NOT_FOUND	Il file specificato non è stato trovato.
ERROR_PATH_NOT_FOUND	Il percorso specificato non è stato trovato.
ERROR_BAD_FORMAT	Il file .exe non è valido (.exe non Win32 o errore nell'immagine .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	Impossibile eseguire la transazione DDE.
SE_ERR_DDETIMEOUT	Impossibile completare la transazione DDE perché il timeout della richiesta.
SE_ERR_DLLNOTFOUND	La DLL specificata non è stata trovata.
SE_ERR_FNF	Il file specificato non è stato trovato.
SE_ERR_NOASSOC	Non esiste un'applicazione associata all'estensione del nome file specificata. Questo errore verrà restituito anche se si tenta di stampare un file che 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 della condivisione.

Chiamare GetLastError per informazioni sull'errore estese.

Commenti

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 che ShellExecute venga chiamato. Alcune estensioni shell richiedono il tipo di appartamento 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)