SHELLEXECUTEINFO

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

The SHELLEXECUTEINFO structure contains information used by the ShellExecuteEx function.

Syntax

typedef struct _SHELLEXECUTEINFO { 
  DWORD cbSize; 
  ULONG fMask; 
  HWND hwnd; 
  LPCTSTR lpVerb; 
  LPCTSTR lpFile; 
  LPCTSTR lpParameters; 
  LPCTSTR lpDirectory; 
  int nShow; 
  HINSTANCE hInstApp; 
  LPVOID lpIDList; 
  LPCTSTR lpClass; 
  HKEY hkeyClass; 
  DWORD dwHotKey; 
  union {
    HANDLE hIcon;
    HANDLE hMonitor;
  } DUMMYUNIONNAME;
  HANDLE hProcess; 
} SHELLEXECUTEINFO, FAR* LPSHELLEXECUTEINFO;

Members

  • cbSize
    Size of the structure, in bytes.

  • fMask
    Array of flags that indicate the content and validity of the other structure members. For Windows CE 1.0 and 1.01, fMask flags are unsupported. For Windows CE 2.0 and later, fMask can be a combination of the following values.

    Value Description

    SEE_MASK_FLAG_NO_UI

    Does not display an error message box if an error occurs.

    SEE_MASK_NOCLOSEPROCESS

    Leaves the process running after the ShellExecuteEx function exits. The hProcess member receives the handle to the process.
  • hwnd
    Window handle to any message boxes that the system may produce while executing this function.

  • lpVerb
    Long pointer to a string specifying the name of a verb. The verb specifies an action for the application to perform. The set of available verbs depends on the particular file or folder. It includes the commands listed in the context menu and the registry. The following table shows verbs that are usually valid.

    Value Description

    Edit

    The function opens an editor.

    Find

    The function initiates a search starting from the specified directory.

    Open

    The function opens the file specified by the lpFile parameter. The file can be an executable file or a document file. It can also be a folder. This is the default verb if no verb is specified.

    Print

    The function prints the document file specified by lpFile.
  • lpFile
    Long pointer to a null-terminated string that specifies the absolute name of the file to open or print. The function can open an executable file or a document file, but it can only print a document file. Note that the concept of a current directory does not exist in Windows Embedded CE. You must specify the complete file path to specify the absolute file name.

  • lpParameters
    Long pointer to a null-terminated string that contains the application parameters. The parameters must be separated by spaces. To include double quotation marks, you must enclose the marks in double quotation marks, as in the following example.

    sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

    In this case, the application receives three parameters: An, example:, and "quoted text".

    If the lpFile member specifies a document file, this member should be NULL.

  • lpDirectory
    Not supported. Set to zero.
  • nShow
    Show flags. Can be one of the SW_* values described for the ShowWindow function. If lpFile specifies an executable file, this member specifies how the application is to be shown when it is opened.

  • hInstApp
    This member is only valid if the function fails, in which case it receives one of the following error values, which are less than or equal to 32.

    Value Description

    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 an 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 is busy.

    SE_ERR_NOASSOC

    File association not available.

    If the function succeeds, the value of this member should be ignored.

  • lpIDList
    Ignored.
  • lpClass
    Ignored.
  • hkeyClass
    Ignored.
  • dwHotKey
    Ignored.
  • hIcon
    Ignored.
  • hProcess
    Handle to the newly started application. This member is set on return and is always set to NULL if fMask is not set to SEE_MASK_NOCLOSEPROCESS.

Remarks

The verbs available for an object are essentially the items that you find on an object's shortcut menu. To find which verbs are available, look in the registry under

HKEY_CLASSES_ROOT\<object_name>\Shell\<verb>

object_name is the name of the file object and verb is the name of the available verb. The verb subkey contains the data indicating what happens when that verb is invoked.

Each verb corresponds to the command that would be used to launch the application from a console window. The open verb is a good example, because it is commonly supported. For .exe files, open launches the application. However, it is more commonly used to launch an application that operates on a particular file. For instance, .txt files can be opened by Microsoft® WordPad. The open verb for a .txt file corresponds to the following command:

"C:\Program Files\Windows NT\Accessories\Wordpad.exe" "%1"

When you use ShellExecuteEx to open a .txt file, Wordpad.exe is launched with the specified file as its argument. Some commands can have additional arguments, such as flags, that can be added as needed to launch the application properly.

In general, trying to determine the list of available verbs for a particular file is somewhat complicated. In many cases, you can set the lpVerb member to NULL, which invokes the default command for the file class. This procedure is usually equivalent to setting lpVerb to open, but some file classes may have a different default command.

Requirements

Header shellapi.h
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

ShellExecuteEx
ShowWindow

Other Resources