SHELLEXECUTEINFOA 结构 (shellapi.h)

项目
02/23/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 成员接收进程句柄。此句柄通常用于允许应用程序了解使用 ShellExecuteExecuteEx 创建的进程何时终止。在某些情况下，例如通过 DDE 会话满足执行要求时，不会返回任何句柄。调用应用程序负责在不再需要句柄时将其关闭。
SEE_MASK_CONNECTNETDRV (0x00000080)	验证共享并连接到驱动器号。这样就可以重新连接断开连接的网络驱动器。 lpFile 成员是网络上文件的 UNC 路径。
SEE_MASK_NOASYNC (0x00000100)	等待执行操作完成，然后返回。此标志应由使用可能导致异步激活的 ShellExecute 表单（例如 DDE）的调用方使用，并创建可能在后台线程上运行的进程。 (注意：如果调用方线程模型不是 Apartment，则默认情况下 ShellExecuteExecuteEx 在后台线程上运行。) 从已在后台线程上运行的进程调用 ShellExecuteEx 应始终传递此标志。此外，调用 ShellExecuteEx 后立即退出的应用程序应指定此标志。如果在后台线程上执行执行操作，并且调用方未指定SEE_MASK_ASYNCOK标志，则调用线程将等到新进程启动后再返回。这通常意味着已调用 CreateProcess 、DDE 通信已完成，或者自定义执行委托已通知 ShellExecuteExecuteEx 已完成。如果指定了SEE_MASK_WAITFORINPUTIDLE标志，则 ShellExecuteExecuteEx 调用 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)	使用为新进程继承父级的控制台，而不是让其创建新控制台。这与将 CREATE_NEW_CONSOLE 标志与 CreateProcess 配合使用相反。
SEE_MASK_ASYNCOK (0x00100000)	可以在后台线程上执行执行，调用应立即返回，而无需等待后台线程完成。请注意，在某些情况下， ShellExecuteEx 会忽略此标志，并等待进程完成，然后再返回。
SEE_MASK_NOQUERYCLASSSTORE (0x01000000)	未使用。
SEE_MASK_HMONITOR (0x00200000)	在多监视器系统上指定监视器时使用此标志。监视器在 hMonitor 成员中指定。此标志不能与SEE_MASK_ICON组合使用。
SEE_MASK_NOZONECHECKS (0x00800000)	请勿执行区域检查。此标志允许 ShellExecuteExecuteEx 绕过 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并且目的是生成“Open With”UI（如果未安装任何应用）。

通常使用以下谓词：

编辑：启动编辑器并打开文档进行编辑。如果 lpFile 不是文档文件，则函数将失败。
explore：浏览 lpFile 指定的文件夹。
find：启动从指定目录开始的搜索。
open：打开 由 lpFile 参数指定的文件。该文件可以是可执行文件、文档文件或文件夹。
print：打印 由 lpFile 指定的文档文件。如果 lpFile 不是文档文件，则函数将失败。
properties：显示文件或文件夹的属性。
runas：以管理员身份启动应用程序。用户帐户控制 (UAC) 将提示用户同意运行提升的应用程序，或者输入用于运行应用程序的管理员帐户的凭据。

lpFile

类型： LPCTSTR

以 null 结尾的字符串的地址，指定 ShellExecuteExecuteEx 将对其执行 lpVerb 参数指定操作的文件或对象的名称。 ShellExecuteExecuteEx 函数支持的系统注册表谓词包括可执行文件和文档文件的“open”和“print”（对于已注册打印处理程序的文档文件）。其他应用程序可能已通过系统注册表添加了 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 谓词的子项。此键将具有符合 Shell 谓词注册表架构的子项，例如 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

类型：句柄

文件类型图标的句柄。如果 fMask 不包含 SEE_MASK_ICON，则忽略此成员。此值仅在 Windows XP 及更早版本中使用。从 Windows Vista 开始，它将被忽略。

DUMMYUNIONNAME.hMonitor

类型：句柄

要显示文档的监视器的句柄。如果 fMask 不包含 SEE_MASK_HMONITOR，则忽略此成员。

hProcess

类型：句柄

新启动的应用程序的句柄。此成员在返回时设置，并且始终为 NULL ，除非 fMask 设置为 SEE_MASK_NOCLOSEPROCESS。即使 fMask 设置为 SEE_MASK_NOCLOSEPROCESS，如果没有启动任何进程， hProcess 也将为 NULL 。例如，如果要启动的文档是 URL，并且 Internet Explorer 的实例已在运行，则它将显示该文档。未启动任何新进程， hProcess 将为 NULL。

注意：ShellExecuteExecuteEx 并不总是返回 hProcess，即使进程是作为调用结果启动的。例如，使用 SEE_MASK_INVOKEIDLIST 调用 IContextMenu 时，hProcess 不会返回。

注解

如果调用 ShellExecuteEx 的线程没有消息循环，或者线程或进程将在 ShellExecuteEx 返回后不久终止，则必须指定SEE_MASK_NOASYNC标志。在这种情况下，调用线程将无法完成 DDE 会话，因此 ShellExecuteExecuteEx 在将控制权返回到调用应用程序之前完成会话非常重要。未能完成会话可能会导致文档启动失败。

如果调用线程具有消息循环，并且将在对 ShellExecuteEx 的调用返回后存在一段时间， 则 SEE_MASK_NOASYNC 标志是可选的。如果省略标志，则调用线程的消息泵将用于完成 DDE 会话。调用应用程序会更快地重新获得控制权，因为 DDE 对话可以在后台完成。

若要在 lpParameters 中包含双引号，请将每个标记括在一对引号中，如以下示例所示。

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

在本例中，应用程序接收三个参数：An、example：和“带引号的文本”。

注意

shellapi.h 标头将 SHELLEXECUTEINFO 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	shellapi.h

SHELLEXECUTEINFOA 结构 (shellapi.h)

语法

成员

注解

要求

反馈

反馈

其他资源