Windows 右键菜单扩展

蔚落 2022-02-16 14:22 812阅读 0赞

右键菜单，指用户在对Windows Shell Object右键单击时，弹出的上下文菜单（Context Menu）。

如上图所示的对右键菜单进行扩展，属于Windows Shell Extension编程的一部分。

注：一般扩展程序的信息会注册到注册表某个路径的ShellExt下。

本文将介绍利用COM接口对Windows右键菜单进行扩展，笔者将分四个步骤对整个项目建立过程进行引导和解释，并会在文章末尾将给出项目代码（C++）链接。

声明：本文在某些API的解释中，加入了笔者的个人理解，可能并不完全或存在理解错误，故在重要WinAPI的解释后面会加入MSDN的连接，方便读者直接查阅官方文档。一切解释请以官方文档为准！

可能需要用到但并不是阅读本文必须的前置知识：COM、ATL、注册表。

一. 新建一个ATL项目  
Visual Studio——新建项目——ATL——使用默认配置（一直按下一步即可）。

注:默认配置中程序类型为动态链接库dll。

注:如果生成的项目中多了一个以PS为后缀的子项目，可以选择将之移除。

二. 为项目添加一个简单的ATL对象，继承并实现相应的IContextMenu、IShellExtInit的接口方法。  
右键项目——添加（Add）——类（Class）——弹出添加引导

引导中双击选择ATL简单对象（ATL Simple Object）,并根据需要填写类名字以及对应的信息，（某些信息VS将自动帮填写，但ProgID建议手动填写一下），点击完成生成一个ATL 简单对象，会发现项目中生成了刚才填写类名字的.h、.cpp、.rgs文件。

打开.h文件，会发现刚才填写的C++类型的声明，请在继承语法的最后添加上

public IContextMenu，public IShellExtInit  
添加COM类型映射：在宏BEGIN\_COM\_MAP与宏BEGIN\_COM\_END之间的列表下手动加上

COM\_INTERFACE\_ENTRY(IContextMenu)  
   
COM\_INTERFACE\_ENTER(IShellExtInit)  
然后覆盖并实现IContextMenu接口（QueryInterface，GetCommandString、InvokeCommand）以及IShellExtInit接口（Initialize）

系统对这些接口的调用顺序、时刻为：

Initialize（用户右键点击某个Shell程序时）  
QueryContextMenu（1.返回S\_OK或其他表示初始化成功的HRESULT时。插入自定义菜单的入口。）  
GetCommandString（用户光标盘旋（hover）在插入的菜单项时，系统status bar将显示的信息。Vista以后的系统不再有作用，不是实现的重点。）  
InvokeCommand（用户点击新插入的菜单项时，将会调用这个方法。用户点击菜单项回调的入口。）  
下面笔者来解析一下这些接口的作用，所有对本文较为有用的地方都以红色标注。

HRESULT Initialize(  
  PCIDLIST\_ABSOLUTE pidlFolder,  
  IDataObject       \*pdtobj,  
  HKEY              hkeyProgID  
);  
参数pdtobj，表示指向某个Shell Object的指针。可以通过这个指针获取用户右键单击的Shell Object信息。比如，可以获取该Shell Object的名称，并且判断其是不是我们需要处理的类型。特别地，对于右键单击桌面空白处或者是文件夹空白处，pdtobj为NULL。

注：只有当这个函数返回S\_OK的时候，QueryContextMenu才会被调用。

IShellExtInit::Initialize-MSDN

HRESULT QueryContextMenu(  
    HMENU hmenu,  
    UINT indexMenu,  
    UINT idCmdFirst,  
    UINT idCmdLast,  
    UINT uFlags  
);  
   
  
参数hmenu，表示用户右键单击弹出的那个菜单的Handle。配合使用GetMenuItemCount、GetSubMenu、GetMenuString、InsertMenuItem等Win API可以将自定义的菜单插入到hemnu菜单树所包含的任意菜单中去。  
参数indexMenu，表示你可以调用InsertMenu或者InsertMenuItem将你的菜单插入的起始位置。  
idCmdFirst，你可以用作作为你自定义菜单标识的最小值。  
idCmdLast，你可以用作作为你自定义菜单标识的最大值。  
uFlags，用于标识当前回调状态的标志位。一般只需要关注一个位标识：CMF\_DEFAULTONLY.这个为表示用户只在右键双击Shell Object，这个时候不需要插入菜单，只需要简单返回MAKE\_HRESULT(SEVERITY\_SUCCESS, 0, 0)即可。  
函数返回值，一般为MAKE\_HRESULT（SEVERITY\_SUCCESS, 0 ,你插入的菜单数量)  
注：通过WIN API插入菜单的时候，需要注意的几点：

自定义菜单的id值必须在区间\[idCmdFirst,idCmdLast\]之间，这个id值同时也是当你的菜单项被用户点击的时候，回调时用于区分你自己的多个菜单项的一个标识值。

插入菜单代码逻辑流应为（位于QueryContextMenu函数内）：

if(CMF\_DEFAULTONLY & uFlags)  
\{  
    return MAKE\_HRESULT(SEVERITY\_SUCCESS, FACILITY\_NULL, USHORT(0));  
\}  
UINT uid = idCmdFirst;  
//当你插入菜单的时候，同时递增uid，同时保存uid值到对应菜单的映射。  
   
//递增uid时，也需要判断一下uid<=idCmdLast  
   
.....  
   
//插入菜单完毕  
return MAKE\_HRESULT(SEVERITY\_SUCCESS,0,uid-idCmdFirst);  
为hemu插入子菜单主要有两个WIN\_API:InsertMenu以及InsertMenuItem。我们只关注更为常用的后者。

BOOL InsertMenuItemA(  
  HMENU            hmenu,  
  UINT             item,  
  BOOL             fByPosition,  
  LPCMENUITEMINFOA lpmi  
);  
   
hemenu表示你的自定义菜单需要插入到的父菜单。  
Item表示位置或者菜单的Id  
fByPosition，True表示item为插入到菜单的位置，False表示item为插入菜单的id  
Lpmi，表示需要插入的子菜单的信息，见下文。  
typedef struct tagMENUITEMINFOW \{  
  UINT      cbSize;  
  UINT      fMask;  
  UINT      fType;  
  UINT      fState;  
  UINT      wID;  
  HMENU     hSubMenu;  
  HBITMAP   hbmpChecked;  
  HBITMAP   hbmpUnchecked;  
  ULONG\_PTR dwItemData;  
  LPWSTR    dwTypeData;  
  UINT      cch;  
  HBITMAP   hbmpItem;  
\} MENUITEMINFOW, \*LPMENUITEMINFOW;

fMask 表示系统应该关注这个结构体的那些成员数据，我们可以用或位操作进行。比如我们让系统关注我们设置的fType\\fState\\wID,则需要设置fMask = MIIM\_FTYPE | MIIM\_ID|MIIM\_STATE 。

fType 表示我们将数据存到dwTypeData的数据类型。通常为MFT\_STRING，并且将用于显示菜单名称的字符串赋值给dwTypeData

wID 是最为重要的一个菜单标识。如前文所说，wID的赋值应为\[idCmdFirst,idCmdLast\]之间。

并且这个值在InvokeCommand的回调当中用于确定自定义的哪个菜单被按下（见后文）

为菜单插入图标：

hbmpChecked\\hbmpUnchecked：使用时必须在fMask中设置位MIIM\_CHECKMASKS。

hbmpItem ：设置位MIIM\_BITMAP。

范例：

在hmenu中插入一个名称叫做“Demo”的，图标显示为hbmpDemo的菜单项如下。

MENUITEMINFO mii;  
::memset(&mii, 0, sizeof(MENUITEMINFO));  
mii.cbSize = (UINT)sizeof(MENUITEMINFO);  
mii.fMask = MIIM\_STRING|MIIM\_ID|MIIM\_FTYPE|MIIM\_BITMAP;  
mii.fType = MFT\_STRING;  
mii.dwTypeData = L”Demo”;  
mii.wID = id;//id 为\[idCmdFirst,idCmdLast\]之间某个值  
mii.hbmpItem = hbmpDemo;  
::InsertMenuItem(hmenu, uiIndex, TRUE, (LPCMENUITEMINFO)&mii);  
   
  
IContextMenu::QueryContextMenu

WIN\_API InsertMenuItem 以及 MENUITEMINFO 结构体

最后，响应菜单项被点击事件的入口在InvokeCommand函数

HRESULT InvokeCommand( CMINVOKECOMMANDINFO \*pici )  
\{  
    //利用pici的lpVerb判断对应哪个自定义菜单项被点击了  
    WORD menuId = LOWORD(pici->lpVerb);  
    //一般选择switch case的方法来进行判断  
    switch(menuId)  
    \{  
        ....//做某个菜单被点击的用户逻辑。     
    \}  
    //但也有直接用hash table or map将菜单id和回调绑定到一起，然后查询菜单所代表的业务逻辑的。  
\}  
   
typedef struct \_CMINVOKECOMMANDINFO \{  
    DWORD cbSize;  
    DWORD fMask;  
    HWND hwnd;  
    LPCSTR lpVerb;  
    LPCSTR lpParameters;  
    LPCSTR lpDirectory;  
    int nShow;  
    DWORD dwHotKey;  
    HANDLE hIcon; \} CMINVOKECOMMANDINFO;  
InvokeCommand函数作为回调入口，重点关注lpVerb这个数据，这个数据的低位字（Low Word）表示被点击的菜单项的ID，这个ID和调用InsertMenuItem的时候，传入的MENUITEMINFO结构的wID相同。

通常，我们使用这个ID来区分自定义的菜单项。

一旦确认某个菜单被点击了，就执行该菜单所代表的程序逻辑。

IContextMenu::InvokeCommand

三. 修改添加该类时自动生成的.rgs脚本文件  
.rgs文件是由ATL项目用于修改注册表的脚本文件。

一般，在添加了一个简单的ATL对象类之后，会对应地生成一个.rgs脚本文件。并且，会自动生成如下信息（这些脚本主要作用是为你的类型自动注册COM组件）。

HKCR  
\{  
    DesktopContextMenuExtension.ShellExt.1 = s 'DesktopContextMenuExtension ShellExt Class'  
    \{  
        CLSID = s '\{721F6C56-9944-4E82-BCBB-977F7681D7AC\}'  
    \}  
    DesktopContextMenuExtension.ShellExt = s 'DesktopContextMenuExtension Class'  
    \{          
        CurVer = s 'DesktopContextMenuExtension.ShellExt.1'  
    \}   
      
    NoRemove CLSID  
    \{  
        ForceRemove \{721F6C56-9944-4E82-BCBB-977F7681D7AC\} = s 'DesktopContextMenuExtension Class'  
        \{  
            ProgID = s 'DesktopContextMenuExtension.ShellExt.1'  
            VersionIndependentProgID = s 'DesktopContextMenuExtension.ShellExt'  
            ForceRemove Programmable  
            InprocServer32 = s '%MODULE%'  
            \{  
                val ThreadingModel = s 'Apartment'  
            \}  
            TypeLib = s '\{AB96BF74-098F-4B26-916C-FA785E3C33B6\}'  
            Version = s '1.0'  
        \}  
    \}  
\}  
注：CLSID   
简单来说，就是通过编写这个文件，将一切有关注册表的操作都交给该脚本语言的解析器去做，然后轻松粗暴解决频繁使用CKey类或者Win API对注册表进行读写步骤。

注：使用CKey或者WINAPI也能达到目的，但对于编码来说难免会有些麻烦，必须在dll注册的函数体内注册表插入信息，然后在dll卸载的函数体内移除注册表中的信息，整个过程十分难受。该脚本的语法语义，请见 MSDN rgs脚本语法语义

为了实现右键菜单的扩展，以桌面空白处以及文件夹空白处为例。

需要在注册表中插入的位置以及信息为(HKCR == HKEY\_CLASSES\_ROOT)：

HKCR\\\\DesktopBackground\\\\shellex\\\\ContextMenuHandlers\\\\InsertedDemoName

将InsertedDemoName的默认值改成你程序对应的CLSID

还有两处需要插入的信息同上。位置为：

HKCR\\\\Directory\\\\shellex\\\\ContextMenuHandlers

HKCR\\\\Directory\\\\background\\\\shellex\\\\ContextMenuHandlers

以DesktopBackground为例的.rgs脚本为：

HKCR  
\{  
    NoRemove DesktopBackground  
    \{  
        NoRemove ShellEx  
        \{  
            NoRemove ContextMenuHandlers  
            \{  
                ForceRemove 'DesktopContextMenuExtension' = s '\{721F6C56-9944-4E82-BCBB-977F7681D7AC\}'  
            \}  
        \}  
    \}  
\}  
注：这里还可以对应不同类型文件右键菜单进行扩展，对应的扩展名下的HKCR\\\\扩展名\\\\shellex\\\\ContextMenuHandlers下插入信息同上。

如在HKCR\\\\.pdf\\\\shellext\\\\ContextMenuHandlers插入，则当用户右键点击.pdf文件时，会调用到我们的Initialize -> QueryContextMenu...

另外 文件夹：folder，快捷方式：.lnk，分区：drive等等

三.5  有了IShellExtInit和IContextMenu接口，又有了修改注册表对应位置的.rgs脚本文件，现在终于可以来解析一下整个右键菜单扩展的调用流程了。  
当用户右键单击某个Shell对象的时候，此时Windows系统会自动在对应的注册表项中查找ShellExt\\\\ContextMenuHandlers下的所有键的列表。注：这便是为什么我们要往生成的.rgs文件添加我们修改注册表的脚本，将我们的类型的CLSID信息加入到XXXX\\\\ContextMenuHandlers当中去的原因。

此时系统会读取的列表当中的所有CLSID信息，并且在HKCR\\\\CLSID\\\\目录下找到对应名字就为这些CLSID的键项，里面会有我们注册的dll的位置信息。注：这是在我们添加一个ATL简单对象时，.rgs自动添加的那串脚本所做的事情。就是注册我们的COM组件。

此时，系统将我们的dll加载到explorer进程的地址空间里边（载入过程只会进行一次），利用dll中的DllGetClassObject函数获取到了所有加载的dll中编写了继承了IShellExtInit和IContextMenu的类对象，（怎么判断类对象是否继承了IShellExtInit和IContextMenu？这就和COM相关了。DllGetClassObject中有一个参数为riid，就是为某些COM接口类的唯一一个标识，通过IUnkown中的QueryInterface就可以知道该实例对象是否继承了IShellExtInit和IContextMenu\[1\]），并调用Initialize，若该函数返回S\_OK，就调用QueryContextMenu函数，我们往右键菜单插入自定义扩展菜单就是这样做的。

注\[1\]:笔者在编写此文的时候，才刚刚开始阅读《COM本质论》了解COM的知识，此处可能会有错漏。

后面当点击我们自定义的菜单的时候，explorer就会调用我们的InvokeCommand函数，此时我们的菜单被点击逻辑被执行。

注:如果你尝试在被点击逻辑的代码中打开了模态窗口（例如MessageBox），那么对应的Explorer进程就会进入假死状态。阻塞代码同理。

四.使用regsvr32注册该COM dll，并测试对应功能。  
右键项目属性，分别修改以下几项。

编译项目，分别在不同平台测试。x64位dll对应64位系统，Win32对应32位系统。

以管理员方式运行cmd或powershell

注册dll：regsvr32  “你的dll路径”

卸载dll：regsvr32  /u  “你的dll路径”

如果注册dll报“LoadLibrary（XXXX.dll）错误”，重点看上面红字红框，并且请尝试使用dll依赖工具查看依赖缺失。

如果报“0x800200?”错误，请检查是否使用管理员身份运行cmd，若确定已使用来管理员权限，请检查.rgs文件脚本的语法是否出错（下面是我碰到过的小坑

坑1：ForceRemove ‘MyProgram.Name.1’ =空格s空格 ’Demo’，注意检查空格。

坑2：.rgs文件编码方式推荐选择无BOM的UTF-8编码）