250 lines
13 KiB
HTML
250 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Devices and Printers Folder Extensibility Sample</title>
|
|
<style type="text/css">
|
|
.style1
|
|
{
|
|
font-family: Calibri;
|
|
}
|
|
.style2
|
|
{
|
|
color: #FF0000;
|
|
font-weight: bold;
|
|
font-style: italic;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body style="font-family: Calibri">
|
|
<p>
|
|
<span style="font-size: 18pt; color: #0000cc; font-family: Calibri"><strong>Devices
|
|
and Printers Folder Extensibility Sample</strong></span></p>
|
|
<p>
|
|
<span style="font-family: Calibri">Last Updated: March 2009</span></p>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Demonstrates</strong></span></p>
|
|
<p>
|
|
<span style="font-family: Calibri">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.</span></p>
|
|
<p>
|
|
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
|
|
<a href="http://www.microsoft.com/whdc">http://www.microsoft.com/whdc</a> for
|
|
complete guidance. </p>
|
|
<p>
|
|
<b>Context Menu</b></p>
|
|
<p style="margin-left: 40px">
|
|
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.<i> </i>
|
|
<span class="style2">Important:</span><i> 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. </i>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. </p>
|
|
<p>
|
|
<b>Command Bar</b></p>
|
|
<p style="margin-left: 40px">
|
|
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.</p>
|
|
<p>
|
|
<b>Property Page </b>
|
|
</p>
|
|
<p style="margin-left: 40px">
|
|
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.</p>
|
|
<p>
|
|
<span style="font-family: Calibri"><b>Features used in the Windows platform</b>:
|
|
Devices and Printers, Shell Extensibility Model, and SetupAPI.</span></p>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Prerequisites</strong></span></p>
|
|
<ul>
|
|
<li><span style="font-family: Calibri">This sample requires Windows 7 or later to
|
|
run.</span></li>
|
|
<li class="style1">Visual Studio 2008 is needed to edit the Solution and Projects.</li>
|
|
<li class="style1">Sample supports x86 and x64.</li>
|
|
</ul>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Languages</strong></span></p>
|
|
<p>
|
|
<span style="font-family: Calibri">C++/COM</span></p>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Folders
|
|
and Files</strong></span></p>
|
|
<ol style="list-style-position: outside; list-style-type: none;">
|
|
<li><span style="font-family: Calibri"><strong>\ </strong></span></li>
|
|
<ol style="list-style-type: none;">
|
|
<li><span style="font-family: Calibri"><strong>readme.htm </strong>- This file. </span>
|
|
</li>
|
|
<li><span style="font-family: Calibri"><strong>DeviceFolderExtensibility.sln</strong>
|
|
- 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. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>Associations.reg</strong> - 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.</span></li>
|
|
</ol>
|
|
<li><span style="font-family: Calibri"><strong> </strong></span></li>
|
|
<li><span style="font-family: Calibri"><strong> </strong></span></li>
|
|
<li><span style="font-family: Calibri"><strong>DeviceContextMenu\ </strong></span>
|
|
</li>
|
|
<ol style="list-style-type: none;">
|
|
<li><span style="font-family: Calibri"><strong>CDeviceContextMenu.h</strong> - Declaration
|
|
of the CDeviceContextMenu class. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>CDeviceContextMenuFactory.h</strong>
|
|
- Declaration of the CDeviceContextMenuFactory class. </span></li>
|
|
<li><b>common.h</b> - Common header for all files in the project.</li>
|
|
<li><b>resource.h</b> - Resource declarations for resources contained in
|
|
DeviceContextMenu.rc</li>
|
|
<li><b>DeviceContextMenu.rc</b> - Contains all the resources and layout for the device
|
|
context menu. </li>
|
|
<li><span style="font-family: Calibri"><strong>CDeviceContextMenu.cpp</strong> -
|
|
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. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>CDeviceContextMenuFactory.cpp</strong>
|
|
- Implements the CDeviceContextMenuFactory class which is used to create CDeviceContextMenu
|
|
objects. </span></li>
|
|
<li><b>DeviceContextMenu</b><span style="font-family: Calibri"><strong>.def</strong>
|
|
- Defines the exports for the dll. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>DeviceContextMenu.idl</strong> - Defines
|
|
the type library and CoClass for the DeviceContextMenu object. </span></li>
|
|
<li><b>dllmain.cpp</b> - Implements the DLL export and related functions.<br />
|
|
<br />
|
|
<br />
|
|
</li>
|
|
</ol>
|
|
<li><span style="font-family: Calibri"><strong>DevicePropertyPage\ </strong></span>
|
|
</li>
|
|
<ol style="list-style-type: none;">
|
|
<li><span style="font-family: Calibri"><strong>CDevicePropertyPage.h</strong> - Declaration
|
|
of the CDevicePropertyPage class. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>CDevicePropertyPageFactory.h</strong>
|
|
- Declaration of the CDevicePropertyPageFactory class. </span></li>
|
|
<li><b>common.h</b> - Common header for all files in the project.</li>
|
|
<li><b>resource.h</b> - Resource declarations for resources contained in DevicePropertyPage.rc</li>
|
|
<li><b>DevicePropertyPage.rc</b> - Contains all the resources and layout for the device
|
|
property page. </li>
|
|
<li><span style="font-family: Calibri"><strong>CDevicePropertyPage.cpp</strong> -
|
|
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. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>CDevicePropertyPageFactory.cpp</strong>
|
|
- Implements the CDevicePropertyPageFactory class which is used to create CDevicePropertyPage
|
|
objects. </span></li>
|
|
<li><b>DevicePropertyPage</b><span style="font-family: Calibri"><strong>.def</strong>
|
|
- Defines the exports for the dll. </span></li>
|
|
<li><span style="font-family: Calibri"><strong>DevicePropertyPage.idl</strong> - Defines
|
|
the type library and CoClass for the DevicePropertyPage object. </span></li>
|
|
<li><b>dllmain.cpp</b> - Implements the DLL export and related functions.</li>
|
|
</ol>
|
|
</ol>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Building
|
|
the Sample (using Visual Studio)</strong></span></p>
|
|
<ol>
|
|
<li><span style="font-family: Calibri">Open DeviceFolderExtensibility.sln in Visual
|
|
Studio. </span></li>
|
|
<li><span style="font-family: Calibri">In the Build menu, select <strong>Build Solution</strong>.
|
|
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.</span></li>
|
|
</ol>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Building
|
|
the Sample (from SDK build environment)</strong></span></p>
|
|
<ol>
|
|
<li><span style="font-family: Calibri">Open the SDK command shell. </span></li>
|
|
<li><span style="font-family: Calibri">Navigate to the sample folder where DeviceFolderExtensibility.sln
|
|
is located. </span></li>
|
|
<li><span style="font-family: Calibri">Type <strong>vcbuild DeviceFolderExtensibility.sln</strong>.
|
|
The application will be built in the default \Debug or \Release directory. </span>
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Running
|
|
the Sample</strong></span></p>
|
|
<p>
|
|
<span style="font-family: Calibri">All files can be used from the binplaced location
|
|
from the build (typically \debug or \release).</span></p>
|
|
<ol>
|
|
<li><span class="style1">Register the COM objects in Windows and associate them with
|
|
the mouse interface.</span><ol style="list-style-type: lower-alpha;">
|
|
<li>Run <b>Regsvr32 DeviceContextMenu.dll</b>.</li>
|
|
<li>Run <b>Regsvr32 DevicePropertyPage.dll</b>.</li>
|
|
<li>Import <b>Associations.reg</b> into the registry.<br />
|
|
<br />
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li><span style="font-family: Calibri">Run Devices and Printers. </span>
|
|
<ol style="list-style-type: lower-alpha;">
|
|
<li><span style="font-family: Calibri">Open Devices and Printers by clicking <strong>
|
|
Start Menu </strong>-> <strong>Devices and Printers</strong>.. </span></li>
|
|
<li>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. (<i><b>Note</b>: 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</i>).</li>
|
|
</ol>
|
|
</li>
|
|
<ol style="list-style-type: lower-alpha;">
|
|
<li>Find the mouse icon and right click on it. The new context menu entry should be
|
|
seen as "<b>Sample Item</b>" and it should be the default (text
|
|
is in bold lettering).</li>
|
|
<li>Just highlight the mouse item now and notice the Command Bar in Devices and
|
|
Printers also shows the "<b>Sample Item</b>" 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.</li>
|
|
<li><span style="font-family: Calibri">Now go to <b>Properties</b> on the mouse icon.
|
|
</span></li>
|
|
<li><span style="font-family: Calibri">When the property sheet loads, it should contain
|
|
the sample property page titled "<b>Sample Page</b>".</li>
|
|
</ol>
|
|
</ol>
|
|
<p>
|
|
</p>
|
|
<p>
|
|
<span style="font-size: 14pt; color: #0000cc; font-family: Calibri"><strong>Removing
|
|
the Sample</strong></span></p>
|
|
<ol>
|
|
<li><span style="font-family: Calibri">Run <b>Regsvr32 -u</b> <b>DevicePropertyPage.dll</strong></b>.</span></li>
|
|
<li>Run <b>Regsvr32</b> <b>-u</b> <b>DeviceContextMenu.dll</b>.</li>
|
|
<li><span style="font-family: Calibri">Use <b>Regedit</b> to remove the entries added
|
|
by <b>Associations.reg</b>. </span></li>
|
|
</ol>
|
|
<p>
|
|
</p>
|
|
</body>
|
|
</html>
|