Network Explorer Extensibility

Network Explorer Extensibility - 1

June 7, 2006

Abstract

Network Explorer is the place in the Microsoft® Windows Vista™ operating system for users to discover and use all of the network resources, including network devices and computers in the local area network (LAN). From Network Explorer, users can see device-specific icons and properties and invoke device-specific actions.

This paper describes how Network Explorer discovers a network device; displays a device-specific icon, actions, and properties; and launches a device-specific application.

This paper provides information about how to implement customized device-specific icons, actions, and properties for display in Network Explorer. This paper is intended for device manufacturers of network-connected devices.

This information applies for the Windows Vista operating system.

The current version of this paper is maintained on the Web at:

References and resources discussed here are listed at the end of this paper.

Contents

Overview

Simple Extensibility

Advanced Extensibility

References

Disclaimer

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 DOCUMENT.

Complying 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.

Microsoft, MSDN, Rally, Windows, and Windows Vista 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.

Overview

Figure 1 shows the typical flow for how Network Explorer discovers a network device; displays a device-specific icon, actions, and properties; and launches a device-specific application.

Figure 1. System Architecture

The extensibility model that Network Explorer follows is based on the device identifiers (IDs) that the device announces. Network Explorer uses the IDs in the PKEY_PNPX_CompatibleTypes property to locate device extension.

The type of this property is VT_VECTOR | VT_LPWSTR.

The following defines PKEY_PNPX_CompatibleTypes.

For Web Services for Devices (WSD) devices:

PKEY_PNPX_CompatibleTypes = wsd:ThisModel/ wsd:manufacturer + "/" + wsd:ThisModel/ wsd:modelName + "/" + wsd:ThisModel/ wsd:modelNumber

PKEY_PNPX_CompatibleTypes = All wsdisco:Types provided by the device

For UPnP devices:

if (PKEY_PNPX_Installable == TRUE)

// The device contains a hardwareID or compatibleID

{

PKEY_PNPX_CompatibleTypes = All X_hardwareIDs provided by the device

PKEY_PNPX_CompatibleTypes = All X_compatibleIDs provided by the device

}

else

// The device does not contain a hardwareID or compatibleID, i.e. not installable

{

PKEY_PNPX_CompatibleTypes = manufacturer + "/" + modelName + "/" modelNumber

PKEY_PNPX_CompatibleTypes = manufacturer + "/" + modelName

PKEY_PNPX_CompatibleTypes = deviceType

}

In both cases, the IDs in PKEY_PNPX_CompatibleTypes are listed from most specific to least specific, which is the order in which Network Explorer looks for device customization information. This allows a device manufacture to customize the device at different scopes. For more information about how PKEY_PNPX_CompatibleTypes is defined, see “PnP-X: Plug and Play Extensions forWindows” on the Microsoft Windows® Rally™ technologies Web site.

Note: Network Explorer searches only for root devices and queries for the PKEY_PNPX_CompatibleTypes property of the root devices. For multifunction devices (embedded devices in UPnP cases or multiple host services in WSD cases), because Network Explorer can pass the root Function Instance of the device to the device extension, the device extension developer decides how to customize the multiple function device’s user interface (UI) in Network Explorer. To get the Function Instance of the root device, a device extension can query for the PKEY_NE_FI of the corresponding shell item of the device.

PKEY_NE_FI is defined as:

DEFINE_PROPERTYKEY(PKEY_NE_FI, 0xae54373, 0x43be, 0x4fad, 0x85, 0xe4, 0x69, 0xdc, 0x86, 0x33, 0x98, 0x6e, 14);

Because Network Explorer is a folder in the Windows shell namespace, the extensible architecture follows closely how the Windows shell defines extensibility. Two extensibility models are supported:

Simple extensibility, which defines the path of a device icon and other details by storing customization information directly in the registry. For information, see “Simple Extensibility” later in this paper.
Advanced extensibility, which allows a shell extension to be registered for a given type of device. This extension provides a device icon, context menu, and property pages. For information, see “Advanced Extensibility” later in this paper.

In both cases, the registry layout for registering the customized icon, context menu, and property page handlers are defined in the Shell Programmer’s Guide on the MSDN® Website.

Simple Extensibility

Simple extensibility does not require any code implementation. Information is stored in the registry for all of the device’s custom details such as the location of the icon and customized actions.

The following provides an example of the customization of an Internet gateway device (IGD). In this example, the IGD device has the following device type (PKEY_PNPX_DeviceType):

urn:schemas-upnp-org:device:InternetGatewayDevice:1

The following example defines a customized icon for the IGD device:

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1\DefaultIcon

Default value = netshell.dll,-1909

Note:dllname,-ResourceID points to an icon resource in a dynamic-link library (DLL).

This example adds a Configure and Open context menu for the IGD device:

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1
\ shell\Configure\command

Default value = notepad.exe %1

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1\ shell\Open\command

Default value = notepad.exe %1

In this example, the Open action launches Notepad. The value %1 is the PKEY_ PNPX_GlobalIdentity that is returned from the device’s Function Instance, which is a unique ID for the device and defined as follows:

For UPNP devices, the ID has this format:
uuid:guid_of_the_device
For devices that implement WSD, the ID has this format:
urn:uuid:guid_of_the_device

For the context menu, the following registry example sets Configure as the default action:

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1\ shell

Default value = configure

The text in the context menu can be localized. The following example shows localized text for the Configure context menu:

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1\shell\configure

MUIVerb = netshell.dll,-2001

Note: netshell.dll,-2001 is the string resource ID of the text.

For more details, see these entries in the Shell Programmer’s Guide on MSDN that describe extending the icon and context menu in Shell folders:

Customizing Icons

/shell_basics/shell_basics_extending/icon.asp
Extending Shortcut Menus

/shell_basics/shell_basics_extending/context.asp

Advanced Extensibility

Advanced extensibility requires a set of shell interfaces to be implemented as shell extensions, which are Component Object Model (COM) objects. This provides dynamic customization of the icon, context menu, and property sheet.

For the context menu, the following interfaces are required:

IContextMenu, which provides the context menu.
IShellExtInit, which is used to initialize the shell extension.

For more information, see “Creating Context Menu Handlers” on MSDN:
/shell/programmersguide/shell_int/shell_int_extending/extensionhandlers
/contextmenuhandlers.asp

For the icon, the following interfaces are required:

IExtractIcon, which provides the icon.
IPersistFile, which is used to initialize the shell extension.

For more information, see “Creating Icon Handlers” on MSDN:
/shell_int/shell_int_extending/extensionhandlers/iconhandlers.asp

For property sheets, the following interfaces are required:

IShellPropSheetExt, which provides the property sheets.
IShellExtInit, which is used to initialize the shell extension.

For more information, see “Creating Property Sheet Handlers” on MSDN:
/shell_int/shell_int_extending/extensionhandlers/propsheethandlers.asp

The following is an example of a shell extension that provides a customized context menu and property sheets:

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1\shellex
\ContextMenuHandlers\{4A1E5ACD-A108-4100-9E26-D2FAFA1BA486}

HKCR\NetworkExplorerPlugins
\urn:schemas-upnp-org:device:InternetGatewayDevice:1\shellex
\PropertySheetHandlers\{4A1E5ACD-A108-4100-9E26-D2FAFA1BA486}

Note: The globally unique ID (GUID) is the COM class identifier (CLSID) of the COM object that implements the required interfaces for context menu and property sheets.

References

Function Discovery API Reference [MSDN]
PnP-X: Plug and Play Extensions forWindows Specification [WHDC]