{"id":44773,"date":"2015-02-02T07:00:00","date_gmt":"2015-02-02T22:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2015\/02\/02\/customizing-item-enumeration-with-ishellitem-the-old-fashioned-way\/"},"modified":"2019-03-13T12:12:31","modified_gmt":"2019-03-13T19:12:31","slug":"20150202-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20150202-00\/?p=44773","title":{"rendered":"Customizing item enumeration with IShellItem, the old-fashioned way"},"content":{"rendered":"

If you are targeting Windows 8 or higher, you can use STR_ENUM_ITEMS_FLAGS<\/code><\/a> to customize how shell items are enumerated. But what if you need to run on older systems, too? <\/p>\n

In that case, you will need to drop to the lower-level IShell­Folder::Enum­Objects<\/code> function, like we did before<\/a>, and then reconstructe shell items from the low-level IShell­Folder<\/code> and ITEMID_CHILD<\/code>. (Note that the term “low-level” is used here only in a relative sense; it’s lower level than IShell­Item<\/code>.) <\/p>\n

We can wrap that inside a helper class. <\/p>\n

\n#define UNICODE\n#define _UNICODE<\/a>\n#define STRICT\n#define STRICT_TYPED_ITEMIDS<\/a>\n#include <windows.h>\n#include <shlobj.h>\n#include <atlbase.h>\nCComModule _Module;\n#include <atlcom.h>\n#include <atlalloc.h>\n#include <stdio.h>\n#include <tchar.h>\n\nclass CEnumItemsWithSHCONTF :\n    public CComObjectRoot,\n    public IEnumShellItems\n{\npublic:\n  BEGIN_COM_MAP(CEnumItemsWithSHCONTF)\n    COM_INTERFACE_ENTRY(IEnumShellItems)\n  END_COM_MAP()\n\n  static HRESULT Create(HWND hwnd, SHCONTF shcontf,\n                 IShellItem *psiFolder, REFIID riid, void **ppv);\n\n  STDMETHOD(Next)(ULONG celt, IShellItem **ppsi, ULONG *pceltFetched);\n  STDMETHOD(Skip)(ULONG celt);\n  STDMETHOD(Reset)();\n  STDMETHOD(Clone)(IEnumShellItems **ppesiClone);\n\nprivate:\n  static HRESULT CreateRef1(CComObject<CEnumItemsWithSHCONTF> **ppObj);\n  HRESULT Initialize(HWND hwnd, SHCONTF shcontf, IShellItem *psiFolder);\n  HRESULT CloneFrom(CEnumItemsWithSHCONTF *pSource);\nprivate:\n  CComPtr<IShellFolder> m_spsfParent;\n  CComPtr<IEnumIDList> m_speidl;\n};\n\nHRESULT CEnumItemsWithSHCONTF::CreateRef1(\n    CComObject<CEnumItemsWithSHCONTF> **ppObj)\n{\n  CComObject<CEnumItemsWithSHCONTF> *pObj;\n  HRESULT hr = CComObject<CEnumItemsWithSHCONTF>::\n                       CreateInstance(&pObj);\n  *ppObj = CComPtr<CComObject<CEnumItemsWithSHCONTF> >(pObj).Detach();\n  return hr;\n}\n\nHRESULT CEnumItemsWithSHCONTF::Initialize(\n  HWND hwnd, SHCONTF shcontf, IShellItem *psiFolder)\n{\n  HRESULT hr = psiFolder->BindToHandler(\n    nullptr, BHID_SFObject, IID_PPV_ARGS(&m_spsfParent));\n  if (SUCCEEDED(hr)) {\n    hr = m_spsfParent->EnumObjects(hwnd, shcontf, &m_speidl);\n  }\n  return hr;\n}\n\nHRESULT CEnumItemsWithSHCONTF::CloneFrom(\n    CEnumItemsWithSHCONTF *pSource)\n{\n  HRESULT hr = pSource->m_speidl->Clone(&m_speidl);\n  if (SUCCEEDED(hr)) {\n    m_spsfParent = pSource->m_spsfParent;\n  }\n  return hr;\n}\n\nHRESULT CEnumItemsWithSHCONTF::Create(\n    HWND hwnd, SHCONTF shcontf,\n    IShellItem *psiFolder, REFIID riid, void **ppv)\n{\n  *ppv = nullptr;\n\n  CComPtr<CComObject<CEnumItemsWithSHCONTF>> spObj;\n  HRESULT hr = CreateRef1(&spObj);\n\n  if (SUCCEEDED(hr)) {\n    hr = spObj->Initialize(hwnd, shcontf, psiFolder);\n    if (SUCCEEDED(hr)) {\n      hr = spObj->QueryInterface(riid, ppv);\n    }\n  }\n  return hr;\n}\n\nHRESULT CEnumItemsWithSHCONTF::Next(\n    ULONG celt, IShellItem **ppsi, ULONG *pceltFetched)\n{\n  if (celt != 1 && pceltFetched == nullptr) {\n    return E_INVALIDARG;\n  }\n\n  for (ULONG i = 0; i < celt; i++) ppsi[i] = nullptr;\n\n  ULONG celtFetched = 0;\n  HRESULT hr = S_OK;\n  while (hr == S_OK && celtFetched < celt) {\n    CComHeapPtr<ITEMID_CHILD> spidlChild;\n    hr = m_speidl->Next(1, &spidlChild, nullptr);\n    if (hr == S_OK) {\n      hr = SHCreateItemWithParent(nullptr, m_spsfParent,\n        spidlChild, IID_PPV_ARGS(&ppsi[celtFetched]));\n      if (SUCCEEDED(hr)) celtFetched++;\n    }\n  }\n\n  if (pceltFetched != nullptr) *pceltFetched = celtFetched;\n  if (SUCCEEDED(hr)) {\n    hr = (celtFetched == celt) ? S_OK : S_FALSE;\n  }\n  return hr;\n}\n\nHRESULT CEnumItemsWithSHCONTF::Skip(ULONG celt)\n{\n  return m_speidl->Skip(celt);\n}\n\nHRESULT CEnumItemsWithSHCONTF::Reset()\n{\n  return m_speidl->Reset();\n}\n\nHRESULT CEnumItemsWithSHCONTF::Clone(\n    IEnumShellItems **ppesiClone)\n{\n  *ppesiClone = nullptr;\n\n  CComPtr<CComObject<CEnumItemsWithSHCONTF>> spClone;\n  HRESULT hr = CreateRef1(&spClone);\n\n  if (SUCCEEDED(hr)) {\n    hr = spClone->CloneFrom(this);\n    if (SUCCEEDED(hr)) {\n        *ppesiClone = spClone.Detach();\n    }\n  }\n  return hr;\n}\n<\/pre>\n
The CEnum­Items­With­SHCONTF<\/code> class does the work of enumerating child items the old-fashioned way, then constructing shell items from the result. Most of this code is boilerplate (including the part to avoid having a live COM object with reference count zero<\/a>). <\/p>\n
The object has two members, the source folder from which the items are being enumerated and the low-level enumerator itself. We initialize the object by asking for the low-level IEnum­ID­List<\/code> handler and calling IEnum­ID­List::Enum­Objects<\/code> with the specific flags we want. When it is time to generate items, we ask the inner enumerator for the next ID list, and construct a shell item around it by comining the ID list with the parent folder. <\/p>\n
The rest is bookkeeping: We keep track of the number of elements fetched so far in order to return it to the caller if requested, and also in order to decide what the return value should be. If all items were retrieved successfully, then return S_OK<\/code>. If we ran out of items, then return S_FALSE<\/code>. If something went wrong, we return the error code, possibly with partially-fetched results. <\/p>\n
The other enumerator operations like Reset<\/code> and Clone<\/code> are delegated to the inner enumerator. Cloning is a little tricky because we also have to clone ourselves! <\/p>\n
Now we can adapt our program from last time<\/a> to use this class instead of BHID_Enum­Items<\/code>. <\/p>\n
\nint __cdecl wmain(int argc, wchar_t **argv)\n{\n CCoInitialize<\/a> init;\n\n if (argc < 2) return 0;\n CComPtr<IShellItem> spsiFolder;\n SHCreateItemFromParsingName(argv[1], nullptr,\n                             IID_PPV_ARGS(&spsiFolder));\n\n CComPtr<IEnumShellItems> spesi;\n CEnumItemsWithSHCONTF::Create(nullptr, SHCONTF_FOLDERS,\n    spsiFolder, IID_PPV_ARGS(&spesi));<\/font>\n for (CComPtr<IShellItem> spsi;\n      spesi->Next(1, &spsi, nullptr) == S_OK;\n      spsi.Release()) {\n  PrintDisplayName<\/a>(spsi, SIGDN_NORMALDISPLAY, L\"Display Name\");\n  PrintDisplayName(spsi, SIGDN_FILESYSPATH, L\"File system path\");\n  wprintf(L\"\\n\");\n }\n return 0;\n}\n<\/pre>\n","protected":false},"excerpt":{"rendered":"
Driving it manually.<\/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-44773","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Driving it manually.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44773","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=44773"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44773\/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=44773"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=44773"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=44773"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}