CMINVOKECOMMANDINFOEX structure (shobjidl_core.h)

Contains extended information about a shortcut menu command. This structure is an extended version of CMINVOKECOMMANDINFO that allows the use of Unicode values.

Syntax

typedef struct _CMINVOKECOMMANDINFOEX {
  DWORD   cbSize;
  DWORD   fMask;
  HWND    hwnd;
  LPCSTR  lpVerb;
  LPCSTR  lpParameters;
  LPCSTR  lpDirectory;
  int     nShow;
  DWORD   dwHotKey;
  HANDLE  hIcon;
  LPCSTR  lpTitle;
  LPCWSTR lpVerbW;
  LPCWSTR lpParametersW;
  LPCWSTR lpDirectoryW;
  LPCWSTR lpTitleW;
  POINT   ptInvoke;
} CMINVOKECOMMANDINFOEX;

Members

cbSize

Type: DWORD

The size of this structure, in bytes. This member should be filled in by callers of IContextMenu::InvokeCommand and tested by the implementations to know that the structure is a CMINVOKECOMMANDINFOEX structure rather than CMINVOKECOMMANDINFO.

fMask

Type: DWORD

Zero, or one or more of the following flags are set to indicate desired behavior and indicate that other fields in the structure are to be used.

CMIC_MASK_HOTKEY

The dwHotKey member is valid.

CMIC_MASK_ICON

The hIcon member is valid. As of Windows Vista this flag is not used.

CMIC_MASK_FLAG_NO_UI

The implementation of IContextMenu::InvokeCommand is prevented from displaying user interface elements (for example, error messages) while carrying out a command.

CMIC_MASK_UNICODE

The shortcut menu handler should use lpVerbW, lpParametersW, lpDirectoryW, and lpTitleW members instead of their ANSI equivalents. Because some shortcut menu handlers may not support Unicode, you should also pass valid ANSI strings in the lpVerb, lpParameters, lpDirectory, and lpTitle members.

CMIC_MASK_NO_CONSOLE

If a shortcut menu handler needs to create a new process, it will normally create a new console. Setting the CMIC_MASK_NO_CONSOLE flag suppresses the creation of a new console.

CMIC_MASK_HASLINKNAME

The lpTitle member contains a full path to a shortcut file. Use in conjunction with CMIC_MASK_HASTITLE.

Note  This value is not supported in Windows Vista and later systems.
 

CMIC_MASK_HASTITLE

The lpTitle member is valid.

Note  This value is not supported in Windows Vista and later systems.
 

CMIC_MASK_FLAG_SEP_VDM

This flag is valid only when referring to a 16-bit Windows-based application. If set, the application that the shortcut points to runs in a private Virtual DOS Machine (VDM). See Remarks.

CMIC_MASK_ASYNCOK

The implementation of IContextMenu::InvokeCommand can spin off a new thread or process to handle the call and does not need to block on completion of the function being invoked. For example, if the verb is "delete" the IContextMenu::InvokeCommand call may return before all of the items have been deleted. Since this is advisory, calling applications that specify this flag cannot guarantee that this request will be honored if they are not familiar with the implementation of the verb that they are invoking.

CMIC_MASK_NOASYNC

Windows Vista and later. The implementation of IContextMenu::InvokeCommand should be synchronous, not returning before it is complete. Since this is recommended, calling applications that specify this flag cannot guarantee that this request will be honored if they are not familiar with the implementation of the verb that they are invoking.

CMIC_MASK_SHIFT_DOWN

The SHIFT key is pressed. Use this instead of polling the current state of the keyboard that may have changed since the verb was invoked.

CMIC_MASK_CONTROL_DOWN

The CTRL key is pressed. Use this instead of polling the current state of the keyboard that may have changed since the verb was invoked.

CMIC_MASK_FLAG_LOG_USAGE

Indicates that the implementation of IContextMenu::InvokeCommand might want to keep track of the item being invoked for features like the "Recent documents" menu.

CMIC_MASK_NOZONECHECKS

Do not perform a zone check. This flag allows ShellExecuteEx to bypass zone checking put into place by IAttachmentExecute.

CMIC_MASK_PTINVOKE

The ptInvoke member is valid.

hwnd

Type: HWND

A handle to the window that is the owner of the shortcut menu. An extension can also use this handle as the owner of any message boxes or dialog boxes it displays. Callers must specify a legitimate HWND that can be used as the owner window for any UI that may be displayed. Failing to specify an HWND when calling from a UI thread (one with windows already created) will result in reentrancy and possible bugs in the implementation of a IContextMenu::InvokeCommand call.

lpVerb

Type: LPCSTR

The address of a null-terminated string that specifies the language-independent name of the command to carry out. This member is typically a string when a command is being activated by an application. The system provides predefined constant values for the following command strings.

Constant Command string
CMDSTR_RUNAS "RunAs"
CMDSTR_PRINT "Print"
CMDSTR_PREVIEW "Preview"
CMDSTR_OPEN "Open"
 

This is not a fixed set; new canonical verbs can be invented by context menu handlers and applications can invoke them.

If a canonical verb exists and a menu handler does not implement the canonical verb, it must return a failure code to enable the next handler to be able to handle this verb. Failing to do this will break functionality in the system including ShellExecute.

Alternatively, rather than a pointer, this parameter can be MAKEINTRESOURCE(offset) where offset is the menu-identifier offset of the command to carry out. Implementations can use the IS_INTRESOURCE macro to detect that this alternative is being employed. The Shell uses this alternative when the user chooses a menu command.

lpParameters

Type: LPCSTR

Optional parameters. This member is always NULL for menu items inserted by a Shell extension.

lpDirectory

Type: LPCSTR

An optional working directory name. This member is always NULL for menu items inserted by a Shell extension.

nShow

Type: int

A set of SW_ values to pass to the ShowWindow function if the command displays a window or starts an application.

dwHotKey

Type: DWORD

An optional keyboard shortcut to assign to any application activated by the command. If the fMask member does not specify CMIC_MASK_HOTKEY, this member is ignored.

hIcon

Type: HANDLE

An icon to use for any application activated by the command. If the fMask member does not specify CMIC_MASK_ICON, this member is ignored.

lpTitle

Type: LPCSTR

An ASCII title.

lpVerbW

Type: LPCWSTR

A Unicode verb, for those commands that can use it.

lpParametersW

Type: LPCWSTR

A Unicode parameters, for those commands that can use it.

lpDirectoryW

Type: LPCWSTR

A Unicode directory, for those commands that can use it.

lpTitleW

Type: LPCWSTR

A Unicode title.

ptInvoke

Type: POINT

The point where the command is invoked. If the fMask member does not specify CMIC_MASK_PTINVOKE, this member is ignored. This member is not valid prior to Internet Explorer 4.0.

Remarks

Although the IContextMenu::InvokeCommand declaration specifies a CMINVOKECOMMANDINFO structure for the pici parameter, it can also accept a CMINVOKECOMMANDINFOEX structure. If you are implementing this method, you must inspect cbSize to determine which structure has been passed.

By default, all 16-bit Windows-based applications run as threads in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that are run in separate VDMs have separate input queues. That means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. The disadvantage of running separately is that it takes significantly more memory to do so.

CMINVOKECOMMANDINFOEX itself is defined in Shobjidl.h, but you must also include Shellapi.h to have full access to all flags.

Note  Prior to Windows Vista, this structure was declared in Shlobj.h.
 

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Header shobjidl_core.h (include Shobjidl.h)