Introduction



Devices and Printers – Extensibility?GuideJune 1, 2009AbstractThis document 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 paper assumes that the reader is already familiar with Devices and Printers in Windows??7. This information applies for the Windows 7 operating system.References and resources discussed here are listed at the end of this paper.The current version of this paper is maintained on the Web at: : This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS plying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.? 2009 Microsoft Corporation. All rights reserved.Microsoft, MSDN, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.The names of actual companies and products mentioned herein may be the trademarks of their respective owners.Document HistoryDateChangeJune 1, 2009Deleted “Folder” from “Devices and Printers Folder”November 5, 2008First publicationContents TOC \o "1-3" \h \z \u Introduction PAGEREF _Toc230593351 \h 3Shortcut Menus PAGEREF _Toc230593352 \h 3Static versus Dynamic Shortcut Menu Items PAGEREF _Toc230593353 \h 3Associating Shortcut Menu Items to Devices PAGEREF _Toc230593354 \h 4Associating Shortcut Menu Items to Devices Based on Model Identifier PAGEREF _Toc230593355 \h 4Associating Shortcut Menu Items to Devices Based on Hardware?Identifier PAGEREF _Toc230593356 \h 4Associating Shortcut Menu Items to Devices Based on Device Interface?Class PAGEREF _Toc230593357 \h 5Registering Shortcut Menu Items and Handlers PAGEREF _Toc230593358 \h 6Static Registration PAGEREF _Toc230593359 \h 6Specifying a Default Double-Click Action PAGEREF _Toc230593360 \h 7Property Pages PAGEREF _Toc230593361 \h 8Resources PAGEREF _Toc230593362 \h 8IntroductionIn Windows??7, developers can extend the capabilities of Devices and Printers in the following areas:Shortcut menus (also called “context menus”)Property pagesDevelopers 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 document 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 MenusA 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 do 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 ItemsTwo methods can be used to insert items into the shortcut menu for a device:StaticDynamicStatic 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 DevicesThe handlers for shortcut menu items in Devices and Printers are registered under the following registry key:HKEY_CLASSES_ROOT\DeviceDisplayObjectDevices 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 identifierHardware identifierDevice interface classWhich 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 IdentifierTo 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?IdentifierTo 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_01HKEY_CLASSES_ROOT\DeviceDisplayObject\HardwareId\USB#VID_04F9&PID_0102&MI_01In 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?ClassTo 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 HandlersEach 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 RegistrationStatic menu items are registered in the following registry key:<AssociationKey>\ShellUnder 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\Item2Both 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):MUIVerbThe 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, -ResourceIDwhere 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 ActionThe 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:1.Mark the registration of the hander with the MayChangeDefaultMenu registry key, as described in “Creating Context Menu Handlers” on MSDN.2.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\Item2DefaultAppliesTo=""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 Menu” on MSDN.Property PagesThe procedure for registering property pages for devices is similar to the procedure for registering shortcut menu items, as described previously in this paper.For more information about how to create property pages, see “Creating Property Sheet Handlers” on MSDN.ResourcesDevice Experience portal page on WHDC Menu(VS.85).aspxCreating Context Menu Handlers(VS.85).aspxMENUITEMINFO Structure(VS.85).aspxSetMenuDefaultItem Function(VS.85).aspxCreating Property Sheet Handlers(VS.85).aspx ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download