shellExecuteW 函数 (shellapi.h)

对指定文件执行操作。

语法

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

参数

[in, optional] hwnd

类型:HWND

用于显示 UI 或错误消息的父窗口的句柄。 如果操作未与窗口关联,则此值可以为 NULL

[in, optional] lpOperation

类型: LPCTSTR

指向以 null 结尾的字符串(在本例中称为 谓词)的指针,指定要执行的操作。 可用谓词集取决于特定的文件或文件夹。 通常,对象的快捷菜单中可用的操作是可用的谓词。 通常使用以下谓词:

编辑

启动编辑器并打开文档进行编辑。 如果 lpFile 不是文档文件,则函数将失败。

浏览

浏览 lpFile 指定的文件夹。

find

启动从 lpDirectory 指定的目录开始的搜索。

打开

打开 lpFile 参数指定的项。 该项可以是文件或文件夹。

print

打印 lpFile 指定的文件。 如果 lpFile 不是文档文件,则函数将失败。

运行方式

以管理员身份启动应用程序。 用户帐户控制 (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 可以将执行委托给使用组件对象模型 (COM) 激活的 Shell 扩展 (数据源、上下文菜单处理程序、谓词实现) ,因此应在调用 ShellExecute 之前初始化 COM。 某些 Shell 扩展需要 COM 单线程单元 (STA) 类型。 在这种情况下,应初始化 COM,如下所示:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

当然,在某些情况下 ,ShellExecute 不使用这些类型的 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 的 Find 实用工具,请使用以下调用。

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

如果 lpOperationNULL,则该函数将打开 lpFile 指定的文件。 如果 lpOperation 为“open”或“explore”,则函数将尝试打开或浏览文件夹。

若要获取有关由于调用 ShellExecute 而启动的应用程序的信息,请使用 ShellExecuteExecuteEx

注意 “文件夹选项” 中单独进程设置中的“启动 文件夹”窗口会影响 ShellExecute。 如果此选项 (默认设置) 禁用, 则 ShellExecute 将使用打开的资源管理器窗口,而不是启动新窗口。 如果没有打开资源管理器窗口, ShellExecute 将启动一个新窗口。
 

注意

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

要求

要求
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 shellapi.h
Library Shell32.lib
DLL Shell32.dll (版本 3.51 或更高版本)

另请参阅

CoInitializeEx

CreateProcessW

IShellExecuteHook

(ShellExecute、ShellExecuteExecuteEx、SHELLEXECUTEINFO) 启动应用程序

ShellExecuteEx