The Old New Thing

Microspeak: to family well

Raymond Chen - MSFT — Tue, 18 Jun 2013 14:00:00 GMT

If you hang out with designers, you may hear the word family used as a verb, usually with the adverb well.

The old icons now look dated and do not family well with the Web site.

We renamed the feature from Auto Shape to Instant Shape so that it families well with other features like Instant Color.

The authenticity certificate on the side of the box should family well with the design on the front of the box.

From context, it appears that to family well basically means to be harmonious or consistent with.

I wonder if the Queen of England ever pulls this sort of prank in real life

Raymond Chen - MSFT — Mon, 17 Jun 2013 14:00:01 GMT

I dreamed that I was playing doubles tennis. My partner was Boris Becker. Our opponents were the Queen of England and a policeman on a horse. The horse served his horseshoe, which I returned poorly. As the horseshoe bounced across the ground, it made huge divots. The game was called due to poor ground conditions.

The Queen played a game with the crowd by pretending to sit down (allowing everybody to sit), then faking them out and standing (making everybody stand up again).

Displaying a property sheet for multiple files

Raymond Chen - MSFT — Mon, 17 Jun 2013 14:00:00 GMT

Today's Little Program will show a property sheet that covers multiple files, just like the one you get from Explorer if you multi-select a bunch of files and right-click them all then select Properties.

In fact, that description of how you do the operation interactively maps directly to how you do the operation programmatically!

#define UNICODE
#define _UNICODE
#define STRICT_TYPED_ITEMIDS
#include <windows.h>
#include <ole2.h>
#include <shlobj.h>
#include <atlbase.h>
#include <atlalloc.h>

HRESULT GetUIObjectOf(
    IShellFolder *psf,
    HWND hwndOwner,
    UINT cidl,
    PCUITEMID_CHILD_ARRAY apidl, REFIID riid, void **ppv)
{
 return psf->GetUIObjectOf(hwndOwner, cidl, apidl, riid, nullptr, ppv);
}

The GetUIObjectOf helper function merely wraps the IShellFolder::GetUIObjectOf method to insert the pesky nullptr parameter between the riid and ppv. The riid and ppv parameters by convention go right next to each other, and the IID_PPV_ARGS macro assumes that the function you're calling follows that convention. Unfortunately, the people who designed IShellFolder::GetUIObjectOf didn't get the memo, and we've been stuck with it ever since.

HRESULT InvokeCommandByVerb(
    IContextMenu *pcm,
    HWND hwnd,
    LPCSTR pszVerb)
{
 HMENU hmenu = CreatePopupMenu();
 HRESULT hr = hmenu ? S_OK : E_OUTOFMEMORY;
 if (SUCCEEDED(hr)) {
  hr = pcm->QueryContextMenu(hmenu, 0, 1, 0x7FFF, CMF_NORMAL);
  if (SUCCEEDED(hr)) {
   CMINVOKECOMMANDINFO info = { 0 };
   info.cbSize = sizeof(info);
   info.hwnd = hwnd;
   info.lpVerb = pszVerb;
   hr = pcm->InvokeCommand(&info);
  }
  DestroyMenu(hmenu);
 }
 return hr;
}

The InvokeCommandByVerb function merely hosts an IContextMenu and invokes a single verb.

Okay, those are the only two helper functions we need this week. The rest we can steal from earlier articles.

For the purpose of illustration, the program will display a multi-file property sheet for the first two files in your My Documents folder folder. Remember, Little Programs do little to no error checking.

int __cdecl wmain(int, wchar_t **)
{
 CCoInitialize init;
 ProcessReference ref;
 CComPtr<IShellFolder> spsf;
 BindToCsidl(CSIDL_MYDOCUMENTS, IID_PPV_ARGS(&spsf));
 CComPtr<IEnumIDList> speidl;
 spsf->EnumObjects(nullptr, SHCONTF_NONFOLDERS, &speidl);
 if (!speidl) return 0;
 CComHeapPtr<ITEMID_CHILD> spidl1;
 CComHeapPtr<ITEMID_CHILD> spidl2;
 if (speidl->Next(1, &spidl1, nullptr) != S_OK) return 0;
 if (speidl->Next(1, &spidl2, nullptr) != S_OK) return 0;
 PCUITEMID_CHILD rgpidl[2] = { spidl1, spidl2 };
 CComPtr<IContextMenu> spcm;
 GetUIObjectOf(spsf, nullptr, 2, rgpidl, IID_PPV_ARGS(&spcm));
 if (!spcm) return 0;
 InvokeCommandByVerb(spcm, "properties");
 return 0;
}

Because everybody freaks out if I write code that doesn't run on Windows XP, I used the BindToCSIDL function instead of one of its more modern equivalents to get access to the My Documents folder.

Once we have My Documents, we ask to enumerate its non-folders. If the enumeration fails or says that there are no items (by returning S_FALSE), then we bail immediately.

Next, we enumerate two items from the folder. If we can't get both, then we bail.

We then create a two-item array and get the IContextMenu UI object for the collection.

Finally, we invoke the "properties" verb on the context menu.

And that's it. If you run this program, you'll see a context menu for the first two files in your My Documents folder.

A big little program: Monitoring Internet Explorer and Explorer windows, part 3: Tracking creation and destruction

Raymond Chen - MSFT — Fri, 14 Jun 2013 14:00:00 GMT

Last time, we listener for window navigations. Today we'll learn about tracking window creation and destruction.

The events to listen to are the DShellWindowsEvents. The WindowRegistered event fires when a new window is created, and the WindowRevoked event fires when a window is destroyed.

The bad news is that the parameter to those events is a cookie, which is not useful for much, so we just use the events to tell us that it's time to kick off a new enumeration to see what changed. This will also catch the case where something fell out of sync because a window closed without unregistering (say, because the application crashed).

Take our program from last time and make these changes:

LONG g_lCounter;

struct ItemInfo
{
 ItemInfo(HWND hwnd, IDispatch *pdisp)
  : hwnd(hwnd), lCounter(g_lCounter) { ... }
 ...

 HWND hwnd;
 CComPtr<CWebBrowserEventsSink> spSink;
 LONG lCounter;
};

The counter is used to detect stale windows when we re-enumerate.

HRESULT BuildWindowList()
{
 CComPtr<IUnknown> spunkEnum;
 HRESULT hr = g_spWindows->_NewEnum(&spunkEnum);
 if (FAILED(hr)) return hr;

 ++g_lCounter;

 CComQIPtr<IEnumVARIANT> spev(spunkEnum);
 for (CComVariant svar;
      spev->Next(1, &svar, nullptr) == S_OK;
      svar.Clear()) {
  if (svar.vt != VT_DISPATCH) continue;

  HWND hwnd;
  CComHeapPtr<WCHAR> spszLocation;
  if (FAILED(GetBrowserInfo(svar.pdispVal,
             &hwnd, &spszLocation))) continue;

  ItemInfo *pii = GetItemByWindow(hwnd, nullptr);
  if (pii) { pii->lCounter = g_lCounter; continue; }
  pii = new(std::nothrow) ItemInfo(hwnd, svar.pdispVal);
  if (!pii) continue;

  LVITEM item;
  item.mask = LVIF_TEXT | LVIF_PARAM;
  item.iItem = MAXLONG;
  item.iSubItem = 0;
  item.pszText = spszLocation;
  item.lParam = reinterpret_cast<LPARAM>(pii);
  int iItem = ListView_InsertItem(g_hwndChild, &item);
  if (iItem < 0) delete pii;
 }

 int iItem = ListView_GetItemCount(g_hwndChild);
 while (--iItem >= 0) {
  ItemInfo *pii = GetItemByIndex(iItem);
  if (pii->lCounter != g_lCounter) {
   ListView_DeleteItem(g_hwndChild, iItem);
  }
 }

 return S_OK;
}

Building the window list is now a two-step process, since what we are really doing is updating the window list. First, we enumerate the contents of the IShellWindows. For each window, we get its window handle and see if there is already an item for that window. If so, then we update the counter for that item. If there is not already an item for that window, then we create one like we did before.

After we've processed all the windows that exist, we go look for the deletion by walking through all our items and deleting any whose counter was not updated by the previous loop.

Okay, but so far we haven't actually done anything new. Here's the new stuff:

class CShellWindowsEventsSink :
    public CDispInterfaceBase<DShellWindowsEvents>
{
public:
 HRESULT SimpleInvoke(
    DISPID dispid, DISPPARAMS *pdispparams, VARIANT *pvarResult)
 {
  switch (dispid) {
  case DISPID_WINDOWREGISTERED:
  case DISPID_WINDOWREVOKED:
   BuildWindowList();
   break;
  }
  return S_OK;
 }
};

CComPtr<CShellWindowsEventsSink> g_spShellSink;

This is the object that listens for changes to the window list. And whether the change is that a window arrived or a window departed, the response is the same: Refresh the window list.

All that's left to do is hook up this event sink (and clean it up):

BOOL
OnCreate(HWND hwnd, LPCREATESTRUCT lpcs)
{
 g_hwndChild = CreateWindow(WC_LISTVIEW, 0,
    LVS_LIST | WS_CHILD | WS_VISIBLE |
    WS_HSCROLL | WS_VSCROLL, 0, 0, 0, 0,
    hwnd, (HMENU)1, g_hinst, 0);
 g_spWindows.CoCreateInstance(CLSID_ShellWindows);
 BuildWindowList();

 g_spShellSink.Attach(new CShellWindowsEventsSink());
 g_spShellSink->Connect(g_spWindows);

 return TRUE;
}

void OnDestroy(HWND hwnd)
{
 g_spWindows.Release();
 if (g_spShellSink) {
  g_spShellSink->Disconnect();
  g_spShellSink.Release();
 }
 PostQuitMessage(0);
}

We now have a program that displays all the Internet Explorer and Explorer windows, updates their locations as you navigate, and adds and removes them as new windows are created or existing ones are closed.

Reminder: This is a Little Program, which means that there is little to no error checking, and the design may be somewhat suboptimal. (For example, I use global variables everywhere because I'm lazy.) But it should give you enough of a head start so you can write a more robust version.

Exercise: There is still a subtle bug in BuildWindowList. Identify it and discuss how you would address it.

A big little program: Monitoring Internet Explorer and Explorer windows, part 2: Tracking navigations

Raymond Chen - MSFT — Thu, 13 Jun 2013 14:00:00 GMT

Okay, it's been a while since we set aside our Little Program to learn a bit about connection points and using dispatch interfaces as connection point interfaces. Now we can put that knowledge to use.

Internet Explorer and Explorer windows fire a group of events known as DWebBrowserEvents, so we just need to listen on those events to follow the window as it navigates around.

Take our scratch program and make these changes:

#define UNICODE
#define _UNICODE
#define STRICT
#define STRICT_TYPED_ITEMIDS
#include <windows.h>
#include <windowsx.h>
#include <ole2.h>
#include <commctrl.h>
#include <shlwapi.h>

#include <shlobj.h>
#include <atlbase.h>
#include <atlalloc.h>
#include <exdisp.h>
#include <exdispid.h>

...
// DispInterfaceBase incorporated by reference

void UpdateText(HWND hwnd, PCWSTR pszText);

class CWebBrowserEventsSink :
    public CDispInterfaceBase<DWebBrowserEvents>

public:
 CWebBrowserEventsSink(HWND hwnd) : m_hwnd(hwnd) { }

 IFACEMETHODIMP SimpleInvoke(
    DISPID dispid, DISPPARAMS *pdispparams, VARIANT *pvarResult)
 {
  switch (dispid) {
  case DISPID_NAVIGATECOMPLETE:
   UpdateText(m_hwnd, pdispparams->rgvarg[0].bstrVal);
   break;

  case DISPID_QUIT:
   UpdateText(m_hwnd, L"<exited>");
   Disconnect();
   break;
  }
  return S_OK;
 };

private:
 HWND m_hwnd;
};

Our event sink class listens for DISPID_NAVIGATECOMPLETE and DISPID_QUIT and updates the text with the new navigation location or the string L"<exited>" if the window exited. In the exit case, we also disconnect from the connection point to break the circular reference.

The IDL file for NavigateComplete says

[id(DISPID_NAVIGATECOMPLETE), helpstring("...")]
void NavigateComplete([in] BSTR URL );

Therefore, we know that the URL parameter arrives as a VT_BSTR in position zero, so we can access it as pdispparams->rgvarg[0].bstrVal.

That class is basically the guts of the program. The rest is scaffolding. Like hooking up this guy to a listview item so it can report its findings somewhere.

struct ItemInfo
{
 ItemInfo(HWND hwnd, IDispatch *pdisp)
  : hwnd(hwnd) {
  spSink.Attach(new(std::nothrow) CWebBrowsrEventsSink(hwnd));
  if (spSink) spSink->Connect(pdisp);
 }
 ~ItemInfo() { if (spSink) spSink->Disconnect(); }

 HWND hwnd;
 CComPtr<CWebBrowserEventsSink> spSink;
};

ItemInfo *GetItemByIndex(int iItem)
{
 LVITEM item;
 item.mask = LVIF_PARAM;
 item.iItem = iItem;
 item.iSubItem = 0;
 item.lParam = 0;
 ListView_GetItem(g_hwndChild, &item);
 return reinterpret_cast<ItemInfo *>(item.lParam);
}

ItemInfo *GetItemByWindow(HWND hwnd, int *piItem)
{
 int iItem = ListView_GetItemCount(g_hwndChild);
 while (--iItem >= 0) {
  ItemInfo *pii = GetItemByIndex(iItem);
  if (pii->hwnd == hwnd) {
   if (piItem) *piItem = iItem;
   return pii;
  }
 }
 return nullptr;
}

void UpdateText(HWND hwnd, PCWSTR pszText)
{
 int iItem;
 if (GetItemByWindow(hwnd, &iItem)) {
  ListView_SetItemText(g_hwndChild, iItem, 0,
                       const_cast<PWSTR>(pszText));
 }
}

Attached to each listview item is an ItemInfo structure which remembers the browser window it is associated with and the event sink that is listening for events.

// GetLocationFromView, GetLocationFromBrowser, and GetBrowserInfo
// incorporated by reference

CComPtr<IShellWindows> g_spWindows;

// rename DumpWindows to BuildWindowList
HRESULT BuildWindowList()
{
 CComPtr<IUnknown> spunkEnum;
 HRESULT hr = g_spWindows->_NewEnum(&spunkEnum);
 if (FAILED(hr)) return hr;

 CComQIPtr<IEnumVARIANT> spev(spunkEnum);
 for (CComVariant svar;
      spev->Next(1, &svar, nullptr) == S_OK;
      svar.Clear()) {
  if (svar.vt != VT_DISPATCH) continue;

  HWND hwnd;
  CComHeapPtr<WCHAR> spszLocation;
  if (FAILED(GetBrowserInfo(svar.pdispVal,
             &hwnd, &spszLocation))) continue;

  ItemInfo *pii =
            new(std::nothrow) ItemInfo(hwnd, svar.pdispVal);
  if (!pii) continue;

  LVITEM item;
  item.mask = LVIF_TEXT | LVIF_PARAM;
  item.iItem = MAXLONG;
  item.iSubItem = 0;
  item.pszText = spszLocation;
  item.lParam = reinterpret_cast<LPARAM>(pii);
  int iItem = ListView_InsertItem(g_hwndChild, &item);
  if (iItem < 0) delete pii;
 }
 return S_OK;
}

To build the window list, we enumerate the contents of the IShellWindows. For each window, we get its window handle and current location and create a listview item for it. The reference data for the listview item is the ItemInfo.

BOOL
OnCreate(HWND hwnd, LPCREATESTRUCT lpcs)
{
 g_hwndChild = CreateWindow(WC_LISTVIEW, 0,
    LVS_LIST | WS_CHILD | WS_VISIBLE |
    WS_HSCROLL | WS_VSCROLL, 0, 0, 0, 0,
    hwnd, (HMENU)1, g_hinst, 0);
 g_spWindows.CoCreateInstance(CLSID_ShellWindows);
 BuildWindowList();
 return TRUE;
}

Our creation function creates a child listview and fills it with stuff.

And of course we clean up our objects when the items are deleted and when the window is destroyed.

LRESULT OnNotify(HWND hwnd, int idFrom, NMHDR *pnm)
{
 switch (idFrom) {
 case 1:
  switch (pnm->code) {
  case LVN_DELETEITEM:
   {
    auto pnmlv = CONTAINING_RECORD(pnm, NMLISTVIEW, hdr);
    delete reinterpret_cast<ItemInfo *>(pnmlv->lParam);
   }
   break;
  }
 }
 return 0;
}

void OnDestroy(HWND hwnd)
{
 g_spWindows.Release();
 PostQuitMessage(0);
}

 HANDLE_MSG(hwnd, WM_NOTIFY, OnNotify);

And there we have it, a program that displays all the Internet Explorer and Explorer windows and updates their locations as you navigate.

Note, however, that our program doesn't notice when new windows are created. We'll hook that up next time.

Dispatch interfaces as connection point interfaces

Raymond Chen - MSFT — Wed, 12 Jun 2013 14:00:00 GMT

Last time, we learned about how connection points work. One special case of this is where the connection interface is a dispatch interface.

Dispatch interfaces are, as the name suggests, COM interfaces based on IDispatch. The IDispatch interface is the base interface for OLE automation objects, and if you want your connection point interface to be usable from script, you probably should make it a dispatch interface.

I'm assuming you know how IDispatch works. The short version is that script that wants to invoke a method or property calls GetIDsOfNames to get the dispatch ID for the method or property it wants to access, and it uses the type library to figure out things like the parameters and return value. Once the scripting engine figures out how the method or property expects to be called, it can call IDispatch::Invoke passing the dispatch ID and a DISPPARAMS structure that holds the parameters.

Nowadays, this sort of thing goes by the fancy name of reflection, but back in the OLE Automation days, it was simply all in a day's work. You kids think you invented everything.

Just like as with regular connection point interfaces, a dispatch interface used as a connection point interface consists of events which are formally implemented as methods.

dispinterface DWidgetEvents
{
 [id(WDISPID_RENAMED)]
 HRESULT Renamed([in] BSTR oldName, [in] BSTR newName);
...
};

You declare that your object is a source of events for this interface by noting it in your object declaration. (Thanks, Medinoc for noting the error in the original version of this article.)

coclass Widget
{
 [default] interface IWidget;
 [default, source] dispinterface DWidgetEvents;
}

A client registers with the connection point with the DIID_DWidgetEvents interface. By convention, dispatch interfaces usually end with the word Events and are often prefixed with the letter D, and the interface ID symbol begins with DIID rather than simply IID. These conventions are not universally adhered-to, so don't freak out if you see people who don't follow them. (If you declare your dispatch interface in an IDL file, then the MIDL compiler will generate the dispatch interface ID with the DIID prefix for you.)

Now, formally, when the connection point wants to invoke the Renamed method, it calls GetIDsOfNames to get the ID for the method called L"Renamed", and asks for the type library to figure out what the parameters are. But this is frequently just pointless busy-work: The connection point often already knows the answer, since the connection point already knows what interface it is talking to. It doesn't need to do any "reflection" since the connection point already knows what the IDs and calling conventions are. In the same way, your C# code doesn't need to use reflection to call a method on an object whose assembly you already have referenced in your project. (The GetIDsOfNames exists not for connection points, but rather to assist dynamically-typed languages, where you can try to invoke any method on any object, and the method is looked up at run time.)

In other words, the connection point already knows that the ID for the method Rename is WDISPID_RENAMED, and that it takes two BSTR parameters, because that was part of the contract for registering with the connection point in the first place.

This means that in practice, the only method on the client that is ever called is IDispatch::Invoke.

Here is a template base class that I use for my connection point interface implementations of dispatch interfaces. We'll discuss the pieces afterwards:

template<typename DispInterface>
class CDispInterfaceBase : public DispInterface
{
public:
 CDispInterfaceBase() : m_cRef(1), m_dwCookie(0) { }

 /* IUnknown */
 IFACEMETHODIMP QueryInterface(REFIID riid, void **ppv)
 {
  *ppv = nullptr;
  HRESULT hr = E_NOINTERFACE;
  if (riid == IID_IUnknown || riid == IID_IDispatch ||
      riid == __uuidof(DispInterface))
  {
   *ppv = static_cast<DispInterface *>
          (static_cast<IDispatch*>(this));
   AddRef();
   hr = S_OK;
  }
  return hr;
 }

 IFACEMETHODIMP_(ULONG) AddRef()
 {
  return InterlockedIncrement(&m_cRef);
 }

 IFACEMETHODIMP_(ULONG) Release()
 {
  LONG cRef = InterlockedDecrement(&m_cRef);
  if (cRef == 0) delete this;
  return cRef;
 }

 // *** IDispatch ***
 IFACEMETHODIMP GetTypeInfoCount(UINT *pctinfo)
 {
  *pctinfo = 0;
  return E_NOTIMPL;
 }

 IFACEMETHODIMP GetTypeInfo(UINT iTInfo, LCID lcid,
                            ITypeInfo **ppTInfo)
 {
  *ppTInfo = nullptr;
  return E_NOTIMPL;
 }

 IFACEMETHODIMP GetIDsOfNames(REFIID, LPOLESTR *rgszNames,
                              UINT cNames, LCID lcid,
                              DISPID *rgDispId)
 {
  return E_NOTIMPL;
 }

 IFACEMETHODIMP Invoke(
    DISPID dispid, REFIID riid, LCID lcid, WORD wFlags,
    DISPPARAMS *pdispparams, VARIANT *pvarResult,
    EXCEPINFO *pexcepinfo, UINT *puArgErr)
 {
  if (pvarResult) VariantInit(pvarResult);
  return SimpleInvoke(dispid, pdispparams, pvarResult);
 }

 // Derived class must implement SimpleInvoke
 virtual HRESULT SimpleInvoke(DISPID dispid,
    DISPPARAMS *pdispparams, VARIANT *pvarResult) = 0;

public:
 HRESULT Connect(IUnknown *punk)
 {
  HRESULT hr = S_OK;
  CComPtr<IConnectionPointContainer> spcpc;
  if (SUCCEEDED(hr)) {
   hr = punk->QueryInterface(IID_PPV_ARGS(&spcpc));
  }
  if (SUCCEEDED(hr)) {
  hr = spcpc->FindConnectionPoint(__uuidof(DispInterface), &m_spcp);
  }
  if (SUCCEEDED(hr)) {
  hr = m_spcp->Advise(this, &m_dwCookie);
  }
  return hr;
 }

 void Disconnect()
 {
  if (m_dwCookie) {
   m_spcp->Unadvise(m_dwCookie);
   m_spcp.Release();
   m_dwCookie = 0;
  }
 }

private:
 LONG m_cRef;
 CComPtr<IConnectionPoint> m_spcp;
 DWORD m_dwCookie;
};

First, a distraction: Our QueryInterface implementation performs a double-cast of this to IDispatch, then to the templated interface. This ensures that the templated interface pointer and IDispatch are compatible. It would be bad if somebody tried to use this QueryInterface implementation with something unrelated to IDispatch. (Yes, I could've used std::is_base_of, but I'm an old-timer who grew up before TR1.)

The bulk of the class merely stubs out all the methods of IDispatch, save for IDispatch::Invoke, which does a little grunt work (initializing the result VARIANT) and then leaves the derived class to do the heavy lifting.

Finally, there are two public methods Connect and Disconnect. These perform the Advise and Unadvise calls we saw yesterday. To simplify things for our caller, we save the IConnectionPointer we registered against so that the caller doesn't have to pass it back in when disconnecting.

Exercise: Is the m_spcp.Release() call in Disconnect really necessary? (Assuming that Connect is called at most once.)

This helper template class makes writing dispatch interface connection point clients really simple, since all you have to do is implement SimpleInvoke in the form of a switch statement on the dispatch IDs you care about:

class CWidgetClient : public CDispInterfaceBase
{
public:
 CWidgetClient() { }

 HRESULT SimpleInvoke(
    DISPID dispid, DISPPARAMS *pdispparams, VARIANT *pvarResult)
{
 switch (dispid) {
 case WDISPID_RENAMED:
  HeyLookItGotRenamed(pdispparams->rgvarg[0].bstrVal,
                      pdispparams->rgvarg[1].bstrVal);
  break;
 }
 return S_OK;
};

In the SimpleInvoke method, we switch on the dispatch ID, and if we see one we like, we extract the parameters from the pdispparams.

Update: Commenter parkrrr points out a huge gotcha with the DISPPARAMS structure: The parameters are passed in reverse order. I don't know why. They just are.

Next time, we'll start hooking up events to our Little Program so it can update when the user navigates an Explorer or Internet Explorer window.

Warning! Managed code! The CLR understands the connection point/dispatch interface convention and exposes a dispatch event to managed code in the form of a CLR event and corresponding delegate. For example, our Renamed event is exposed as an event called Renamed, with delegate type DWidgetEvents_RenamedEventHandler. You can listen on the event the way you listen to any other CLR event: widget.Renamed += this.OnRenamed;.

Note: I completely ignored the subject of dual interfaces. You can read about those if you like, but we won't need to know about them for the job at hand.

An introduction to COM connection points

Raymond Chen - MSFT — Tue, 11 Jun 2013 14:00:00 GMT

Last time, we saw how to enumerate all the Internet Explorer and Explorer Windows and see what they are viewing. But that program printed static information. It didn't track the changes to the windows if the user clicked to another Web page or navigated to a different folder.

In order to hook that up, we need to understand the connection point model and the way events are expressed in dispatch interfaces. First, let's look at the connection point model. These topics confused me when I first met them (in part because I didn't do a good job of mentally separating them into two topics and instead treated it as one big topic), so I'm going to spend a few days trying to explain how it works, and then later this week, we'll actually hook things up. (And actually hooking it up is a lot easier than explaining it.)

Today, the connection point model.

Suppose you have a widget which can have multiple clients. The clients can communicate with the widget by invoking methods on the widget, like IWidget::SetColor. but how does the widget communicate with its clients? Well, since this is COM, the first thing you need is an interface, say, IWidgetClient. The idea is that each client implements IWidgetClient, and when the widget needs to, say, notify each client that the color changed, it can invoke IWidgetClient::OnColorChanged on each one. Each client can register with the widget for notifications.

The COM interface for standardizing the registration mechanism is IConnectionPoint. A connection point acts as a middle-man between the widget and all its clients: Whenever the widget needs to notify all its clients, it tells the connection point to do it.

Widget		Connection Point	→	Client A

	→		→	Client B

			→	Client C

A client registers with a connection point by calling IConnectionPoint::Advise, and it unregisters by calling IConnectionPoint::Unadvise.

Okay, that's great, but how do clients find the connection point so they can register with it?

The widget exposes an interface known as IConnectionPointContainer which provides access to an object's connection points. The client can call the IConnectionPointContainer::FindConnectionPoint method to get access to a specific connection point.

Here's how the pieces fit together:

// error checking elided for expository purposes

void IUnknown_FindConnectionPoint(IUnknown *punk,
                                  REFIID riid,
                                  IConnectionPoint **ppcp)
{
 // get the IConnectionPointContainer interface
 CComQIPtr<IConnectionPointContainer> spcpc(punk);

 // Locate the connection point
 spcpc->FindConnectionPoint(riid,  ppcp);
}

class CClient : public IWidgetClient
{
...
 IWidget *m_pWidget;
 DWORD m_dwCookie;
};

CClient::RegisterWidgetClient()
{
 // Find the IWidgetClient connection point
 CComPtr<IConnectionPoint> spcp;
 IUnknown_FindConnectionPoint(m_pWidget,
                              IID_IWidgetClient, &spcp);

 // register with it
 spcp->Advise(this, &m_dwCookie);
}

CClient::UnregisterWidgetClient()
{
 // Find the IWidgetClient connection point
 CComPtr<IConnectionPoint> spcp;
 IUnknown_FindConnectionPoint(m_pWidget,
                              IID_IWidgetClient, &spcp);

 // unregister from it
 spcp->Unadvise(m_dwCookie);
}

After registering as a widget client, the CClient object will receive method calls on its IWidgetClient until it unregisters.

Now the widget and clients have two-way communication. If the clients want to initiate the communuication, it can call a method on IWidget. If the widget wants to initiate the communication, it can call a method on IWidgetClient.

Note that we've created a giant circular reference. The widget has a reference to its connection point (so it can tell it to fire a notification to all its clients), and the connection point has a reference to the widget client (so it can forward the notification along), and the widget client has a reference to the widget in its m_pWidget member. In order to break this cycle, you have to remember to explicitly call UnregisterWidgetClient when you are no longer interested in receiving widget notifications.

Note that even though the arrows in the diagram above flow from left to right (from widget to clients), that doesn't mean that the information flow is strictly left-to-right. You can pass information in the other direction via return values or output parameters.

For example, there might be a method on the IWidgetClient interface called GetColor:

interface IWidgetClient : IUnknown
{
 ...
 HRESULT GetColor([out] COLORREF *pclr);
 ...
};

Since there can be multiple clients, the widget needs to have some sort of rule for deciding which client gets to choose the color. It might decide to ask each client in turn for a color, until one of them returns S_OK, and that client's color is used and no further clients are notified.

Or maybe there's a method called OnSave:

interface IWidgetClient : IUnknown
{
 ...
 HRESULT OnSave([in] IPropertyStorage *pps);
 ...
};

The convention here might be that all clients will be notified of the Save operation and they can write any additional information to the IPropertyStorage while handing the notification.

Those are just examples. Feel free to make up your own. The point is that just because the arrows go from the widget to the clients doesn't mean that information can't flow back the other way.

Most of the time, you have the simple case where a widget will expose a single connection point. In that case, the generality of the IConnectionPointContainer may seem unnecessary. But it allows you to add new connection points later. For example, you might have multiple client interfaces for different types of clients. You could have IWidgetColorClient for clients that are interested only in color changes, and IWidgetNetworkClient for clients that are interested only in monitoring the widget's network activity.

Or maybe you didn't plan on having multiple connection points originally, but in the second version of your product, you want to add additional methods to IWidgetClient, so you need to create IWidgetClient2, which means that you also need a new connection point for it.

Next time, a look at the special case where the client interface is a dispatch interface.

Unexpected complexity of Swedish pronouns, and escaping the resulting embarrassment

Raymond Chen - MSFT — Mon, 10 Jun 2013 14:00:01 GMT

I dreamed that Swedish had separate third-person-plural pronouns based on gender. They were formed from han and hon by adding a common suffix, but the pattern broke down for det, and I got stuck trying to finish a sentence without knowing the correct word.

I was able to escape from this embarrassing situation by using a technique available only in dreams: I woke up.

A big little program: Monitoring Internet Explorer and Explorer windows, part 1: Enumeration

Raymond Chen - MSFT — Mon, 10 Jun 2013 14:00:00 GMT

Normally, Monday is the day for Little Programs, but this time I'm going to spend a few days on a single Little Program. Now, this might very well disqualify it from the name Little Program, but the concepts are still little; all I'm doing is snapping blocks together. (Plus, it's my Web site, so you can just suck it.)

The goal of our Little Program is to monitor Internet Explorer and Explorer windows as they are created, navigate to new locations, and are destroyed. (In principle, other Web browsers can participate in this protocol, but I don't know of any that do, so I'll assume that only Explorer and Internet Explorer register with the ShellWindows object.)

The key to all this is the ShellWindows object, which we've spent time playing with in the past.

Today we're going to write a helper function that takes an object returned by the ShellWindows object and extract the window handle and current location. This is the guts of our Little Program, so I'm basically doing the cool stuff up front, and then leaving the annoying bits for later.

#define UNICODE
#define _UNICODE
#define STRICT
#define STRICT_TYPED_ITEMIDS
#include <windows.h>
#include <ole2.h>
#include <iostream>

#include <shlobj.h>
#include <atlbase.h>
#include <atlalloc.h>

Now that we got the preliminary header file goop out of the way, we can write the exciting function.

HRESULT GetBrowserInfo(IUnknown *punk, HWND *phwnd,
                       PWSTR *ppszLocation)
{
 HRESULT hr;

 CComPtr<IShellBrowser> spsb;
 hr = IUnknown_QueryService(punk, SID_STopLevelBrowser,
                            IID_PPV_ARGS(&spsb));
 if (FAILED(hr)) return hr;

 hr = spsb->GetWindow(phwnd);
 if (FAILED(hr)) return hr;

 hr = GetLocationFromView(spsb, ppszLocation);
 if (SUCCEEDED(hr)) return hr;

 return GetLocationFromBrowser(punk, ppszLocation);
}

Awfully short for what purported to be an exciting function, but that's because I hid the exciting parts in helper functions.

First, we take the object and ask to locate the top-level browser, since that's where some of the interesting information hangs out. We ask for the IShellBrowser so we can get the window handle via the base class method IOleWindow::GetWindow. That's the easy part.

Getting the current location is tricky, because Explorer windows do it one way, and Internet Explorer does it another way. That's because Explorer windows browse the shell namespace, whereas Internet Explorer windows browse the Internet. Shell namespace locations are represented by pidls, whereas Internet locations are represented by URLs.

First, the Explorer way:

HRESULT GetLocationFromView(IShellBrowser *psb,
                            PWSTR *ppszLocation)
{
 HRESULT hr;

 *ppszLocation = nullptr;

 CComPtr<IShellView> spsv;
 hr = psb->QueryActiveShellView(&spsv);
 if (FAILED(hr)) return hr;

 CComQIPtr<IPersistIDList> sppidl(spsv);
 if (!sppidl) return E_FAIL;

 CComHeapPtr<ITEMIDLIST_ABSOLUTE> spidl;
 hr = sppidl->GetIDList(&spidl);
 if (FAILED(hr)) return hr;

 CComPtr<IShellItem> spsi;
 hr = SHCreateItemFromIDList(spidl, IID_PPV_ARGS(&spsi));
 if (FAILED(hr)) return hr;

 hr = spsi->GetDisplayName(SIGDN_DESKTOPABSOLUTEPARSING,
                           ppszLocation);
 return hr;
}

The maze we navigate here is to start from the IShellBrowser and get to the IShellView by calling IShellBrowser::QueryActiveShellView. It's rather annoying that the IShellBrowser::QueryActiveShellView method always returns you an IShellView rather than being forward-looking and letting you pass a riid/ppv pair. (The shell has for the most part learned this lesson, and new object creation or retrieval functions tend to take the riid/ppv pair so you can specify your ring size when you place the order instead of always getting a size 6 ring and then having to resize it.) Since IShellBrowser::QueryActiveShellView doesn't let us specify the desired interface, we have to do the QueryInterface ourselves to convert the IShellView into what we really want: The IPersistIDList.

From the IPersistIDList we ask for the pidl, which now tells us what the Explorer window is looking at. For display purposes, we convert it into a string by converting the pidl into an IShellItem (notice the handy riid/ppv pair produced by the type-checking IID_PPV_ARGS macro) and then asking the shell item for its parsing name.

(We saw techniques similar to this a few years ago.)

If it turns out we don't have an Explorer window, then we try again using the Web browser interfaces:

HRESULT GetLocationFromBrowser(IUnknown *punk,
                               PWSTR *ppszLocation)
{
 HRESULT hr;

 CComQIPtr<IWebBrowser2> spwb2(punk);
 if (!spwb2) return E_FAIL;

 CComBSTR sbsLocation;
 hr = spwb2->get_LocationURL(&sbsLocation);
 if (FAILED(hr)) return hr;

 return SHStrDupW(sbsLocation, ppszLocation);
}

We turn the object into an IWebBrowser2 and ask for the LocationURL property. The annoyance here is that IWebBrowser2 is an automation interface, so it uses BSTR for passing strings around, which is different from IShellItem::GetDisplayName which uses CoTaskMemAlloc, since that is the convention for non-dispatch COM interfaces. We therefore have to convert the BSTR to a task-allocated PWSTR before returning, so that the return value is consistent with GetLocationFromView.

Finally, we call the function in a loop to test that it actually works:

CComPtr<IShellWindows> g_spWindows;

HRESULT DumpWindows()
{
 CComPtr<IUnknown> spunkEnum;
 HRESULT hr = g_spWindows->_NewEnum(&spunkEnum);
 if (FAILED(hr)) return hr;

 CComQIPtr<IEnumVARIANT> spev(spunkEnum);
 for (CComVariant svar;
      spev->Next(1, &svar, nullptr) == S_OK;
      svar.Clear()) {
  if (svar.vt != VT_DISPATCH) continue;

  HWND hwnd;
  CComHeapPtr<WCHAR> spszLocation;
  if (FAILED(GetBrowserInfo(svar.pdispVal, &hwnd,
                            &spszLocation))) continue;

   std::wcout << hwnd
              << L" "
              << static_cast<PCWSTR>(spszLocation)
              << std::endl;
 }
 return S_OK;
}

int __cdecl wmain(int, PWSTR argv[])
{
 CCoInitialize init;
 g_spWindows.CoCreateInstance(CLSID_ShellWindows);
 DumpWindows();
 g_spWindows.Release();

 return 0;
}

Yes, I stupidly made g_spWindows a global variable, but it'll come in handy later. (It's still stupid, but at least there's a reason for the stupidity.)

Okay, we can take this program for a spin. When you run it, it should print the window handles and locations of all your Explorer and Internet Explorer windows.

Before we can start hooking up events to keep this list up to date, we need to learn a bit about connection points and using dispatch interfaces as connection point interfaces. We'll spend a few days on those topics, then return to our program.

Sharing an input queue takes what used to be asynchronous and makes it synchronous, like focus changes

Raymond Chen - MSFT — Fri, 07 Jun 2013 14:00:00 GMT

As I noted earlier in the series, attaching input queues puts you back into the world of coöperative multitasking, where the two attached threads need to work together to get anything done.

Back in the old 16-bit days, when input was synchronous, there was only one active window, only one focus window, only one window with capture, only one caret, only one cursor show count, only one keyboard state, only one input state. Furthermore, if you called SetFocus, you had to wait until the previous focus window responded to the WM_KILLFOCUS message before your SetFocus call returned.

With asynchronous input, these sorts of operations are now local to your input queue. If you call SetFocus, then that steals focus only from other windows which belong to your input queue. Windows which belong to other input queues are unaffected. (Conversely, you can set focus only to windows which belong to your input queue, since those are the only windows your input queue has access to.)

This is probably not very exciting, until you look at the one thing that can reach across input queues: The foreground window.

The concept of the foreground window was introduced when input was desynchronized in order to express the "really global active window", as opposed to SetActiveWindow, which continued to refer to the local active window. It's something that was originally intended to be used only in emergencies since it violates the isolation of input queues, but as we learned before, eventually nothing is special any more, and what used to be the special function for stepping outside the box has become the function you use every day for getting things done.

What most people don't realize is that SetForegroundWindow is still subject to the rules on synchronous input. If you call SetForegroundWindow, and the previous foreground window also belongs to your input queue, then your call to SetForegroundWindow will wait until the previous foreground window processes its WM_ACTIVATE(WA_INACTIVE) message.

A lot of people use AttachThreadInput thinking that it's a Get Out of Jail Free card, letting them manipulate windows of other programs and bypass the normal rules for focus and activation. But in fact it's a Get Into the Same Jail card, because you tied your thread's fate to that other thread. If that thread has stopped responding to messages, then your thread will also stop responding to messages, since you are sharing the same input queue and operations within an input queue are synchronous.

Bonus reminder: If two windows are related by a parent/child relationship or owner/owned relationship, then their input queues are automatically attached. For example, if you do a SetParent where the parent and child are in different threads, you have just synchronized the two threads. This sort of cross-thread relationship is technically legal, but it is very difficult to manage correctly, so it should be avoided unless you really know what you're doing. And if you are doing cross-thread or cross-process between windows that were not designed to participate in cross-thread or cross-process parenting, you are almost certainly doomed.