The Complete Idiot's Guide to Writing Shell Extensions - Part III
By Maurice Montgenie (Original Version in ATL by Michael Dunn) 

A tutorial on writing a shell extension that shows pop-up info for files. 

  • Download demo project - 45 Kb

    In Parts I and II of the Guide, I showed how to write context menu extensions. In Part III, I'll demonstrate a different type of extension, explain how to share memory with the shell, and show how to use MFC alongside ATL.

    Part III assumes that you understand the basics of shell extensions (given in Part I), and are familiar with MFC. Note that the extension presented here requires version 4.71 or higher of the shell, so you must be running Windows 98 or 2000, or have the Active Desktop installed on 95 or NT 4.

    The QueryInfo extension

    The Active Desktop shell introduced a new feature, tooltips that show a description of certain objects if you hover the mouse over them. For example, hovering over My Computer shows this tooltip:

     [My Computer tooltip - 6K]

    Other objects like Network Neighborhood and Control Panel have similar tooltips. We can provide our own pop-up info for other objects in the shell, using a QueryInfo extension.

    A note about the name "QueryInfo extension": This is something I made up; I named it after one of the interfaces used, IQueryInfo. As far as I can tell, there isn't an official name for it. I took a quick look through the October 1999 MSDN and couldn't even find a mention of this type of extension! It is definitely a supported extension, though, since Microsoft Office installs QueryInfo extensions for its file types, as shown here:

     [Word doc tooltip - 5K]

    WinZip version 8 also has a QueryInfo extension for compressed files:

     [WinZip tooltip - 5K]

    The best documentation I've found is Dino Esposito's article "Enhance Your User's Experience with New Infotip and Icon Overlay Shell Extensions" in the March 2000 MSDN Magazine.

    Beginning the context menu extension – what should it do?

    This shell extension will be a quick text file viewer - it will display the first line of the file, along with the total file size. Our information will appear in a tooltip when the user hovers the mouse over a TXT file.

    Using AppWizard to get started

    Run the AppWizard and make a new ATL COM app. We'll call it TxtInfo. To add a COM object to the DLL, go to the ClassView tree, right-click the TxtInfo classes item, and pick New ATL Object.

    In the ATL Object Wizard, the first panel already has Simple Object selected, so just click Next. On the second panel, enter TxtInfoShlExt in the Short Name edit box and click OK. (The other edit boxes on the panel will be filled in automatically.)

    The initialization interface

    Before, with our context menu extensions, we implemented the IShellExtInit interface, which was how Explorer initialized our object. There is another initialization interface used for some shell extensions, IPersistFile, and this is the one a QueryInfo extension uses. Why the difference? If you remember, IShellExtInit::Initialize() receives an IDataObject pointer with which it can enumerate all of the files that were selected. Extensions that can only ever operate on a single file use IPersistFile. Since the mouse can't hover over more than one object at a time, a QueryInfo extension only works on one file at a time, so it uses IPersistFile.

    We first need to add IPersistFile to the list of interfaces that CTxtInfoShlExt implements. Open up TxtInfoShlExt.h, and add the lines listed here in red:

    asmTxtInfoIMap  InterfaceItem { pIID_ITxtInfoShlExt,  OFFSET vtableITxtInfoShlExt }
    InterfaceItem { pIID_IPersistFile, OFFSET vtableIPersistFile }
    We'll also need a variable to hold the filename that Explorer gives us during our initialization:
    asmTxtInfoObjData   STRUCT
    m_szFilename BYTE MAX_PATH DUP(?)
    asmTxtInfoObjData ENDS
    If you look up the docs on IPersistFile, you'll see a lot of methods. Fortunately, for the purposes of a shell extension, we only have to implement Load(), and ignore the others.

    Everything aside from Load() just returns E_NOTIMPL to indicate that we don't implement them.

    And to make this situation even nicer, our Load() method is really simple. We'll just store the name of the file that Explorer passes us. This is the file that the mouse is hovering over.

    Load proc this_:DWORD, pwszFilename:DWORD, dwMode:DWORD
    pObjectData this_, ecx ; cast this_ to object data
    lea ecx, (asmTxtInfoObjData ptr [ecx]).m_szFilename invoke WideCharToMultiByte, CP_ACP, 0, pwszFilename, -1, ecx, MAX_PATH, NULL, NULL mov eax, S_OK ret Load endp
    The filename is stored in m_szFilename, for later use.

    Creating text for the tooltip

    After Explorer calls our Load() method, it calls QueryInterface() to get another interface: IQueryInfo. IQueryInfo is a pretty simple interface, with just two methods (and only one is actually used). Open up TxtInfoShlExt.h again, and add the lines listed here in red:

    asmTxtInfoIMap  InterfaceItem { pIID_ITxtInfoShlExt,  OFFSET vtableITxtInfoShlExt }
    InterfaceItem { pIID_IPersistFile, OFFSET vtableIPersistFile }
    InterfaceItem { pIID_IQueryInfo, OFFSET vtableIQueryInfo }
    The GetInfoFlags() method isn't used currently, so we can just return E_NOTIMPL. GetInfoTip() is where we will return text to Explorer for it to show in the tooltip. First, the boring stuff at the beginning:
    GetInfoTip proc uses esi this_:DWORD, pdwFlags:DWORD, ppwszTip:DWORD   
    LOCAL pMalloc:DWORD
    LOCAL hFile:DWORD, hMapFile:DWORD, pMapViewFile:DWORD, dwFileSize:DWORD
    LOCAL bReadLine:DWORD
    LOCAL pszTooltip:DWORD
    LOCAL hResult:DWORD
    dwFlags is not used currently. ppwszTip is a pointer to an LPWSTR (Unicode string pointer) that we'll set to point at a buffer that we must allocate.

    First, we'll try to open the file for reading. We know the filename, since we stored it in the Load() function earlier.

      ;Opens a mapped view of the selected file
    invoke CreateFile, ecx, GENERIC_READ, 0, NULL, OPEN_EXISTING,\
    mov hFile, eax .if eax == 0FFFFFFFFh mov hResult, E_FAIL jmp fin .endif invoke CreateFileMapping, hFile, NULL,PAGE_READONLY, 0, 0, NULL mov hMapFile, eax .if eax == 0 invoke CloseHandle,hFile mov hResult, E_FAIL jmp fin .endif invoke MapViewOfFile, hMapFile, FILE_MAP_READ, 0, 0, 0 mov pMapViewFile, eax .if eax == 0 invoke CloseHandle,hMapFile invoke CloseHandle,hFile mov hResult, E_FAIL jmp fin .endif
    Now, since we need to use the shell's memory allocator to allocate a buffer, we need an IMalloc interface pointer. We get this by calling the SHGetMalloc() function:
      invoke SHGetMalloc, addr pMalloc
    .if eax==E_FAIL
    jmp closefile
    I'll have more to say about IMalloc a bit later. The next step is to get the file size, and read the first line:
      ;Get the size of the file
    invoke GetFileSize, hFile, NULL
    mov dwFileSize, eax
    ;Read in the first line from the file. ...
    The next step is to create the first part of the tooltip, which lists the file size.
      dsText szFileSize, "File size: "
    invoke lstrcat, pszTooltip, offset szFileSize
    invoke dwtoa, dwFileSize, addr buffer
    invoke lstrcat, pszTooltip, addr buffer
    szNewLine BYTE 13,10,0
    invoke lstrcat, pszTooltip, addr szNewLine

    Now, if we were able to read the first line of the file, we add it to the tooltip.

      pop ecx ;get the number of characters of the first line
    invoke lstrcpyn, addr buffer, pMapViewFile, ecx
    invoke lstrcat, pszTooltip, addr buffer
    Now that we have the complete tooltip, we need to allocate a buffer. Here's where we use IMalloc. The pointer returned by SHGetMalloc() is a copy of the shell's IMalloc interface. Any memory we allocate with that interface resides in the shell's process space, so the shell can use it. More importantly, the shell can also free it. So what we do is allocate the buffer, and then forget about it. The shell will free the memory once it's done using it.

    One other thing to be aware of is that the string we return to the shell must be in Unicode. That's why the calculation in the Alloc() call below multiplies by sizeof(wchar_t); just allocating memory for lstrlen(sToolTip) would only allocate half the required amount of memory.

      invoke lstrlen, pszTooltip
    inc eax
    push eax
    shl eax, 1
    coinvoke pMalloc, IMalloc, Alloc, eax
    mov ecx, ppwszTip
    mov [ecx], eax mov eax, ppwszTip
    .if eax==NULL
    mov hResult, E_OUTOFMEMORY
    jmp clearmem
    .endif ;Use the Unicode string copy function to put the tooltip text in the buffer.
    pop ecx
    mov edx, ppwszTip
    mov edx, [edx]
    invoke MultiByteToWideChar, CP_ACP, 0, pszTooltip, -1, edx, ecx
    The last thing to do is release the IMalloc interface we got earlier.
      coinvoke pMalloc, IMalloc, Release

    And that's all there is to it! Explorer takes the string in ppwszTip and displays it in a tooltip.

     [text file tooltip - 6K]

    Registering the shell extension

    QueryInfo extensions are registered a bit differently than context menu extensions. Our extension is registered under a subkey of HKEY_CLASSES_ROOT whose name is the file extension we want to handle. In this case, that's HKCR\.txt. But wait, it gets stranger! You'd think the ShellEx subkey would be something logical like "TooltipHandlers". Close! The key is called "{00021500-0000-0000-C000-000000000046}".

    I think Microsoft is trying to sneak some shell extensions past us here! If you poke around the registry, you'll find other ShellEx subkeys whose names are GUIDs. That GUID above happens to be the GUID of IQueryInfo.

    Anyway, here's the RGS script necessary to have our extension invoked on .TXT files:

        NoRemove .txt
            NoRemove shellex
                NoRemove {00021500-0000-0000-C000-000000000046} = s '{F4D78AE1-05AB-11D4-8D3B-444553540000}'

    You can easily have the extension invoked for other extensions by duplicating the above snippet, and changing ".txt" to whatever extension you want. Unfortunately, you can't register a QueryInfo extension under the * or AllFileSystemObjects keys to have it invoked on all files.

    As in our previous extensions, on NT and Win 2000 we need to add our extension to the list of "approved" extensions. The code to do this is in the DllRegisterServer() and DllUnregisterServer() functions in the sample project.

    The component in asm weigth only 15Ko, the same one coded with ATL is 28Ko !!!


    Copyright © Maurice MONTGENIE -