Devices and Printers Folder Extensibility Sample

Last Updated: March 2009

 

Demonstrates

This sample demonstrates how to create property pages and context menu handlers for devices in the Devices and Printers Folder. The sample solution contains two projects: a context menu project and a property page project. Each builds into its own DLL. If a client wants to implement a context menu and property page, then they could both just be built into the same DLL and share the same class factory.

To accommodate the sample being built and tried without modification, the context menu handler binds to the mouse interface by default (done in Associations.reg).  In real scenarios it is recommended to bind against Hardware Ids if possible instead of interfaces.  Please see the "Devices and Printers Folder - Extensibility Guide" document on http://www.microsoft.com/whdc for complete guidance.

Context Menu

The main purpose of this project is to show how to create a context menu handler for a device that launches a custom application contextually. Important: This project shows how to implement a dynamic context menu handler which won't always be needed. If the requirement is just to launch an application statically (without context) you can just associate a static context menu handler with the device. See the "Devices and Printers Folder - Extensibility Guide" document for more information.  This project demonstrates how contextual information can be collected from the device in Devices and Printers and then use that information to launch an application. 

Command Bar

The object created in the context menu project also supports being used for the Command Bar. This sample shows how entries can be added to the Command Bar (in the Associations.reg file). Please note that Command Bar items should be used sparingly as there is limited UI real-estate for these. Only put context menu items on the Command Bar that are going to be frequently used by customers.

Property Page

The main purpose of this project is to show how to create a property page for a device with relevant contextual information about the device clicked on in Devices and Printers.

Features used in the Windows platform: Devices and Printers, Shell Extensibility Model, and SetupAPI.

 

Prerequisites

 

Languages

C++/COM

 

Folders and Files

  1. \
    1. readme.htm - This file.
    2. DeviceFolderExtensibility.sln - Visual Studio 2008 solution file. This solution file encapsulates all the projects for this sample. Each folder under the root defines a project and contains a Visual Studio project file.
    3. Associations.reg - File used to associate the property page COM object with the mouse interface for Devices and Printers. Note this file really just exists for convenience in getting the sample up and running. In real scenarios, the association would likely be performed by a driver installation package (via an INF file), or a software installation package that this object ships with.  Also, please note the actual registration of the COM object itself in Windows is done through DllRegisterServer in dllmain.cpp.
  2.  
  3.  
  4. DeviceContextMenu\
    1. CDeviceContextMenu.h - Declaration of the CDeviceContextMenu class.
    2. CDeviceContextMenuFactory.h - Declaration of the CDeviceContextMenuFactory class.
    3. common.h - Common header for all files in the project.
    4. resource.h - Resource declarations for resources contained in DeviceContextMenu.rc
    5. DeviceContextMenu.rc - Contains all the resources and layout for the device context menu.
    6. CDeviceContextMenu.cpp - Implements the CDeviceContextMenu class which includes the implementations of the standard interfaces to add property pages to the Devices and Printers property sheet: IInitializeCommand and IExplorerCommand.
    7. CDeviceContextMenuFactory.cpp - Implements the CDeviceContextMenuFactory class which is used to create CDeviceContextMenu objects.
    8. DeviceContextMenu.def - Defines the exports for the dll.
    9. DeviceContextMenu.idl - Defines the type library and CoClass for the DeviceContextMenu object.
    10. dllmain.cpp - Implements the DLL export and related functions.


  5. DevicePropertyPage\
    1. CDevicePropertyPage.h - Declaration of the CDevicePropertyPage class.
    2. CDevicePropertyPageFactory.h - Declaration of the CDevicePropertyPageFactory class.
    3. common.h - Common header for all files in the project.
    4. resource.h - Resource declarations for resources contained in DevicePropertyPage.rc
    5. DevicePropertyPage.rc - Contains all the resources and layout for the device property page.
    6. CDevicePropertyPage.cpp - Implements the CDevicePropertyPage class which includes the implementations of the required interfaces to add property pages to the Devices and Printers property sheet: IShellExt and IShellPropertySheetExt.
    7. CDevicePropertyPageFactory.cpp - Implements the CDevicePropertyPageFactory class which is used to create CDevicePropertyPage objects.
    8. DevicePropertyPage.def - Defines the exports for the dll.
    9. DevicePropertyPage.idl - Defines the type library and CoClass for the DevicePropertyPage object.
    10. dllmain.cpp - Implements the DLL export and related functions.

 

Building the Sample (using Visual Studio)

  1. Open DeviceFolderExtensibility.sln in Visual Studio.
  2. In the Build menu, select Build Solution. The application will be built in the default \Debug or \Release directory. To build debug and release for both x86 and x64, perform a Batch Build, or use the Configuration Manager to build each one.

 

Building the Sample (from SDK build environment)

  1. Open the SDK command shell.
  2. Navigate to the sample folder where DeviceFolderExtensibility.sln is located.
  3. Type vcbuild DeviceFolderExtensibility.sln. The application will be built in the default \Debug or \Release directory.

 

Running the Sample

All files can be used from the binplaced location from the build (typically \debug or \release).

  1. Register the COM objects in Windows and associate them with the mouse interface.
    1. Run Regsvr32 DeviceContextMenu.dll.
    2. Run Regsvr32 DevicePropertyPage.dll.
    3. Import Associations.reg into the registry.
       
  2. Run Devices and Printers.
    1. Open Devices and Printers by clicking Start Menu -> Devices and Printers..
    2. Because both sample objects bind to the mouse interface, the new context menu and property page should be available on all mice in Devices and Printers. (Note: if the PC has a legacy PS/2 mouse it won't be shown separately and will be grouped with the PC icon in Devices and Printers. In this case, simply load the PC's property page to see the sample).
    1. Find the mouse icon and right click on it. The new context menu entry should be seen as "Sample Item" and it should be the default (text is in bold lettering).
    2. Just highlight the mouse item now and notice the Command Bar in Devices and Printers also shows the "Sample Item" entry as well. This happens because the context menu handler object (based on IExplorerCommand as this sample is) can support the Command Bar in addition to the context menu. A few simple registry entries enables this Command Bar functionality with the object.
    3. Now go to Properties on the mouse icon.
    4. When the property sheet loads, it should contain the sample property page titled "Sample Page".

 

Removing the Sample

  1. Run Regsvr32 -u DevicePropertyPage.dll.
  2. Run Regsvr32 -u DeviceContextMenu.dll.
  3. Use Regedit to remove the entries added by Associations.reg.