@Structure.FieldOrder(value={"cbSize","fMask","hwnd","lpVerb","lpFile","lpParameters","lpDirectory","nShow","hInstApp","lpIDList","lpClass","hKeyClass","dwHotKey","hMonitor","hProcess"}) public static class ShellAPI.SHELLEXECUTEINFO extends Structure
Contains information used by ShellExecuteEx.
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, *LPSHELLEXECUTEINFO;
The SEE_MASK_NOASYNC flag must be specified if the thread calling ShellExecuteEx does not have a message loop or if the thread or process will terminate soon after ShellExecuteEx returns. Under such conditions, the calling thread will not be available to complete the DDE conversation, so it is important that ShellExecuteEx complete the conversation before returning control to the calling application. Failure to complete the conversation can result in an unsuccessful launch of the document.
If the calling thread has a message loop and will exist for some time after the call to ShellExecuteEx returns, the SEE_MASK_NOASYNC flag is optional. If the flag is omitted, the calling thread's message pump will be used to complete the DDE conversation. The calling application regains control sooner, since the DDE conversation can be completed in the background.
When populating the most frequently used program list using the SEE_MASK_FLAG_LOG_USAGE flag in fMask, counts are made differently for the classic and Windows XP-style Start menus. The classic style menu only counts hits to the shortcuts in the Program menu. The Windows XP-style menu counts both hits to the shortcuts in the Program menu and hits to those shortcuts' targets outside of the Program menu. Therefore, setting lpFile to myfile.exe would affect the count for the Windows XP-style menu regardless of whether that file was launched directly or through a shortcut. The classic style-which would require lpFile to contain a .lnk file name-would not be affected.
To include double quotation marks in lpParameters, enclose each mark in a pair of 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".
Structure.ByReference, Structure.ByValue, Structure.FieldOrder, Structure.StructField| Modifier and Type | Field and Description |
|---|---|
int |
cbSize
Type: DWORD
Required.
|
int |
dwHotKey
Type: DWORD
A keyboard shortcut to associate with the application.
|
int |
fMask
Type: ULONG
Flags that indicate the content and validity of the other structure
members; a combination of the following values:
|
WinDef.HINSTANCE |
hInstApp
Type: HINSTANCE
[out] If SEE_MASK_NOCLOSEPROCESS is set and the call succeeds, it
sets this member to a value greater than 32.
|
WinReg.HKEY |
hKeyClass
Type: HKEY
A handle to the registry key for the file type.
|
WinNT.HANDLE |
hMonitor
This is actually a union:
union { HANDLE hIcon; HANDLE hMonitor; } DUMMYUNIONNAME;
DUMMYUNIONNAME
hIcon
Type: HANDLE
A handle to the icon for the file type. |
WinNT.HANDLE |
hProcess
Type: HANDLE
A handle to the newly started application.
|
WinDef.HWND |
hwnd
Type: HWND
Optional.
|
java.lang.String |
lpClass
Type: LPCTSTR
The address of a null-terminated string that specifies one of the
following:
A ProgId.
|
java.lang.String |
lpDirectory
Type: LPCTSTR
Optional.
|
java.lang.String |
lpFile
Type: LPCTSTR
The address of a null-terminated string that specifies the name of
the file or object on which will perform the action specified by the
lpVerb parameter.
|
Pointer |
lpIDList
Type: LPVOID
The address of an absolute
ITEMIDLIST
structure (PCIDLIST_ABSOLUTE) to contain an item identifier list that
uniquely identifies the file to execute.
|
java.lang.String |
lpParameters
Type: LPCTSTR
Optional.
|
java.lang.String |
lpVerb
Type: LPCTSTR
A string, referred to as a verb, that specifies the action
to be performed.
|
int |
nShow
Type: int
Required.
|
ALIGN_DEFAULT, ALIGN_GNUC, ALIGN_MSVC, ALIGN_NONE, CALCULATE_SIZE| Constructor and Description |
|---|
SHELLEXECUTEINFO() |
allocateMemory, allocateMemory, autoAllocate, autoRead, autoRead, autoWrite, autoWrite, cacheTypeInfo, calculateSize, clear, createFieldsOrder, createFieldsOrder, createFieldsOrder, createFieldsOrder, dataEquals, dataEquals, ensureAllocated, equals, fieldOffset, getAutoRead, getAutoWrite, getFieldList, getFieldOrder, getFields, getNativeAlignment, getNativeSize, getNativeSize, getPointer, getStringEncoding, getStructAlignment, hashCode, newInstance, newInstance, read, readField, readField, setAlignType, setAutoRead, setAutoSynch, setAutoWrite, setStringEncoding, size, sortFields, toArray, toArray, toString, toString, useMemory, useMemory, write, writeField, writeField, writeFieldpublic int cbSize
Type: DWORD
Required. The size of this structure, in bytes.
public int fMask
Type: ULONG
Flags that indicate the content and validity of the other structure members; a combination of the following values:
SEE_MASK_DEFAULT (0x00000000)
Use default values.
SEE_MASK_CLASSNAME (0x00000001)
Use the class name given by the lpClass member. If both SEE_MASK_CLASSKEY and SEE_MASK_CLASSNAME are set, the class key is used.
SEE_MASK_CLASSKEY (0x00000003)
Use the class key given by the hkeyClass member. If both SEE_MASK_CLASSKEY and SEE_MASK_CLASSNAME are set, the class key is used.
SEE_MASK_IDLIST (0x00000004)
Use the item identifier list given by the lpIDList member. The lpIDList member must point to an structure.
SEE_MASK_INVOKEIDLIST (0x0000000C)
Use the interface of the selected item's . Use either lpFile to identify the item by its file system path or lpIDList to identify the item by its PIDL. This flag allows applications to use to invoke verbs from shortcut menu extensions instead of the static verbs listed in the registry.
SEE_MASK_ICON (0x00000010)
Use the icon given by the hIcon member. This flag cannot be combined with SEE_MASK_HMONITOR.
SEE_MASK_HOTKEY (0x00000020)
Use the keyboard shortcut given by the dwHotKey member.
SEE_MASK_NOCLOSEPROCESS (0x00000040)
Use to indicate that the hProcess member receives the process handle. This handle is typically used to allow an application to find out when a process created with terminates. In some cases, such as when execution is satisfied through a DDE conversation, no handle will be returned. The calling application is responsible for closing the handle when it is no longer needed.
SEE_MASK_CONNECTNETDRV (0x00000080)
Validate the share and connect to a drive letter. This enables reconnection of disconnected network drives. The lpFile member is a UNC path of a file on a network.
SEE_MASK_NOASYNC (0x00000100)
Wait for the execute operation to complete before returning. This flag should be used by callers that are using ShellExecute forms that might result in an async activation, for example DDE, and create a process that might be run on a background thread. (Note: runs on a background thread by default if the caller's threading model is not Apartment.) Calls to ShellExecuteEx from processes already running on background threads should always pass this flag. Also, applications that exit immediately after calling ShellExecuteEx should specify this flag.
If the execute operation is performed on a background thread and the caller did not specify the SEE_MASK_ASYNCOK flag, then the calling thread waits until the new process has started before returning. This typically means that either has been called, the DDE communication has completed, or that the custom execution delegate has notified that it is done. If the SEE_MASK_WAITFORINPUTIDLE flag is specified, then ShellExecuteEx calls and waits for the new process to idle before returning, with a maximum timeout of 1 minute.
For further discussion on when this flag is necessary, see the Remarks section.
SEE_MASK_FLAG_DDEWAIT (0x00000100)
Do not use; use SEE_MASK_NOASYNC instead.
SEE_MASK_DOENVSUBST (0x00000200)
Expand any environment variables specified in the string given by the lpDirectory or lpFile member.
SEE_MASK_FLAG_NO_UI (0x00000400)
Do not display an error message box if an error occurs.
SEE_MASK_UNICODE (0x00004000)
Use this flag to indicate a Unicode application.
SEE_MASK_NO_CONSOLE (0x00008000)
Use to inherit the parent's console for the new process instead of having it create a new console. It is the opposite of using a CREATE_NEW_CONSOLE flag with .
SEE_MASK_ASYNCOK (0x00100000)
The execution can be performed on a background thread and the call should return immediately without waiting for the background thread to finish. Note that in certain cases ignores this flag and waits for the process to finish before returning.
SEE_MASK_NOQUERYCLASSSTORE (0x01000000)
Not used.
SEE_MASK_HMONITOR (0x00200000)
Use this flag when specifying a monitor on multi-monitor systems. The monitor is specified in the hMonitor member. This flag cannot be combined with SEE_MASK_ICON.
SEE_MASK_NOZONECHECKS (0x00800000)
Introduced in Windows XP. Do not perform a zone check. This flag allows to bypass zone checking put into place by .
SEE_MASK_WAITFORINPUTIDLE (0x02000000)
After the new process is created, wait for the process to become idle before returning, with a one minute timeout. See for more details.
SEE_MASK_FLAG_LOG_USAGE (0x04000000)
Introduced in Windows XP. Keep track of the number of times this application has been launched. Applications with sufficiently high counts appear in the Start Menu's list of most frequently used programs.
SEE_MASK_FLAG_HINST_IS_SITE (0x08000000)
Introduced in Windows 8. The hInstApp member is used to specify the of an object that implements . This object will be used as a site pointer. The site pointer is used to provide services to the function, the handler binding process, and invoked verb handlers.
public WinDef.HWND hwnd
Type: HWND
Optional. A handle to the parent window, used to display any message boxes that the system might produce while executing this function. This value can be NULL.
public java.lang.String lpVerb
Type: LPCTSTR
A string, referred to as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. This parameter can be NULL, in which case the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry. The following verbs are commonly used:
edit
Launches an editor and opens the document for editing. If lpFile is not a document file, the function will fail.
explore
Explores the folder specified by lpFile.
find
Initiates a search starting from the specified directory.
open
Opens the file specified by the lpFile parameter. The file can be an executable file, a document file, or a folder.
Prints the document file specified by lpFile. If lpFile is not a document file, the function will fail.
properties
Displays the file or folder's properties.
public java.lang.String lpFile
Type: LPCTSTR
The address of a null-terminated string that specifies the name of the file or object on which will perform the action specified by the lpVerb parameter. The system registry verbs that are supported by the ShellExecuteEx function include "open" for executable files and document files and "print" for document files for which a print handler has been registered. Other applications might have added Shell verbs through the system registry, such as "play" for .avi and .wav files. To specify a Shell namespace object, pass the fully qualified parse name and set the SEE_MASK_INVOKEIDLIST flag in the fMask parameter.
public java.lang.String lpParameters
Type: LPCTSTR
Optional. The address of a null-terminated string that contains the application parameters. The parameters must be separated by spaces. If the lpFile member specifies a document file, lpParameters should be NULL.
public java.lang.String lpDirectory
Type: LPCTSTR
Optional. The address of a null-terminated string that specifies the name of the working directory. If this member is NULL, the current directory is used as the working directory.
public int nShow
Type: int
Required. Flags that specify how an application is to be shown when it is opened; one of the SW_ values listed for the ShellExecute function. If lpFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it.
public WinDef.HINSTANCE hInstApp
Type: HINSTANCE
[out] If SEE_MASK_NOCLOSEPROCESS is set and the call succeeds, it sets this member to a value greater than 32. If the function fails, it is set to an SE_ERR_XXX error value that 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 compared to either 32 or the following SE_ERR_XXX error codes.
SE_ERR_FNF (2)
File not found.
SE_ERR_PNF (3)
Path not found.
SE_ERR_ACCESSDENIED (5)
Access denied.
SE_ERR_OOM (8)
Out of memory.
SE_ERR_DLLNOTFOUND (32)
Dynamic-link library not found.
SE_ERR_SHARE (26)
Cannot share an open file.
SE_ERR_ASSOCINCOMPLETE (27)
File association information not complete.
SE_ERR_DDETIMEOUT (28)
DDE operation timed out.
SE_ERR_DDEFAIL (29)
DDE operation failed.
SE_ERR_DDEBUSY (30)
DDE operation is busy.
SE_ERR_NOASSOC (31)
File association not available.
public Pointer lpIDList
Type: LPVOID
The address of an absolute ITEMIDLIST structure (PCIDLIST_ABSOLUTE) to contain an item identifier list that uniquely identifies the file to execute. This member is ignored if the fMask member does not include SEE_MASK_IDLIST or SEE_MASK_INVOKEIDLIST.
public java.lang.String lpClass
Type: LPCTSTR
The address of a null-terminated string that specifies one of the following:
shell\verb name
.This member is ignored if fMask does not include SEE_MASK_CLASSNAME.
public WinReg.HKEY hKeyClass
Type: HKEY
A handle to the registry key for the file type. The access rights for this registry key should be set to KEY_READ. This member is ignored if fMask does not include SEE_MASK_CLASSKEY.
public int dwHotKey
Type: DWORD
A keyboard shortcut 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. This member is ignored if fMask does not include SEE_MASK_HOTKEY.
public WinNT.HANDLE hMonitor
union { HANDLE hIcon; HANDLE hMonitor; } DUMMYUNIONNAME;
DUMMYUNIONNAME
Type: HANDLE
A handle to the icon for the file type. This member is ignored if fMask does not include SEE_MASK_ICON. This value is used only in Windows XP and earlier. It is ignored as of Windows Vista.
Type: HANDLE
A handle to the monitor upon which the document is to be displayed. This member is ignored if fMask does not include SEE_MASK_HMONITOR.
public WinNT.HANDLE hProcess
Type: HANDLE
A handle to the newly started application. This member is set on return and is always NULL unless fMask is set to SEE_MASK_NOCLOSEPROCESS. Even if fMask is set to SEE_MASK_NOCLOSEPROCESS, hProcess will be NULL if no process was launched. For example, if a document to be launched is a URL and an instance of Internet Explorer is already running, it will display the document. No new process is launched, and hProcess will be NULL.