共用方式為

SHELLEXECUTEINFOA 結構 （shellapi.h）

  • 發行項

包含 ShellExecuteExecuteEx所使用的資訊。

語法

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;

成員

cbSize

類型：DWORD

必填。 這個結構的大小，以位元組為單位。

fMask

類型：ULONG

下列一或多個值的組合，表示其他結構成員的內容和有效性：

SEE_MASK_DEFAULT （0x00000000） 使用預設值。
SEE_MASK_CLASSNAME（0x00000001） 使用 lpClass 成員所提供的類別名稱。 如果同時設定SEE_MASK_CLASSKEY和SEE_MASK_CLASSNAME，則會使用類別索引鍵。
SEE_MASK_CLASSKEY（0x00000003） 使用由 hkeyClass 成員所提供的類別索引鍵。 如果同時設定SEE_MASK_CLASSKEY和SEE_MASK_CLASSNAME，則會使用類別索引鍵。
SEE_MASK_IDLIST （0x00000004） 使用 lpIDList 成員所提供的專案標識碼清單。 lpIDList 成員必須指向 ITEMIDLIST 結構。
SEE_MASK_INVOKEIDLIST （0x0000000C） 使用所選取專案 快捷選單處理程式的 IContextMenu 介面。 使用 lpFile，依其文件系統路徑來識別專案，或 lpIDList 依其 PIDL 識別專案。 此旗標可讓應用程式使用 ShellExecuteEx 從快捷方式功能表延伸模組叫用動詞，而不是登錄中列出的靜態動詞。
附注： SEE_MASK_INVOKEIDLIST 覆寫並表示SEE_MASK_IDLIST。
SEE_MASK_ICON （0x00000010） 使用 hIcon 成員所提供的圖示。 這個旗標無法與SEE_MASK_HMONITOR結合。
注意： 此旗標僅適用於 Windows XP 和更早版本。 Windows Vista 會忽略它。
SEE_MASK_HOTKEY （0x00000020） 使用 dwHotKey 成員所提供的鍵盤快捷方式。
SEE_MASK_NOCLOSEPROCESS （0x00000040） 用來指出 hProcess 成員收到進程句柄。 此句柄通常用來讓應用程式找出使用ShellExecuteEx 建立的進程何時終止。 在某些情況下，例如透過 DDE 交談滿足執行時，將不會傳回任何句柄。 呼叫端應用程式負責在不再需要句柄時關閉句柄。
SEE_MASK_CONNECTNETDRV （0x00000080） 驗證共用並連線到驅動器號。 這可重新連線已中斷連線的網路驅動器機。 lpFile 成員是網路上檔案的 UNC 路徑。
SEE_MASK_NOASYNC （0x00000100） 等候執行作業完成再傳回。 使用 ShellExecute 表單的呼叫端應該使用此旗標，例如 DDE，並建立可能在背景線程上執行的進程。 （注意：如果呼叫端的線程模型不是 Apartment，則 ShellExecuteEx 預設會在背景線程上執行。從已在背景線程上執行的進程呼叫 ShellExecuteEx，應該一律傳遞此旗標。 此外，呼叫ShellExecuteEx 之後立即結束的應用程式應該指定此旗標。

如果在背景線程上執行執行執行作業，且呼叫端未指定SEE_MASK_ASYNCOK旗標，則呼叫線程會等到新進程開始后再傳回。 這通常表示已呼叫 CreateProcess、DDE 通訊已完成，或自定義執行委派已 通知殼層ExecuteEx 完成。 如果指定了SEE_MASK_WAITFORINPUTIDLE旗標，ShellExecuteEx 會呼叫 WaitForInputIdle，並等候新進程在傳回之前閑置，且最大逾時為 1 分鐘。

如需有關何時需要此旗標的進一步討論，請參閱一節。
SEE_MASK_FLAG_DDEWAIT （0x00000100） 與SEE_MASK_NOASYNC相同，建議使用該選項。
SEE_MASK_DOENVSUBST （0x00000200） 展開 lpDirectory 或 lpFile 成員所指定字串中指定的任何環境變數。
SEE_MASK_FLAG_NO_UI（0x00000400） 請勿顯示使用者介面 （UI） 錯誤對話框，這些對話框通常會在沒有此選項的情況下顯示。 安全性提示會豁免，但仍會顯示。
SEE_MASK_UNICODE（0x00004000） 使用此旗標來指出 Unicode 應用程式。
SEE_MASK_NO_CONSOLE （0x00008000） 使用 來繼承新進程的父主控台，而不是建立新的控制台。 這與搭配 createProcess使用 CREATE_NEW_CONSOLE 旗標與 相反。
SEE_MASK_ASYNCOK （0x00100000） 您可以在背景線程上執行執行，而且呼叫應該立即傳回，而不需要等待背景線程完成。 請注意，在某些情況下，ShellExecuteEx 會忽略此旗標，並等候程式在傳回之前完成。
SEE_MASK_NOQUERYCLASSSTORE （0x01000000） 未使用。
SEE_MASK_HMONITOR （0x00200000） 在多監視器系統上指定監視器時，請使用此旗標。 監視器是在 hMonitor 成員中指定。 這個旗標無法與SEE_MASK_ICON結合。
SEE_MASK_NOZONECHECKS （0x00800000） 請勿執行區域檢查。 此旗標允許 ShellExecuteEx 略 過 IAttachmentExecute所放置的區域檢查。
SEE_MASK_WAITFORINPUTIDLE（0x02000000） 建立新進程之後，等候進程在返回之前變成閑置狀態，並逾時一分鐘。 如需詳細資訊，請參閱 WaitForInputIdle。
SEE_MASK_FLAG_LOG_USAGE （0x04000000） 指出使用者起始的啟動，可追蹤常用程式和其他行為。
SEE_MASK_FLAG_HINST_IS_SITE （0x08000000） hInstApp 成員可用來指定實作 IServiceProvider之物件的 IUnknown。 此物件將做為月臺指標。 月臺指標可用來提供服務給 ShellExecute 函式、處理程式系結進程，以及叫用動詞處理程式。

ICreatingProcess 可讓呼叫者改變所建立程式的一些參數。

Windows 8 和更新版本中支援此旗標。

指定此選項時，呼叫會在呼叫線程上同步執行。

hwnd

類型：HWND

自選。 擁有者視窗的句柄，用來顯示及放置系統在執行此函式時可能會產生的任何 UI。

lpVerb

類型：LPCTSTR

字串，稱為 動詞，指定要執行的動作。 可用的動詞集取決於特定檔案或資料夾。 一般而言，物件快捷功能表提供的動作是可用的動詞命令。 此參數可以 NULL，在此情況下會使用預設動詞。 如果沒有，則會使用 「open」 動詞。 如果兩個動詞都無法使用，則系統會使用登錄中所列的第一個動詞。 除非有理由將動作限制為特定動詞，否則請傳遞NULL以使用計算的預設值。 在某些情況下，這是必要的，例如，指定SEE_MASK_FLAG_NO_UI，而意圖是在未安裝任何應用程式時產生「開啟」UI。

通常使用下列動詞：

  • 編輯：啟動編輯器，並開啟檔進行編輯。 如果 lpFile 不是文件檔，函式將會失敗。
  • 探索：探索 lpFile所指定的資料夾。
  • 尋找：起始從指定目錄開始的搜尋。
  • 開啟：開啟由 lpFile 參數指定的檔案。 檔案可以是可執行檔、文件檔或資料夾。
  • opeanas：啟動選擇器 UI，允許使用者選取應用程式，以開啟由 lpFile 參數指定的檔案。
  • 列印：列印由 lpFile所指定的檔案檔案。 如果 lpFile 不是文件檔，函式將會失敗。
  • 屬性：顯示檔案或資料夾的屬性。
  • runas：以系統管理員身分啟動應用程式。 用戶帳戶控制 （UAC） 會提示使用者同意提高許可權執行應用程式，或輸入用來執行應用程式的系統管理員帳戶認證。

lpFile

類型：LPCTSTR

null 終止字串的位址，指定shellExecuteEx 之檔案或物件的名稱，將會執行 lpVerb 參數所指定的動作。 ShellExecuteExecuteEx 函式所支援的系統登錄動詞命令包括可執行檔和文件檔的「開啟」，以及已登錄列印處理程式的檔檔的「列印」。 其他應用程式可能已透過系統登錄新增Shell動詞命令，例如 .avi 和.wav檔案的「播放」。 若要指定Shell命名空間物件，請傳遞完整剖析名稱，並在 fMask 參數中設定 SEE_MASK_INVOKEIDLIST 旗標。

注意： 如果已設定 SEE_MASK_INVOKEIDLIST 旗標，您可以使用 lpFile 或 lpIDList，依其文件系統路徑或 PIDL 分別識別專案。 必須設定這兩個值之一，lpFile 或 lpIDList。
注意： 如果路徑未隨附於名稱中，則會假設目前的目錄。

lpParameters

類型：LPCTSTR

自選。 包含應用程式參數之 Null 終止字串的位址。 參數必須以空格分隔。 如果 lpFile 成員指定檔案檔，lpParameters 應該 NULL。

lpDirectory

類型：LPCTSTR

自選。 指定工作目錄名稱之 Null 終止字串的位址。 如果這個成員 NULL，則目前的目錄會當做工作目錄使用。

nShow

類型：int

必填。 旗標，指定應用程式在開啟時要如何顯示;ShellExecute 函式所列的其中一個SW_值。 如果 lpFile 指定檔檔，則旗標只會傳遞至相關聯的應用程式。 由應用程式決定如何處理。

hInstApp

類型：HINSTANCE

[out]如果已設定SEE_MASK_NOCLOSEPROCESS，且 ShellExecuteEx 呼叫成功，則會將此成員設定為大於 32 的值。 如果函式失敗，它會設定為SE_ERR_XXX錯誤值，指出失敗的原因。 雖然 hInstApp 宣告為 HINSTANCE 以與 16 位 Windows 應用程式相容，但這不是真正的 HINSTANCE。 它只能轉換成 int，而且相較於下列 32 或下列SE_ERR_XXX錯誤碼。


錯誤碼 原因
SE_ERR_FNF （2） 找不到檔案。
SE_ERR_PNF （3） 找不到路徑。
SE_ERR_ACCESSDENIED （5） 拒絕存取。
SE_ERR_OOM （8） 記憶體不足。
SE_ERR_DLLNOTFOUND （32） 找不到動態連結庫。
SE_ERR_SHARE （26） 無法共享開啟的檔案。
SE_ERR_ASSOCINCOMPLETE （27） 檔案關聯資訊未完成。
SE_ERR_DDETIMEOUT （28） DDE 作業逾時。
SE_ERR_DDEFAIL （29） DDE 作業失敗。
SE_ERR_DDEBUSY （30） DDE 作業忙碌中。
SE_ERR_NOASSOC （31） 檔案關聯無法使用。

lpIDList

類型：LPVOID

絕對 ITEMIDLIST 結構 （PCIDLIST_ABSOLUTE） 的位址，包含可唯一識別要執行之檔案的專案識別符清單。 如果 fMask 成員不包含 SEE_MASK_IDLIST 或 SEE_MASK_INVOKEIDLIST，則會忽略此成員。

lpClass

類型：LPCTSTR

Null 終止字串的位址，指定下列其中一項：

  • ProgId。 例如，“Paint.Picture”。
  • URI 通訊協定配置。 例如，“HTTP”。
  • 擴展名。 例如， “.txt”
  • HKEY_CLASSES_ROOT下的登錄路徑，會命名包含一或多個Shell動詞的子機碼。 此機碼會有符合殼層動詞登錄架構的子機碼，例如 殼層\動詞名稱。

如果 fMask 不包含 SEE_MASK_CLASSNAME，則會忽略此成員。

hkeyClass

類型：HKEY

檔類型之登錄機碼的句柄。 此登錄機碼的訪問許可權應設定為 KEY_READ。 如果 fMask 不包含 SEE_MASK_CLASSKEY，則會忽略此成員。

dwHotKey

類型：DWORD

與應用程式建立關聯的鍵盤快捷方式。 低序字是虛擬索引鍵程序代碼，而高階字則是修飾詞旗標（HOTKEYF_）。 如需修飾詞旗標的清單，請參閱 WM_SETHOTKEY 訊息的描述。 如果 fMask 不包含 SEE_MASK_HOTKEY，則會忽略此成員。

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

類型：HANDLE

檔類型圖示的句柄。 如果 fMask 不包含 SEE_MASK_ICON，則會忽略此成員。 此值僅適用於 Windows XP 和更早版本。 Windows Vista 會忽略它。

DUMMYUNIONNAME.hMonitor

類型：HANDLE

要顯示檔之監視器的句柄。 如果 fMask 不包含 SEE_MASK_HMONITOR，則會忽略此成員。

hProcess

類型：HANDLE

新啟動應用程式的句柄。 除非 fMask 設為 SEE_MASK_NOCLOSEPROCESS，否則此成員會在傳回時設定為 ，且一律 NULL。 即使 fMask 設定為 SEE_MASK_NOCLOSEPROCESS，如果未啟動任何進程，hProcess 將會 NULL。 例如，如果要啟動的檔是URL，且Internet Explorer的實例已經執行，則會顯示檔。 不會啟動任何新進程，hProcess 將會 NULL。

注意：ShellExecuteEx 不一定會傳回 hProcess，即使呼叫結果啟動進程也一樣。 例如，當您使用 SEE_MASK_INVOKEIDLIST 叫用 IContextMenu時，hProcess 不會傳回 。

言論

如果呼叫 ShellExecuteEx 的線程沒有訊息迴圈，或者線程或進程在殼層ExecuteExecuteEx 傳回 之後不久就會終止，則必須指定 SEE_MASK_NOASYNC 旗標。 在這種情況下，呼叫線程將無法完成 DDE 交談，因此請務必先 ShellExecuteExecuteEx 完成交談，再將控制權傳回給呼叫端應用程式。 無法完成交談可能會導致檔啟動失敗。

如果呼叫線程有訊息迴圈，而且會在呼叫殼層ExecuteExecuteEx 傳回 之後存在一段時間，則 SEE_MASK_NOASYNC 旗標是選擇性的。 如果省略旗標，則會使用呼叫線程的訊息幫浦來完成 DDE 交談。 呼叫端應用程式會更快重新取得控制權，因為 DDE 交談可以在背景中完成。

若要在 lpParameters中包含雙引號，請將每個標記括在一對引號中，如下列範例所示。

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

在此情況下，應用程式會收到三個參數：、範例：，以及 的「引號文字」。

注意

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

要求

要求 價值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
支援的最低伺服器 Windows 2000 Server [僅限傳統型應用程式]
標頭 shellapi.h