SHELLEXECUTEINFOA 結構 (shellapi.h)

發行項
04/05/2024

包含 ShellExecuteEx 所使用的資訊。

語法

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 通訊已完成，或自定義執行委派已通知 ShellExecuteEx 已完成。如果指定了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 所指定的資料夾。
find：起始從指定目錄開始的搜尋。
open：開啟 lpFile 參數指定的檔案。檔案可以是可執行檔、文件檔或資料夾。
print：列印 lpFile 所指定的檔案檔案。如果 lpFile 不是檔檔，函式將會失敗。
properties：顯示檔案或資料夾的屬性。
runas：以系統管理員身分啟動應用程式。用戶帳戶控制 (UAC) 會提示使用者同意提高許可權執行應用程式，或輸入用來執行應用程式的系統管理員帳戶認證。

lpFile

類型： LPCTSTR

Null 終止字串的位址，指定 ShellExecuteEx 將執行 lpVerb 參數所指定之動作的檔案或物件名稱。 ShellExecuteExecuteEx 函式所支援的系統登錄動詞包括可執行檔和檔案檔案的 “open”，以及已登錄列印處理程式的檔檔案的 “print”。其他應用程式可能已透過系統登錄新增殼層動詞，例如 .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 宣告為與 16 位 Windows 應用程式的相容性的 HINSTANCE，但它不是真正的 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的線程沒有訊息迴圈，或者線程或進程在ShellExecuteEx傳回之後即將終止，就必須指定SEE_MASK_NOASYNC旗標。在這種情況下，呼叫線程將無法完成 DDE 交談，因此 ShellExecuteEx 必須在將控制權傳回給呼叫應用程式之前先完成交談。無法完成交談可能會導致檔啟動失敗。

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

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

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

在此情況下，應用程式會收到三個參數：An、example：和 “quoted text”。

注意

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

規格需求

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

SHELLEXECUTEINFOA 結構 (shellapi.h)

語法

成員

備註

規格需求

意見反應

意見反應

其他資源