Navigation
Install the app
How to install the app on iOS
Follow along with the video below to see how to install our site as a web app on your home screen.
Note: This feature may not be available in some browsers.
More options
-
Congratulations Mike Lewis on being selected by the Tek-Tips community for having the most helpful posts in the forums last week. Way to Go!
You are using an out of date browser. It may not display this or other websites correctly.
You should upgrade or use an alternative browser.
You should upgrade or use an alternative browser.
How do I use ShellExecuteEx?
Execute (spawn) a program
How do I use ShellExecuteEx?
by
2ffat
Posted
(Edited
)
Declaration
lpExecInfo is a pointer to SHELLEXECUTEINFO structure.
SHELLEXECUTEINFO has the structure of:
cbSize specifies the size, in bytes, of the structure.
fMask is an array of flags that indicate the content and validity of the other structure members. You can specify a combination of the following values:
[tab][color blue]SEE_MASK_CLASSKEY[/color] -- Use the class key given by the hkeyClass member.
[tab][color blue]SEE_MASK_CLASSNAME[/color] -- Use the class name given by the lpClass member.
[tab][color blue]SEE_MASK_CONNECTNETDRV[/color] -- The lpFile member is a Universal Naming Convention (UNC) path of a file on a network. Validate the share and connect to a drive letter.
[tab][color blue]SEE_MASK_DOENVSUBST[/color] -- Expand any environment variables specified in the string given by the lpDirectory or lpFile member.
[tab][color blue]SEE_MASK_FLAG_DDEWAIT[/color] -- Wait for the DDE conversation to terminate before returning, if the ShellExecuteEx function causes a DDE conversation to start.
[tab][color blue]SEE_MASK_FLAG_NO_UI[/color] -- Do not display an error message box if an error occurs.
[tab][color blue]SEE_MASK_HOTKEY[/color] -- Use the hot key given by the dwHotKey member.
[tab][color blue]SEE_MASK_ICON[/color] -- Use the icon given by the hIcon member.
[tab][color blue]SEE_MASK_IDLIST[/color] -- Use the item identifier list given by the lpIDList member.
[tab][color blue]SEE_MASK_INVOKEIDLIST[/color] -- Use the item identifier list given by the lpIDList member to invoke an application. If this member is NULL, the function creates an item identifier list and invokes the application. SEE_MASK_INVOKEIDLIST overrides SEE_MASK_IDLIST.
[tab][color blue]SEE_MASK_NOCLOSEPROCESS[/color] -- Leave the process running after the ShellExecuteEx function exits. The hProcess member receives the handle of the process.
hwnd is the handle to the parent window for any message boxes that the system may produce while executing this function (for example, for error reporting).
lpVerb is a pointer to a string specifying the name of a verb. The verb specifies an action for the application to perform. This member defaults to "Open" if no verb is specified.
lpFile is a pointer to a list of null-terminated strings that specify the names of the files to open or print. The function can open an executable file or a document file. The function can print a document file. If the path is not included with a name, the current directory is assumed.
lpParameters is a pointer to a null-terminated string containing the application parameters. The parameters must be separated by spaces. To include double quotation marks, you must enclose the marks in double quotation marks. If lpFile specifies a document file, lpParameters should be NULL.
lpDirectory is a pointer to a null-terminated string that specifies the name of the working directory. If this member is not specified, the current directory is used as the working directory.
nShow is the show flags. Can be one of the SW_ values described for the ShowWindow function. If lpFile specifies an executable file, nShow specifies how the application is to be shown when it is opened. If lpFile specifies a document file, nShow should be zero.
hInstApp is the handle to the instance of the application that was started or an error value if the application could not be started. (This handle could also be the handle of a dynamic data exchange [DDE] server application.) This member is set on return. Error values can be one of the following:
[tab][color blue]SE_ERR_FNF[/color] -- File not found
[tab][color blue]SE_ERR_PNF[/color] -- Path not found
[tab][color blue]SE_ERR_ACCESSDENIED[/color] -- Access denied
[tab][color blue]SE_ERR_OOM[/color] -- Out of memory
[tab][color blue]SE_ERR_DLLNOTFOUND[/color] -- Dynamic-link library not found
[tab][color blue]SE_ERR_SHARE[/color] -- Cannot share open file
[tab][color blue]SE_ERR_ASSOCINCOMPLETE[/color] -- File association information not complete
[tab][color blue]SE_ERR_DDETIMEOUT[/color] -- DDE operation timed out
[tab][color blue]SE_ERR_DDEFAIL[/color] -- DDE operation failed
[tab][color blue]SE_ERR_DDEBUSY[/color] -- DDE operation busy
[tab][color blue]SE_ERR_NOASSOC[/color] -- File association not available
lpIDList is a pointer to an ITEMIDLIST structure that contains an item identifier list that uniquely identifies the file to execute. Ignored if fMask is not set to SEE_MASK_IDLIST.
lpClass is a pointer to a null-terminated string specifying the name of a file class or a globally unique identifier (GUID). Ignored if fMask is not set to SEE_MASK_CLASSNAME.
hkeyClass is the handle to the registry key for the file class. Ignored if fMask is not set to SEE_MASK_CLASSKEY.
dwHotKey is th hoot key to associate with the application. The low-order word is the virtual-key code, and the high-order word is a modifier flag (HOTKEYF_). For a list of modifier flags, see the description of the WM_SETHOTKEY message. Ignored if fMask is not set to SEE_MASK_HOTKEY.
hIcon is the handle to the icon for the file class. Ignored if fMask is not set to SEE_MASK_ICON.
hProcess is the handle to the newly started application. This member is set on return and is always NULL if fMask is not set to SEE_MASK_NOCLOSEPROCESS.
[tab]If ShellExecuteEx succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to the instance handle of the application that the function started and returns non-zero. If the function fails it returns 0 and sets an error flag to one of the following:
[tab][color blue]ERROR_FILE_NOT_FOUND[/color] -- The specified file was not found.
[tab][color blue]ERROR_PATH_NOT_FOUND[/color] -- The specified path was not found.
[tab][color blue]ERROR_DDE_FAIL[/color] -- The DDE transaction failed.
[tab][color blue]ERROR_NO_ASSOCIATION[/color] -- There is no application associated with the given filename extension.
[tab][color blue]ERROR_ACCESS_DENIED[/color] -- Access is denied.
[tab][color blue]ERROR_DLL_NOT_FOUND[/color] -- DLL is not found.
[tab][color blue]ERROR_CANCELLED[/color] -- The function prompted the user for the location of the application, but the user cancelled the request.
[tab][color blue]ERROR_NOT_ENOUGH_MEMORY[/color] -- Not enough memory to spawn program.
[tab][color blue]ERROR_SHARING_VIOLATION[/color] -- A sharing violation occurred.
[tab] In addition hInstApp is one of the SE_ERR_ error values indicating the cause of the failure. (An instance handle will always be greater than 32, and an error value less than 32.) Note that the SE_ERR_ error values are for compatibility with the ShellExecute function; use the GetLastError function to retrieve error information.
Pros
[tab]This function allows the user to wait for a spawned process. It is very powerful and flexiable.
Cons
[tab]This is a complex function. You must set up the structure to use it.
Examples
[tab]The following example came from March 1999 C++ Builders Developer's Journal (see http://bcbjournal.org/index.php).
Code:
WINSHELLAPI BOOL WINAPI ShellExecuteEx(LPSHELLEXECUTEINFO lpExecInfo );lpExecInfo is a pointer to SHELLEXECUTEINFO structure.
SHELLEXECUTEINFO has the structure of:
Code:
typedef struct _SHELLEXECUTEINFO {
DWORD cbSize;
ULONG fMask;
HWND hwnd;
LPCSTR lpVerb;
LPCSTR lpFile;
LPCSTR lpParameters;
LPCSTR lpDirectory;
int nShow;
HINSTANCE hInstApp;
// Optional members
LPVOID lpIDList;
LPCSTR lpClass;
HKEY hkeyClass;
DWORD dwHotKey;
HANDLE hIcon;
HANDLE hProcess;
} SHELLEXECUTEINFO, FAR *LPSHELLEXECUTEINFO;cbSize specifies the size, in bytes, of the structure.
fMask is an array of flags that indicate the content and validity of the other structure members. You can specify a combination of the following values:
[tab][color blue]SEE_MASK_CLASSKEY[/color] -- Use the class key given by the hkeyClass member.
[tab][color blue]SEE_MASK_CLASSNAME[/color] -- Use the class name given by the lpClass member.
[tab][color blue]SEE_MASK_CONNECTNETDRV[/color] -- The lpFile member is a Universal Naming Convention (UNC) path of a file on a network. Validate the share and connect to a drive letter.
[tab][color blue]SEE_MASK_DOENVSUBST[/color] -- Expand any environment variables specified in the string given by the lpDirectory or lpFile member.
[tab][color blue]SEE_MASK_FLAG_DDEWAIT[/color] -- Wait for the DDE conversation to terminate before returning, if the ShellExecuteEx function causes a DDE conversation to start.
[tab][color blue]SEE_MASK_FLAG_NO_UI[/color] -- Do not display an error message box if an error occurs.
[tab][color blue]SEE_MASK_HOTKEY[/color] -- Use the hot key given by the dwHotKey member.
[tab][color blue]SEE_MASK_ICON[/color] -- Use the icon given by the hIcon member.
[tab][color blue]SEE_MASK_IDLIST[/color] -- Use the item identifier list given by the lpIDList member.
[tab][color blue]SEE_MASK_INVOKEIDLIST[/color] -- Use the item identifier list given by the lpIDList member to invoke an application. If this member is NULL, the function creates an item identifier list and invokes the application. SEE_MASK_INVOKEIDLIST overrides SEE_MASK_IDLIST.
[tab][color blue]SEE_MASK_NOCLOSEPROCESS[/color] -- Leave the process running after the ShellExecuteEx function exits. The hProcess member receives the handle of the process.
hwnd is the handle to the parent window for any message boxes that the system may produce while executing this function (for example, for error reporting).
lpVerb is a pointer to a string specifying the name of a verb. The verb specifies an action for the application to perform. This member defaults to "Open" if no verb is specified.
lpFile is a pointer to a list of null-terminated strings that specify the names of the files to open or print. The function can open an executable file or a document file. The function can print a document file. If the path is not included with a name, the current directory is assumed.
lpParameters is a pointer to a null-terminated string containing the application parameters. The parameters must be separated by spaces. To include double quotation marks, you must enclose the marks in double quotation marks. If lpFile specifies a document file, lpParameters should be NULL.
lpDirectory is a pointer to a null-terminated string that specifies the name of the working directory. If this member is not specified, the current directory is used as the working directory.
nShow is the show flags. Can be one of the SW_ values described for the ShowWindow function. If lpFile specifies an executable file, nShow specifies how the application is to be shown when it is opened. If lpFile specifies a document file, nShow should be zero.
hInstApp is the handle to the instance of the application that was started or an error value if the application could not be started. (This handle could also be the handle of a dynamic data exchange [DDE] server application.) This member is set on return. Error values can be one of the following:
[tab][color blue]SE_ERR_FNF[/color] -- File not found
[tab][color blue]SE_ERR_PNF[/color] -- Path not found
[tab][color blue]SE_ERR_ACCESSDENIED[/color] -- Access denied
[tab][color blue]SE_ERR_OOM[/color] -- Out of memory
[tab][color blue]SE_ERR_DLLNOTFOUND[/color] -- Dynamic-link library not found
[tab][color blue]SE_ERR_SHARE[/color] -- Cannot share open file
[tab][color blue]SE_ERR_ASSOCINCOMPLETE[/color] -- File association information not complete
[tab][color blue]SE_ERR_DDETIMEOUT[/color] -- DDE operation timed out
[tab][color blue]SE_ERR_DDEFAIL[/color] -- DDE operation failed
[tab][color blue]SE_ERR_DDEBUSY[/color] -- DDE operation busy
[tab][color blue]SE_ERR_NOASSOC[/color] -- File association not available
lpIDList is a pointer to an ITEMIDLIST structure that contains an item identifier list that uniquely identifies the file to execute. Ignored if fMask is not set to SEE_MASK_IDLIST.
lpClass is a pointer to a null-terminated string specifying the name of a file class or a globally unique identifier (GUID). Ignored if fMask is not set to SEE_MASK_CLASSNAME.
hkeyClass is the handle to the registry key for the file class. Ignored if fMask is not set to SEE_MASK_CLASSKEY.
dwHotKey is th hoot key to associate with the application. The low-order word is the virtual-key code, and the high-order word is a modifier flag (HOTKEYF_). For a list of modifier flags, see the description of the WM_SETHOTKEY message. Ignored if fMask is not set to SEE_MASK_HOTKEY.
hIcon is the handle to the icon for the file class. Ignored if fMask is not set to SEE_MASK_ICON.
hProcess is the handle to the newly started application. This member is set on return and is always NULL if fMask is not set to SEE_MASK_NOCLOSEPROCESS.
[tab]If ShellExecuteEx succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to the instance handle of the application that the function started and returns non-zero. If the function fails it returns 0 and sets an error flag to one of the following:
[tab][color blue]ERROR_FILE_NOT_FOUND[/color] -- The specified file was not found.
[tab][color blue]ERROR_PATH_NOT_FOUND[/color] -- The specified path was not found.
[tab][color blue]ERROR_DDE_FAIL[/color] -- The DDE transaction failed.
[tab][color blue]ERROR_NO_ASSOCIATION[/color] -- There is no application associated with the given filename extension.
[tab][color blue]ERROR_ACCESS_DENIED[/color] -- Access is denied.
[tab][color blue]ERROR_DLL_NOT_FOUND[/color] -- DLL is not found.
[tab][color blue]ERROR_CANCELLED[/color] -- The function prompted the user for the location of the application, but the user cancelled the request.
[tab][color blue]ERROR_NOT_ENOUGH_MEMORY[/color] -- Not enough memory to spawn program.
[tab][color blue]ERROR_SHARING_VIOLATION[/color] -- A sharing violation occurred.
[tab] In addition hInstApp is one of the SE_ERR_ error values indicating the cause of the failure. (An instance handle will always be greater than 32, and an error value less than 32.) Note that the SE_ERR_ error values are for compatibility with the ShellExecute function; use the GetLastError function to retrieve error information.
Pros
[tab]This function allows the user to wait for a spawned process. It is very powerful and flexiable.
Cons
[tab]This is a complex function. You must set up the structure to use it.
Examples
[tab]The following example came from March 1999 C++ Builders Developer's Journal (see http://bcbjournal.org/index.php).
Code:
SHELLEXECUTEINFO ShellInfo; // Name structure
memset(&ShellInfo, 0, sizeof(ShellInfo)); // Set up memory block
ShellInfo.cbSize = sizeof(ShellInfo)); // Set up structure size
ShellInfo.hwnd = Handle; // Calling window handle
ShellInfo.lpVerb = "open"; // Open the file with default program
ShellInfo.lpFile = "MyFile.txt"; // File to open
ShellInfo.nShow = SW_NORMAL; // Open in normal window
ShellInfo.fMask = SEE_MASK_NOCLOSEPROCESS; // Necessary if you want to wait for spawned process
bool res = ShellExecuteEx(&ShellInfo); // Call to function
if (res)
WaitForSingleObject(ShellInfo.hProcess, INFINITE); // wait forever for process to finish
Please Note: 1 is Bad, 10 is Good :-)
Part and Inventory Search
-
This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
By continuing to use this site, you are consenting to our use of cookies.