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:
    SEE_MASK_CLASSKEY -- Use the class key given by the hkeyClass member.
    SEE_MASK_CLASSNAME -- Use the class name given by the lpClass member.
    SEE_MASK_CONNECTNETDRV -- 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.
    SEE_MASK_DOENVSUBST -- Expand any environment variables specified in the string given by the lpDirectory or lpFile member.
    SEE_MASK_FLAG_DDEWAIT -- Wait for the DDE conversation to terminate before returning, if the ShellExecuteEx function causes a DDE conversation to start.
    SEE_MASK_FLAG_NO_UI -- Do not display an error message box if an error occurs.
    SEE_MASK_HOTKEY -- Use the hot key given by the dwHotKey member.
    SEE_MASK_ICON -- Use the icon given by the hIcon member.
    SEE_MASK_IDLIST -- Use the item identifier list given by the lpIDList member.
    SEE_MASK_INVOKEIDLIST -- 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.
    SEE_MASK_NOCLOSEPROCESS -- 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:
    SE_ERR_FNF -- File not found
    SE_ERR_PNF -- Path not found
    SE_ERR_ACCESSDENIED -- Access denied
    SE_ERR_OOM -- Out of memory
    SE_ERR_DLLNOTFOUND -- Dynamic-link library not found
    SE_ERR_SHARE -- Cannot share open file
    SE_ERR_ASSOCINCOMPLETE -- File association information not complete
    SE_ERR_DDETIMEOUT -- DDE operation timed out
    SE_ERR_DDEFAIL -- DDE operation failed
    SE_ERR_DDEBUSY -- DDE operation busy
    SE_ERR_NOASSOC -- 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.

    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:
    ERROR_FILE_NOT_FOUND -- The specified file was not found.
    ERROR_PATH_NOT_FOUND -- The specified path was not found.
    ERROR_DDE_FAIL -- The DDE transaction failed.
    ERROR_NO_ASSOCIATION -- There is no application associated with the given filename extension.
    ERROR_ACCESS_DENIED -- Access is denied.
    ERROR_DLL_NOT_FOUND -- DLL is not found.
    ERROR_CANCELLED -- The function prompted the user for the location of the application, but the user cancelled the request.
    ERROR_NOT_ENOUGH_MEMORY -- Not enough memory to spawn program.
    ERROR_SHARING_VIOLATION -- A sharing violation occurred.
     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
    This function allows the user to wait for a spawned process. It is very powerful and flexiable.

Cons
    This is a complex function. You must set up the structure to use it.

Examples
    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

Back to Embarcadero: C++Builder FAQ Index
Back to Embarcadero: C++Builder Forum

My Archive

My FAQ Archive

Member Login

Come Join Us!

LINK TO THIS FORUM!

Tek-Tips LinkedIn® Group

Partner With Us!

Feedback

Geography

Tek-Tips Shirts!

Embarcadero: C++Builder FAQ

Execute (spawn) a program

CODE

CODE

CODE

My Archive

Join Tek-Tips® Today!

Tek-Tips LinkedIn^® Group

Join Tek-Tips^® Today!