Devices and printers extensibility guide
This topic provides important information for developers who want to extend the user experience in Devices and Printers for their particular application or device, or for a particular device class. This topic assumes that the reader is already familiar with Devices and Printers in Windows 7.
Introduction
In Windows 7, developers can extend the capabilities of Devices and Printers in the following areas:
- Shortcut menus (also called “context menus”)
- Property pages
Developers who are already familiar with the shell programming model will discover that extending the capabilities of Devices and Printers is consistent with extending other shell folders in Windows. This content is not intended to be a complete developer’s guide. Instead, it is a source of guidelines and supplemental information that goes beyond what is provided on the MSDN® Web site for developers who are interested in extending the Devices and Printers information.
Shortcut menus
A shortcut menu is the pop-up menu that appears when users right-click a device icon in Devices and Printers. The shortcut menu functions like a small Start menu for the device that lets users see what actions they can perform with the device. The menu is contextual, which means that the menu items that appear on the list depend on the particular device that the user selected. The shortcut menu for all devices contains at list one menu item—Properties—that lets users view the properties of the device. Developers can insert additional menu items on demand, based on the specific capabilities and properties of their device.
Static versus dynamic shortcut menu items
Two methods can be used to insert items into the shortcut menu for a device:
- Static
- Dynamic
Static shortcut menu items are specified in the Windows registry and do not require implementing any code. Therefore, static items are easier to add to a device's shortcut menu than dynamic items, which require implementing code. However, static shortcut menu items are more limited as to how they behave and how they describe themselves to users. The best choice of the type of shortcut menu item depends on the application requirements. A dynamic shortcut menu item is not necessarily a better choice than a static shortcut menu item just because it provides more capabilities. With static shortcut menu items, a developer can describe the shortcut menu item declaratively by using registry entries. In this situation, the menu item text and the action to be performed when the user clicks the item cannot change in response to runtime evaluation of the device selection in Devices and Printers. This is why it is called a static shortcut menu item. Using static shortcut menu items is appropriate in the following example scenarios:
- Starting an application for a device.
- Starting a Control Panel application for a device that contains a device interface that belongs to a specific device class.
Associating shortcut menu items to devices
The handlers for shortcut menu items in Devices and Printers are registered under the following registry key:
HKEY_CLASSES_ROOT\DeviceDisplayObject
Devices and Printers supports associating shortcut menu items to a particular device or to a group of devices that are based on the following device properties:
- Model identifier
- Hardware identifier
- Device interface class
Which method to use depends on the specific scenario and application requirements. Device vendors who want to add a shortcut menu item for a specific device can associate the menu item to the device that is based on the model identifier or the most specific hardware identifier of the device. If a device vendor wants to add a shortcut menu item for a family of devices or all the devices that the vendor manufacturers, the vendor can use a less specific hardware identifier.
However, third-party software vendors typically want to associate shortcut menu items to devices based on device interface class. They are not usually interested in a particular model of device. Instead, they are typically interested in devices that provide specific functionality, such as storage devices, keyboard devices, or mouse devices.
Associating shortcut menu items to devices based on model identifier
To associate shortcut menu items to devices that match a specific model identifier, create the following key in the registry:
HKEY_CLASSES_ROOT\DeviceDisplayObject\ModelId\<ModelId>
where <ModelId> is the model identifier for the device, expressed as a globally unique identifier (GUID).
The following example shows the registry key for associating shortcut menu items with devices that match a specific model identifier:
HKEY_CLASSES_ROOT\DeviceDisplayObject\ModelId\{33229262-74CE-5122-DD20-00A0C993C555}
Associating shortcut menu items to devices based on hardware identifier
To associate shortcut menu items to devices that match a specific hardware identifier, create the following key in the registry:
HKEY_CLASSES_ROOT\DeviceDisplayObject\HardwareId\<HardwareId>
where <HardwareId> is a string that specifies the hardware identifier for the device.
Because devices usually contain multiple hardware identifiers that range from least specific to very specific, the developer decides which hardware identifier to use, depending on the application requirements. Some hardware identifiers can be very general and can match several devices from different device vendors. If this is the intent, associating shortcut menu items to devices based on device interface class is probably a better solution. However, if associating shortcut menu items with a specific model of a device is intended, the most specific hardware identifier should be used only if the device does not support a model identifier.
Because Devices and Printers supports multifunction devices, a device can have multiple device functions, each with its own set of hardware identifiers. When associating shortcut menu items to devices that are based on hardware identifier, an association match occurs when the hardware identifier that is specified in the registry matches any one of the hardware identifiers for any of the device functions that are in the device.
Note
Because hardware identifiers can contain backslash characters (\), which are prohibited when specifying registry key names, the number sign character (#) must be used instead of the backslash character when specifying a hardware identifier.
The following examples show the registry keys for associating shortcut menu items with devices that match specific hardware identifiers:
HKEY_CLASSES_ROOT\DeviceDisplayObject\HardwareId\USB#VID_04F9&PID_0102&REV_0100&MI_01
HKEY_CLASSES_ROOT\DeviceDisplayObject\HardwareId\USB#VID_04F9&PID_0102&MI_01
In this example, the second entry is less specific than the first. Again, the correct choice of hardware identifier depends on the application requirements.
Associating shortcut menu items to devices based on device interface class
To associate shortcut menu items to devices that match a specific device interface class, create the following key in the registry:
HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\<InterfaceClass>
where <InterfaceClass> is an identifier for the device interface class, expressed as a GUID.
The following examples show the registry keys for associating shortcut menu with devices that match specific device interface classes:
HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{02B12962-5CEC-11D2-AA20-00A0C993C932}
HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{6BDD1FC6-810F-11D0-BEC7-08002BE2092F}
The identifier of the device interface class represents the Windows Plug and Play device interface class identifier for the interface. Individual device functions can expose multiple device interfaces, each of which belongs to a specific device interface class, such as USB, human interface device (HID), keyboard, mouse, or storage. Because Devices and Printers supports multifunction devices, where each device function can have multiple device interfaces, it is common for devices to have several device interfaces. Like hardware identifiers, an association match occurs when the device interface class that is specified in the registry matches any one of the device interfaces that the device exposes for any of the device functions in the device.
Registering shortcut menu items and handlers
Each association registry key (discussed previously) contains information about what shortcut menu items to display and what handlers to run for the matching devices. These registry keys include information for both static and dynamic shortcut menu items. Multiple shortcut menu items and the associated handlers can be specified in each key.
Static registration
Static menu items are registered in the following registry key:
<AssociationKey>\Shell
Under this key, each subkey represents a static shortcut menu item. The name of the subkey represents is the static menu item identifier, which is used for specifying the default text that the user sees for the menu item if a localized string reference is not provided.
For example, the following specifies two static menu items, Item1 and Item2:
<AssociationKey>\Shell\Item1
<AssociationKey>\Shell\Item2
Both Item1 and Item2, in this example, represent static shortcut menu items that always appear for matching devices.
The following value under each static menu item entry specifies the localized string to use for the verb (the text that users see for the menu item):
MUIVerb
The value is a string value (REG_EXPAND_SZ) that specifies the location of the string resource that is be used in naming the verb. The string is in the following format:
Dllname, -ResourceID
where Dllname is the name of the DLL that contains the string resource, and ResourceID is the numeric value of the string resource within the DLL.
Developers should avoid specifying hardcoded paths to standard system folders—such as System or Program Files—and use well-known environment variables instead—such as %SystemRoot% or %ProgramFiles%. The Windows shell expands these at runtime. If the resource DLL is in the search path, specifying the full path to the DLL is unnecessary.
The following are examples of good and bad entries for the same resource:
MUIVerb ="c:\windows\system32\acme.dll, -1001"(Bad)
MUIVerb ="%SystemRoot%\System32\acme.dll, -1001"(Good)
MUIVerb ="acme.dll, -1001"(Good)
Under each registry key that specifies a static shortcut menu item, a subkey that is named Command contains information about the action to take when the user selects that shortcut menu item for a device. The action to take is specified in the (Default) value of the Command subkey. This value is set to a string value (REG_EXPAND_SZ), which contains the command-line equivalent for the program to run, as shown in the following example:
(Default) ="%SystemRoot%\System32\notepad.exe”
The following provides a complete example of static shortcut menu items for devices that match a particular device interface class:
[HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{02B12962-5CEC-11D2-AA20-00A0C993C932}]
[HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{02B12962-5CEC-11D2-AA20-00A0C993C932}\Shell\Item1]
MUIVerb=”acme.dll, -1000”
[HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{02B12962-5CEC-11D2-AA20-00A0C993C932}\Shell\Item1\Command]
@=”rundll32.exe acme.dll Do_Item1”
[HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{02B12962-5CEC-11D2-AA20-00A0C993C932}\Shell\Item2]
MUIVerb=”acme.dll, -1001”
[HKEY_CLASSES_ROOT\DeviceDisplayObject\InterfaceClass\{02B12962-5CEC-11D2-AA20-00A0C993C932}\Shell\Item2\Command]
@=”rundll32.exe acme.dll Do_Item2 TestArg”
In this example, two items appear on the shortcut menu when the user right-clicks a device that matches the device interface class {02B12962-5CEC-11D2-AA20-00A0C993C932}: one for Item1 and one for Item2, and whose verbs (the text that appears on the shortcut menu for each item) are described in Acme.dll by using resource identifiers -1000 and -1001. The action that is taken when the user selects one of these shortcut menu items is that Rundll32.exe is invoked to call the Do_Item1 and Do_Item2 entry points that are exposed by Acme.dll. Note that in this example, Do_Item2 is shown accepting an argument for the case of the Item2 shortcut menu item.
Specifying a default double-click action
The default shortcut menu item specifies the default action that occurs when a user double-clicks a device in Devices and Printers. The default shortcut menu item always appears in bold font for the benefit of the user.
When developers write a shortcut menu handler, that handler can programmatically specify which item is the default shortcut menu item. Developers do this by following these steps:
- Mark the registration of the hander with the MayChangeDefaultMenu registry key, as described in Creating Context Menu Handlers.
- Add code to set the shortcut menu item as the default item by using one of the following two methods:
- Set MSF_DEFAULT in the fState member of the MENUITEMINFO structure for the default menu item.
- Call the SetMenuDefaultItem function.
For the case of static shortcut menu items, the following example shows how to specify a default action:
<AssociationKey>\Shell\Item1
<AssociationKey>\Shell\Item2
DefaultAppliesTo=""
As this example shows, simply adding a single string value (RES_SZ) that is named DefaultAppliesTo to the shortcut menu item key sets the associated menu item to be the default menu item in the shortcut menu. In this example, the Item2 menu item is set to be the default menu item.
For more information about how to create shortcut menu items, see Context Menus.
Property pages
The procedure for registering property pages for devices is similar to the procedure for registering shortcut menu items, as described previously in this topic.
For more information about how to create property pages, see Property Sheet Handlers.
Related topics