IAssocHandler::CreateInvoker method (shobjidl_core.h)
Retrieves an object that enables the invocation of the associated handler on the current selection. The invoker includes the ability to verify whether the current selection is supported.
Syntax
HRESULT CreateInvoker(
[in] IDataObject *pdo,
[out] IAssocHandlerInvoker **ppInvoker
);
Parameters
[in] pdo
Type: IDataObject*
A pointer to an IDataObject that represents the selected item or items on which to invoke the handler. Note that if you have only a single item, IAssocHandler::Invoke could be the better choice. See Remarks for more details.
[out] ppInvoker
Type: IAssocHandlerInvoker**
When this method returns, contains the address of a pointer to an IAssocHandlerInvoker object. This object is used to invoke the menu item after ensuring that the selected items are supported by the associated handler.
Return value
Type: HRESULT
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
IAssocHandler objects are typically used to populate an Open With menu. When one of those menu items is selected, this method is called to launch the chosen application.
Invoke and CreateInvoker
The IDataObject used by these methods can represent either a single file or it may represent a selection of multiple files. Not all applications support the multiple files option. Those applications that do support that scenario might impose other restrictions such as the number of files that can be opened at once, or acceptable combinations of file types.Therefore, an application often must determine whether the handler supports the selection before trying to invoke the handler. For example, an application might enable a menu item only if it knew that the selection in question was supported by that handler.
It is generally safe to assume that an application will support invocation on a single item; in those cases the application typically calls IAssocHandler::Invoke.
For multiple selection scenarios, the application should call IAssocHandler::CreateInvoker. That method retrieves an IAssocHandlerInvoker object that allows the calling application to first check whether the selection is supported (SupportsSelection), then to invoke the handler (Invoke).
IAssocHandler::Invoke can be called on a selection of multiple files, but it is not recommended due to the large processing load involved and no guarantee of success.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | shobjidl_core.h (include Shobjidl.h) |