ShellExecute

3.1

  #include <shellapi.h>    

  HINSTANCE ShellExecute(hwnd, lpszOp, lpszFile, lpszParams, lpszDir, fsShowCmd)    
  HWND hwnd; /* handle of parent window */
  LPCSTR lpszOp; /* address of string for operation to perform */
  LPCSTR lpszFile; /* address of string for filename */
  LPCSTR lpszParams; /* address of string for executable-file parameters */
  LPCSTR lpszDir; /* address of string for default directory */
  int fsShowCmd; /* whether file is shown when opened */

The ShellExecute function opens or prints the specified file.

Parameters

hwnd

Identifies the parent window. This window receives any message boxes an application produces (for example, for error reporting).

lpszOp

Points to a null-terminated string specifying the operation to perform. This string can be “open” or “print”. If this parameter is NULL, “open” is the default value.

lpszFile

Points to a null-terminated string specifying the file to open.

lpszParams

Points to a null-terminated string specifying parameters passed to the application when the lpszFile parameter specifies an executable file. If lpszFile points to a string specifying a document file, this parameter is NULL.

lpszDir

Points to a null-terminated string specifying the default directory.

fsShowCmd

Specifies whether the application window is to be shown when the application is opened. This parameter can be one of the following values:

Value Meaning

SW_HIDE Hides the window and passes activation to another window.
SW_MINIMIZE Minimizes the specified window and activates the top-level window in the system's list.
SW_RESTORE Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL).
SW_SHOW Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED Activates a window and displays it as a maximized window.
SW_SHOWMINIMIZED Activates a window and displays it as an icon.
SW_SHOWMINNOACTIVE Displays a window as an icon. The window that is currently active remains active.
SW_SHOWNA Displays a window in its current state. The window that is currently active remains active.
SW_SHOWNOACTIVATE Displays a window in its most recent size and position. The window that is currently active remains active.
SW_SHOWNORMAL Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_RESTORE).

Return Value

The return value is the instance handle of the application that was opened or printed, if the function is successful. (This handle could also be the handle of a DDE server application.) A return value less than or equal to 32 specifies an error. The possible error values are listed in the following Comments section.

Errors

The ShellExecute function returns the value 31 if there is no association for the specified file type or if there is no association for the specified action within the file type. The other possible error values are as follows:

Value Meaning

0 System was out of memory, executable file was corrupt, or relocations were invalid.
2 File was not found.
3 Path was not found.
5 Attempt was made to dynamically link to a task, or there was a sharing or network-protection error.
6 Library required separate data segments for each task.
8 There was insufficient memory to start the application.
10 Windows version was incorrect.
11 Executable file was invalid. Either it was not a Windows application or there was an error in the .EXE image.
12 Application was designed for a different operating system.
13 Application was designed for MS-DOS 4.0.
14 Type of executable file was unknown.
15 Attempt was made to load a real-mode application (developed for an earlier version of Windows).
16 Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.
19 Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded.
20 Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this application was corrupt.
21 Application requires Microsoft Windows 32-bit extensions.

Comments

The file specified by the lpszFile parameter can be a document file or an executable file. If it is a document file, this function opens or prints it, depending on the value of the lpszOp parameter. If it is an executable file, this function opens it, even if the string “print” is pointed to by lpszOp.

See Also

FindExecutable