ShellExecuteA 函式 (shellapi.h)

發行項
03/05/2024

在指定的檔案上執行作業。

語法

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

參數

[in, optional] hwnd

類型： HWND

父視窗的句柄，用於顯示UI或錯誤訊息。如果作業未與視窗相關聯，這個值可以是 NULL 。

[in, optional] lpOperation

類型： LPCTSTR

以 Null 終止字串的指標，在此案例中稱為動詞命令，指定要執行的動作。可用的動詞集取決於特定檔案或資料夾。一般而言，可從物件的快捷方式功能表取得的動作是可用的動詞命令。通常會使用下列動詞：

編輯

啟動編輯器，並開啟檔以進行編輯。如果 lpFile 不是檔檔，函式將會失敗。

探索

探索 lpFile 所指定的資料夾。

尋找

從 lpDirectory 所指定的目錄中起始搜尋。

開啟

開啟 lpFile 參數所指定的專案。專案可以是檔案或資料夾。

print

列印 lpFile 指定的檔案。如果 lpFile 不是文件檔，則函式會失敗。

runas

以系統管理員身分啟動應用程式。用戶帳戶控制 (UAC) 會提示使用者同意提高許可權執行應用程式，或輸入用來執行應用程式的系統管理員帳戶認證。

NULL

如果有的話，會使用默認動詞。如果沒有，則會使用「open」動詞命令。如果兩個動詞都無法使用，系統會使用登錄中列出的第一個動詞。

[in] lpFile

類型： LPCTSTR

Null 終止字串的指標，指定要在其中執行指定動詞命令的檔案或物件。若要指定Shell命名空間物件，請傳遞完整剖析名稱。請注意，並非所有物件都支援所有動詞。例如，並非所有文件類型都支援「print」動詞。如果 lpDirectory 參數使用相對路徑，則不會使用 lpFile 的相對路徑。

[in, optional] lpParameters

類型： LPCTSTR

如果 lpFile 指定可執行檔，此參數是 Null 終止字串的指標，指定要傳遞至應用程式的參數。此字串的格式取決於要叫用的動詞。如果 lpFile 指定文件檔， lpParameters 應為 NULL。

[in, optional] lpDirectory

類型： LPCTSTR

Null 終止字串的指標，指定動作的預設 (工作) 目錄。如果此值為 NULL，則會使用目前的工作目錄。如果在 lpFile 提供相對路徑，請勿使用 lpDirectory 的相對路徑。

[in] nShowCmd

類型： INT

旗標，指定應用程式在開啟時要如何顯示。如果 lpFile 指定檔檔，則旗標只會傳遞至相關聯的應用程式。應用程式必須決定如何處理它。它可以是可在 ShowWindow 函式的 nCmdShow 參數中指定的任何值。

傳回值

類型： HINSTANCE

如果函式成功，它會傳回大於 32 的值。如果函式失敗，它會傳回錯誤值，指出失敗的原因。傳回值會轉換成 HINSTANCE，以便與 16 位 Windows 應用程式回溯相容性。不過，這不是真正的 HINSTANCE。它只能轉換成 INT_PTR ，相較於下列 32 或下列錯誤碼。

傳回碼	描述
0	操作系統記憶體不足或資源。
ERROR_FILE_NOT_FOUND	找不到指定的檔案。
ERROR_PATH_NOT_FOUND	找不到指定的路徑。
ERROR_BAD_FORMAT	.exe 檔案無效， (非 Win32 .exe 或 .exe 映射) 發生錯誤。
SE_ERR_ACCESSDENIED	操作系統拒絕存取指定的檔案。
SE_ERR_ASSOCINCOMPLETE	檔名關聯不完整或無效。
SE_ERR_DDEBUSY	無法完成 DDE 交易，因為正在處理其他 DDE 交易。
SE_ERR_DDEFAIL	DDE 交易失敗。
SE_ERR_DDETIMEOUT	無法完成 DDE 交易，因為要求逾時。
SE_ERR_DLLNOTFOUND	找不到指定的 DLL。
SE_ERR_FNF	找不到指定的檔案。
SE_ERR_NOASSOC	沒有與指定擴展名相關聯的應用程式。如果您嘗試列印無法列印的檔案，也會傳回此錯誤。
SE_ERR_OOM	記憶體不足，無法完成作業。
SE_ERR_PNF	找不到指定的路徑。
SE_ERR_SHARE	發生共享違規。

呼叫 GetLastError 以取得擴充的錯誤資訊。

備註

由於 ShellExecute 可以將執行委派給 Shell 延伸模組， (數據源、操作功能表處理程式、動詞實作) 使用元件物件模型 (COM) 啟用，因此呼叫 ShellExecute 之前，應該先初始化 COM。某些 Shell 擴充功能需要 COM 單個線程 Apartment (STA) 類型。在此情況下，應該初始化 COM，如下所示：

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

殼層 Execute 確實不會使用下列其中一種 Shell 擴充功能，而且這些實例完全不需要初始化 COM。不過，使用這個函式之前 ，請務必先 初始化 COM。

這個方法可讓您在資料夾的快捷方式功能表中執行任何命令，或儲存在登錄中。

若要開啟資料夾，請使用下列其中一個呼叫：

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

或

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

若要探索資料夾，請使用下列呼叫：

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

若要啟動目錄的Shell尋找公用程式，請使用下列呼叫。

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

如果 lpOperation 為 NULL，函式會開啟 lpFile 指定的檔案。如果 lpOperation 為 “open” 或 “explore”，則函式會嘗試開啟或探索資料夾。

若要取得呼叫 ShellExecute而啟動之應用程式的相關信息，請使用 ShellExecuteEx。

注意 [ 資料夾選項] 中個別行程設定中的 [啟動資料夾] 視窗 會影響 ShellExecute。如果停用該選項 (預設設定 ) ，ShellExecute 會使用開啟的 [總管] 視窗，而不是啟動新的選項。如果沒有開啟 [總管] 視窗， ShellExecute 會啟動新的視窗。

注意

shellapi.h 標頭會將ShellExecute定義為別名，根據UNICODE預處理器常數的定義，自動選取此函式的ANSI或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	shellapi.h
程式庫	Shell32.lib
Dll	Shell32.dll (3.51 版或更新版本)