{"id":14623,"date":"2010-03-12T07:00:01","date_gmt":"2010-03-12T07:00:01","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2010\/03\/12\/simplifying-context-menu-extensions-with-iexecutecommand\/"},"modified":"2010-03-12T07:00:01","modified_gmt":"2010-03-12T07:00:01","slug":"simplifying-context-menu-extensions-with-iexecutecommand","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20100312-01\/?p=14623","title":{"rendered":"Simplifying context menu extensions with IExecuteCommand"},"content":{"rendered":"

\nThe IExecuteCommand<\/code> interface is a simpler form of\ncontext menu extension which takes care of the annoying parts of\nIContextMenu<\/code> so you can focus on your area of expertise,\nnamely, doing the actual thing the user selected,\nand leave the shell to doing the grunt work of managing the UI part.\n<\/p>\n

\nI’ve never needed a scratch shell extension before, so I guess\nit’s time to create one.\nThis part is completely boring, and those of you who have written\nCOM inproc servers can skip over it.\n<\/p>\n

\n#include <windows.h>\n#include <new>\nLONG g_cObjs;\nvoid DllAddRef() { InterlockedIncrement(&g_cObjs); }\nvoid DllRelease() { InterlockedDecrement(&g_cObjs); }\n\/\/ guts of shell extension go in here eventually\nclass CFactory : public IClassFactory\n{\npublic:\n \/\/ *** IUnknown ***\n STDMETHODIMP QueryInterface(REFIID riid, void **ppv);\n STDMETHODIMP_(ULONG) AddRef() { return 2; }\n STDMETHODIMP_(ULONG) Release() { return 1; }\n \/\/ *** IClassFactory ***\n STDMETHODIMP CreateInstance(IUnknown *punkOuter,\n                             REFIID riid, void **ppv);\n STDMETHODIMP LockServer(BOOL fLock);\n};\nCFactory c_Factory;\nSTDMETHODIMP CFactory::QueryInterface(REFIID riid, void **ppv)\n{\n IUnknown *punk = NULL;\n if (riid == IID_IUnknown || riid == IID_IClassFactory) {\n  punk = static_cast<IClassFactory*>(this);\n }\n *ppv = punk;\n if (punk) {\n  punk->AddRef();\n  return S_OK;\n } else {\n  return E_NOINTERFACE;\n }\n}\nSTDMETHODIMP CFactory::CreateInstance(\n IUnknown *punkOuter, REFIID riid, void **ppv)\n{\n *ppv = NULL;\n if (punkOuter) return CLASS_E_NOAGGREGATION;\n CShellExtension *pse = new(std::nothrow) CShellExtension();\n if (!pse) return E_OUTOFMEMORY;\n HRESULT hr = pse->QueryInterface(riid, ppv);\n pse->Release();\n return hr;\n}\nSTDMETHODIMP CFactory::LockServer(BOOL fLock)\n{\n if (fLock) DllAddRef();\n else       DllRelease();\n return S_OK;\n}\nSTDAPI DllGetClassObject(REFCLSID rclsid,\n                         REFIID riid, void **ppv)\n{\n if (rclsid == CLSID_ShellExtension) {\n  return c_Factory.QueryInterface(riid, ppv);\n }\n *ppv = NULL;\n return CLASS_E_CLASSNOTAVAILABLE;\n}\nSTDAPI DllCanUnloadNow()\n{\n return g_cObjs ? S_OK : S_FALSE;\n}\n<\/pre>\n
\nI’m assuming that the above code is all old hat.\nConsider it a prerequisite.\n<\/p>\n
\nOkay, now the good stuff.\n<\/p>\n
\nThe IExecuteCommand<\/code> interface is used when you\ncreate a static registration for a shell verb but\n\nspecify DelegateExecute<\/code> in the command<\/a>.\nOur sample shell extension will be active on text files,\nand all it’ll do is print the file names to the debugger.\n<\/p>\n
\nSince we’re a COM server, we need to register our CLSID.\nThis should also be very familiar to you.\n<\/p>\n
\n[HKEY_CLASSES_ROOT\\CLSID\\{guid<\/font>}\\InProcServer32]\n@=\"C:\\path\\to\\scratch.dll<\/font>\"\n\"ThreadingModel\"=\"Apartment\"\n<\/pre>\n
\nHere’s where we register our object as a verb for text files,\nspecifying that it should be invoked via DelegateExecute<\/code>:\n<\/p>\n
\n[HKEY_CLASSES_ROOT\\txtfile\\shell\\printnamestodebugger]\n@=\"Print names to debugger\"\n[HKEY_CLASSES_ROOT\\txtfile\\shell\\printnamestodebugger\\command]\n\"DelegateExecute\"=\"{guid<\/font>}\"\n<\/pre>\n
\nThat was the easy part. Now to roll up our sleeves and write\nthe shell extension.\n<\/p>\n
\n#include <shobjidl.h>\nCLSID CLSID_ShellExtension = { ...guid...<\/font> };\nclass CShellExtension\n : public IExecuteCommand\n , public IInitializeCommand\n , public IObjectWithSelection\n{\npublic:\n CShellExtension();\n \/\/ *** IUnknown ***\n STDMETHODIMP QueryInterface(REFIID riid, void **ppv);\n STDMETHODIMP_(ULONG) AddRef();\n STDMETHODIMP_(ULONG) Release();\n \/\/ *** IInitializeCommand ***\n STDMETHODIMP Initialize(PCWSTR pszCommandName, IPropertyBag *ppb);\n \/\/ *** IObjectWithSelection ***\n STDMETHODIMP SetSelection(IShellItemArray *psia);\n STDMETHODIMP GetSelection(REFIID riid, void **ppv);\n \/\/ *** IExecuteCommand ***\n STDMETHODIMP SetKeyState(DWORD grfKeyState) { return S_OK; }\n STDMETHODIMP SetParameters(LPCWSTR pszParameters) { return S_OK; }\n STDMETHODIMP SetPosition(POINT pt) { return S_OK; }\n STDMETHODIMP SetShowWindow(int nShow) { return S_OK; }\n STDMETHODIMP SetNoShowUI(BOOL fNoShowUI) { return S_OK; }\n STDMETHODIMP SetDirectory(LPCWSTR pszDirectory) { return S_OK; }\n STDMETHODIMP Execute();\nprivate:\n ~CShellExtension();\nprivate:\n LONG m_cRef;\n IShellItemArray *m_psia;\n};\nCShellExtension::CShellExtension()\n : m_cRef(1), m_psia(NULL)\n{\n DllAddRef();\n}\nCShellExtension::~CShellExtension()\n{\n if (m_psia) m_psia->Release();\n DllRelease();\n}\n<\/pre>\n
\nI’ve written this all out longhand; I’m trusting that you’re\nusing some sort of framework (like, say, ATL) which avoids all\nthis tedium, but since different people may choose different frameworks,\nI won’t choose a framework here.\nInstead, we just have the boring IUnknown<\/code> methods.\n<\/p>\n
\nSTDMETHODIMP CShellExtension::QueryInterface(\n REFIID riid, void **ppv)\n{\n IUnknown *punk = NULL;\n if (riid == IID_IUnknown || riid == IID_IExecuteCommand) {\n  punk = static_cast<IExecuteCommand*>(this);\n } else if (riid == IID_IInitializeCommand) {\n  punk = static_cast<IInitializeCommand*>(this);\n } else if (riid == IID_IObjectWithSelection) {\n  punk = static_cast<IObjectWithSelection*>(this);\n }\n *ppv = punk;\n if (punk) {\n  punk->AddRef();\n  return S_OK;\n } else {\n  return E_NOINTERFACE;\n }\n}\nSTDMETHODIMP_(ULONG) CShellExtension::AddRef()\n{\n return ++m_cRef;\n}\nSTDMETHODIMP_(ULONG) CShellExtension::Release()\n{\n ULONG cRef = --m_cRef;\n if (cRef == 0) delete this;\n return cRef;\n}\n<\/pre>\n
\nWhew.\nUp until now, it’s just been boring typing that you have to do\nfor any shell extension.\nFinally we can start doing something interesting.\nWindows 7 will initialize your shell extension with information\nabout the command being executed.\nFor this particular shell extension, we’ll just print the command\nname to the debugger to prove that something happened.\n(In real life, you might use the same CShellExtension<\/code>\nto handle multiple commands, and this lets you determine which\ncommand you’re being asked to execute.)\n<\/p>\n
\nSTDMETHODIMP CShellExtension::Initialize(\n PCWSTR pszCommandName,\n IPropertyBag *ppb)\n{\n OutputDebugStringW(L\"Command: \");\n OutputDebugStringW(pszCommandName);\n OutputDebugStringW(L\"\\r\\n\");\n return S_OK;\n}\n<\/pre>\n
\nThe shell will give you the items on which to execute in the form\nof an IShellItemArray<\/code>:\n<\/p>\n
\nSTDMETHODIMP CShellExtension::SetSelection(IShellItemArray *psia)\n{\n if (psia) psia->AddRef()<\/a>;\n if (m_psia) m_psia->Release();\n m_psia = psia;\n return S_OK;\n}\nSTDMETHODIMP CShellExtension::GetSelection(\n REFIID riid, void **ppv)\n{\n if (m_psia) return m_psia->QueryInterface(riid, ppv);\n *ppv = NULL;\n return E_NOINTERFACE;\n}\n<\/pre>\n
\nThe shell will then call a bunch of IExecuteCommand::SetThis<\/code>\nand\nIExecuteCommand::SetThat<\/code> methods to inform you of the\nenvironment in which you have been asked to execute.\nWe just ignored them all for simplicity, but in practice,\nyou may want to pay attention to some of them, particularly\nIExecuteCommand::SetPosition<\/code>,\nIExecuteCommand::SetShowWindow<\/code>, and\nIExecuteCommand::SetNoShowUI<\/code>.\n<\/p>\n
\nAfter all the IExecuteCommand::SetXxx<\/code> methods have been called,\nit’s show time:\n<\/p>\n
\nSTDMETHODIMP CShellExtension::Execute()\n{\n HRESULT hr;\n if (m_psia) {\n  IEnumShellItems *pesi;\n  if (SUCCEEDED(hr = m_psia->EnumItems(&pesi))) {\n   IShellItem *psi;\n   while (pesi->Next(1, &psi, NULL) == S_OK) {\n    LPWSTR pszName;\n    if (SUCCEEDED(psi->GetDisplayName(SIGDN_FILESYSPATH,\n                                      &pszName))) {\n     OutputDebugStringW(L\"File: \");\n     OutputDebugStringW(pszName);\n     OutputDebugStringW(L\"\\r\\n\");\n     CoTaskMemFree(pszName);\n    }\n    psi->Release();\n   }\n   pesi->Release();\n   hr = S_OK;\n  }\n } else {\n  hr = E_UNEXPECTED;\n }\n return hr;\n}\n<\/pre>\n
\nAll we do is enumerate the contents of the IShellItemArray<\/code>\nand print their file names (if they have one).\nInstead of IEnumShellItems<\/code>, you can use\nIShellItemArray::GetCount<\/code> and\nIShellItemArray::GetItemAt<\/code>.\nOr, if you are porting an existing context menu that uses\nIDataObject<\/code>,\nyou can call IShellItemArray::BindToHandler(BHID_DataObject)<\/code>\nto turn your IShellItemArray<\/code> into an IDataObject<\/code>.\n<\/p>\n
\nInstall this shell extension, right-click on a text file (or\na bunch of text files), and select\nPrint names to debugger<\/i>.\nIf all goes well, the debugger will report\nCommand: printnamestodebugger<\/code>\nfollowed by paths of the files you selected.\n<\/p>\n
\nBut wait, there’s more.\nThe IPropertyBag<\/code> passed to\nIInitializeCommand::Initialize<\/code>\ncontains additional configuration options taken from the\nregistry.\nYou can use this to customize the behavior of the shell extension further.\n\nPut the bonus information under the command key<\/a>\nlike this:\n<\/p>\n
\n[HKEY_CLASSES_ROOT\\txtfile\\shell\\printnamestodebugger]\n\"extra\"=\"Special\"\n<\/pre>\n
\nSTDMETHODIMP CShellExtension::Initialize(\n PCWSTR pszCommandName,\n IPropertyBag *ppb)\n{\n OutputDebugStringW(L\"Command: \");\n OutputDebugStringW(pszCommandName);\n OutputDebugStringW(L\"\\r\\n\");\n if (ppb) {\n  VARIANT vt;\n  VariantInit(&vt);\n  if (SUCCEEDED(ppb->Read(L\"extra\", &vt, NULL))) {\n   if (SUCCEEDED(VariantChangeType(&vt, &vt, 0, VT_BSTR))) {\n    OutputDebugStringW(L\"extra: \");\n    OutputDebugStringW(vt.bstrVal);\n    OutputDebugStringW(L\"\\r\\n\");\n   }\n   VariantClear(&vt);\n  }\n }<\/font>\n return S_OK;\n}\n<\/pre>\n
\nThis updated version of CShellExtension<\/code> looks for\nthat registry value extra<\/code> we set above\nand if found prints its value to the debugger.\n<\/p>\n
\nOkay, so it looks like a lot of typing, but most of that was\ntyping you have to do for any shell extension.\nThe part that is specific to IExecuteCommand<\/code> is not\nthat bad,\nand it certainly avoids having to mess with\nIContextMenu::QueryContextMenu<\/code>\nand the fifty bajillion variations on\nIContextMenu::InvokeCommand<\/code>.\nFurthermore,\nthe shell doesn’t even load your IExecuteCommand<\/code> handler\nuntil the user selects your command,\nso switching to a static registration also gives the system a bit of a\nperformance boost.\n<\/p>\n
\nBonus tip<\/b>:\nYou can combine the IExecuteCommand<\/code> technique with\n\nGetting Dynamic Behavior for Static Verbs by Using Advanced Query Syntax<\/i>\n<\/a>\nand\n\nUsing Item Attributes<\/i><\/a>\nto specify the conditions under which you want your verb to appear\nwithout having to write a single line of C++ code.\n\nChoosing a Static or Dynamic Shortcut Menu Method<\/a>\nprovides additional guidance on choosing among the various methods\nfor registering verbs.\n<\/p>\n
\nOne nice thing about IExecuteCommand<\/code> is that it supports\nout-of-proc activation (i.e., local server rather than in-proc server).\nThis means that it supports cross-bitness shell extensions:\nIf you don’t have the time to port your 32-bit shell extension to 64-bit,\nyou can register it as an out-of-proc IExecuteCommand<\/code>.\nWhen running on 64-bit Windows,\nthe 64-bit Explorer will launch your 32-bit server to handle the command.\nConversely, if your IExecuteCommand<\/code> is a 64-bit local server,\na 32-bit application can still invoke it.\n<\/p>\n
\n(We’ll see more about local server shell extensions in a few months.\nThis was just foreshadowing.)<\/p>\n","protected":false},"excerpt":{"rendered":"
The IExecuteCommand interface is a simpler form of context menu extension which takes care of the annoying parts of IContextMenu so you can focus on your area of expertise, namely, doing the actual thing the user selected, and leave the shell to doing the grunt work of managing the UI part. I’ve never needed a […]<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-14623","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
The IExecuteCommand interface is a simpler form of context menu extension which takes care of the annoying parts of IContextMenu so you can focus on your area of expertise, namely, doing the actual thing the user selected, and leave the shell to doing the grunt work of managing the UI part. I’ve never needed a […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/14623","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=14623"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/14623\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=14623"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=14623"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=14623"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}