ShellExecuteExA function (shellapi.h)

Performs an operation on a specified file.

Syntax

BOOL ShellExecuteExA(
  [in, out] SHELLEXECUTEINFOA *pExecInfo
);

Parameters

[in, out] pExecInfo

Type: SHELLEXECUTEINFO*

A pointer to a SHELLEXECUTEINFO structure that contains and receives information about the application being executed.

Return value

Type: BOOL

Returns TRUE if successful; otherwise, FALSE. Call GetLastError for extended error information.

Remarks

Because ShellExecuteEx can delegate execution to Shell extensions (data sources, context menu handlers, verb implementations) that are activated using Component Object Model (COM), COM should be initialized before ShellExecuteEx is called. Some Shell extensions require the COM single-threaded apartment (STA) type. In that case, COM should be initialized as shown here:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

There are instances where ShellExecuteEx does not use one of these types of Shell extension and those instances would not require COM to be initialized at all. Nonetheless, it is good practice to always initialize COM before using this function.

When DLLs are loaded into your process, you acquire a lock known as a loader lock. The DllMain function always executes under the loader lock. It is important that you do not call ShellExecuteEx while you hold a loader lock. Because ShellExecuteEx is extensible, you could load code that does not function properly in the presence of a loader lock, risking a deadlock and therefore an unresponsive thread.

With multiple monitors, if you specify an HWND and set the lpVerb member of the SHELLEXECUTEINFO structure pointed to by lpExecInfo to "Properties", any windows created by ShellExecuteEx might not appear in the correct position.

If the function succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to a value greater than 32. If the function fails, hInstApp is set to the SE_ERR_XXX error value that best indicates the cause of the failure. Although hInstApp is declared as an HINSTANCE for compatibility with 16-bit Windows applications, it is not a true HINSTANCE. It can be cast only to an int and can be compared only to either the value 32 or the SE_ERR_XXX error codes.

The SE_ERR_XXX error values are provided for compatibility with ShellExecute. To retrieve more accurate error information, use GetLastError. It may return one of the following values.

Opening items from a URL You can register your application to activate when passed URLs. You can also specify which protocols your application supports. See Application Registration for more info.

Site chain support As of Windows 8, you can provide a site chain pointer to the ShellExecuteEx function to support item activation with services from that site. See Launching Applications (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO) for more information.

Requirements

See also

CoInitializeEx

IShellExecuteHook

Launching Applications (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecute