Multitransport Device Installation and Pnp X Out-Of-Band Association

PnP-X Out-of-Band Association - 1

Multitransport Device Installation andPnPX Out-of-Band Association

November 14, 2007

Abstract

Some types of devices—called multitransport devices—can be connected to a computer in more than one way, for example:

• Directly, by using a USB or IEEE 1394 cable.
• Over a network, typically by using an IEEE 802.11 (Wi-Fi) connection.

Plug and Play Extensions (PnP-X) out-of-band association provides a way for an installation application to install a multitransport device as a network-connected device before it is first connected to a network. This procedure bypasses the standard PnP-X association process, so that the device is installed and ready for use when it appears on the network.

This paper provides details about how to implement PnPX out-of-band association in installation applications.

This information applies to 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.

For the latest information, see:

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.

© 2007 Microsoft Corporation. All rights reserved.

Microsoft, MSDN, 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.

Contents

Introduction

Background

Multitransport Device Installation

About PnP-X

PnPX Installation

How PnP-X Installs a Network-Connected Device

Example: Installing a Network-Connected Device

PnPX Out-of-Band Association

How to Create an Out-of-Band Association

Example: Creating an Out-of-Band Association

The Function Instance ID String

Example: How to Implement an Emulated Function Instance

Call to Action

References

Appendix: CEmulatedFunctionInstance Implementation

Introduction

This paper provides information for device manufacturers, hardware engineers, and software developers about how to implement an installation application to create an out-of-band network association for a multitransport device that works with Windows Vista®.

Background

Historically, devices such as printers or external hard drives have been connected directly to the user's computer over aphysical bus such as PCI or USB and are discovered and managed by the Plug and Play (PnP) manager. However, many computers now also use network-connected devices—such as network printers or Wi-Fi-enabled music players—that are accessed through a network connection rather than through a physical bus.

Network Explorer is a component of the Windows Vistashell that gives the user easy access to available local network resources. It replacesNetwork Neighborhood in earlier versions of Windows®. When the computer is connected to a network, Network Explorer discovers the resources available on the local network. In particular, Network Explorer discovers all available network-connected devicesand displays an icon for each one. By right-clicking an icon, a user can obtain properties and perform device-related actions.

Network Explorer uses the Function Discovery API to discover the available network-connected devices and displays an icon for each device. If directed by the user, Network Explorer uses Plug and Play Extensions (PnPX) to install drivers for the device, providing an installation experience that is similar to what users encounter when they connect a new device directly to their computer.

PnP-X uses a virtual bus to represent the network-connected devices to the PnP manager as bus-connected devices. The PnP manager can then manage the network-connected devices in much the same way as it manages standard bus-connected devices.Aftera network-connected device is installed, it is managed by the PnP manager. The device is assigned a devnode in the Plug and Play device tree and appears in Device Manager alongside those devices that are connected to a physical bus.

Multitransport Device Installation

Some types of devices—called multitransport devices—can be connected to a computer in more than one way, for example:

• Directly, by using a USB or IEEE 1394 cable.
• Over a network, typically by using an IEEE 802.11 (Wi-Fi) connection.

Examples of multitransport devices include the Microsoft® Zune®digital media player and some digital still cameras that can be connected by using either USB or WiFi.

In the ideal scenario, after Network Explorer discovers a multitransport device on the local network, the user can start using the device immediately. However, to make this scenario possible, the device must already be installed as a network-connected device.

PnP-X out-of-band association provides a way for aninstallation application to install a multitransport device as a network-connected device before it is first connected to a network. This procedure bypasses the standard PnP-X association process, so that the device is installed and ready for use when it appears on the network.

This paper provides details about how to implement PnPX out-of-band association in installation applications.

About PnP-X

PnP-X consists of three components:

• An association database that contains the data for network-connected devices.
• An IP bus enumerator that serves as a virtual bus for network-connected devices.
• A set of network discovery providers, each of which implements a discovery protocol that can be used to discover network-connected devices.

Windows Vista provides programmatic user-mode access to PnP-X functionality through two new COM-based APIs that are used by Network Explorer and are available for applications:

• The Function Discovery API is used to enumerate system resources, including network-connected devices.For details, see "Function Discovery" in the MSDN® Library.
• The PnP-X association API provides access to the PnPX association database andcan be used to install network-connected devices. For details, see "PnPX Association Database Reference" in the MSDN Library.

The Function Discovery API depends on network discovery providers to enumerate network-connected devices. Windows Vista provides PnPX–compliant network discovery providers for two protocols:

• Simple Service Discovery Protocol (SSDP).
• Devices Profile for Web Services (DPWS), which is implemented as WSDiscovery for Web Services on Devices in Windows Vista.

Independent hardware vendors (IHVs) can also install third-party discovery protocols.

Before discussing how aninstallation application can use these APIsto create an out-of-band association, it is useful to first examine how Network Explorer uses them to discover and install network-connected devices.

Figure 1. Discovering network-connected devices

Figure 1 shows how Network Explorer discovers and installs network-connected devices:

1.Network Explorer uses the Function Discovery API to query for network-connected devices.

2.Function Discovery calls the underlying network discovery providers, whichdiscover the available devices on the local network and retrieve their metadata.

3.The discovery providers create a function instance for each available network-connected device and Function Discovery returns the function instance to Network Explorer.

4.Network Explorer displays an icon for each device.

5.If a device is installable but not yet installed, the user can direct Network Explorer to install it by double-clicking the icon.

Network Explorer uses the function instance and the PnP-X Association API to create an entry in the PnP-X association database and associate the device.

6.After a device is associated, when it is discovered on the network, PnPX automatically installs the device.

7.After a device is installed, the user might be able to right-click the device icon in Network Explorer to run device-specific applications. The available actions depend on the particular device and the installed software.

For more information about Network Explorer see "Network Infrastructure: Overview" on MSDN.For information on the related extensibility model, see "Network Explorer Extensibility" on the WHDC Web site.

PnPX Installation

To understand PnP-X out-of-band association, it is useful to first look at the standard PnP-X installation process. When Network Explorer firstdiscovers a network-connected device, it creates a function instance for the device and displays an icon, but does not installthe device. The device is typically installed when a user right-clicks the icon and directs Network Explorer to install the device, although applications can also start the installation process.

How PnP-X Installs a Network-Connected Device

When a user directs Network Explorer to install a network-connected device, Network Explorer uses the function instance and the PnP-X Association APIto create an association entry in the PnPX association database. PnP-X then installs the device, as follows:

1.TheIP bus enumerator retrieves Plug and Play–related metadata for the device, such as hardware IDs and compatible IDs.

2.The IP bus enumerator creates a physical device object (PDO) and sends a request to the PnP manager to create a devnode for the device.

3.The PnP manager creates the devnode and attempts to install a device stack on top of the PDO, as follows:

• If a compatible device driver is available on the system, the PnP manager creates a device stack and installs the device.
• If no compatible driver is available, the PnP manager runs the Found New Hardware Wizard so the user can install appropriate drivers.

Note: Windows Vista supports PnPX installation for devices that support either SSDP or the WS-Discovery protocol and meet the minimum PnPX requirements. For guidelines and details about these requirements, see "PnPX: Plug and Play Extensions for Windows Specification" on the WHDC Web site.

Example: Installing a Network-Connected Device

The following code sample is an example of a function (DeviceInstallUninstall) that uses the PnP-X Association API to install or uninstall a network-connected device.The example assumes that the application has already used the Function Discovery API to obtain the device's function instance.The procedure is similar to that used by Network Explorer.

HRESULT DeviceInstallUninstall( IFunctionInstance *pIFunInst )

{

HRESULT hr = S_OK;

IPropertyStore *pIPStore = NULL;

IPNPXAssociation *pIPNPXAssociation = NULL;

PROPVARIANT propvar;

bool bPNPXInstallable = false;

PropVariantInit( &propvar );

hr = pIFunInst->OpenPropertyStore( STGM_READ, &pIPStore );

//Check whether the device is installable

if ( S_OK == hr )

hr = pIPStore->GetValue( PKEY_PNPX_Installable, &propvar );

if ( S_OK == hr & VT_BOOL != propvar.vt )

hr = E_FAIL;

if ( S_OK == hr )

bPNPXInstallable = ( VARIANT_TRUE == propvar.boolVal ) ? true : false;

PropVariantClear( &propvar );

if ( bPNPXInstallable )

{

//Get the instance's IPNPXAssociation interface

if ( S_OK == hr )

hr = pIPStore->GetValue( PKEY_PNPX_Associated, &propvar );

if ( S_OK == hr & VT_BOOL != propvar.vt )

hr = E_FAIL;

if ( S_OK == hr )

hr = pIFunInst->QueryService(SID_PNPXAssociation,

__uuidof( IPNPXAssociation ),

reinterpret_cast<LPVOID*>( &pIPNPXAssociation ));

//If the device is already installed, delete it. Otherwise, install it

if ( S_OK == hr )

{

if ( VARIANT_TRUE == propvar.boolVal ) //Installed

{

hr = pIPNPXAssociation->Delete( NULL ); // Unassociate it

fputws( L"Unassociated the Device\r\n", stdout );

}

else //Not installed

{

hr = pIPNPXAssociation->Associate( NULL ); // Associate it

fputws( L"Associated the Device\r\n", stdout );

}

}

}

// cleanup

PropVariantClear( &propvar );

if ( pIPStore )

pIPStore->Release();

if ( pIPNPXAssociation )

pIPNPXAssociation->Release();

return hr;

}

As shown in the preceding example,an application uses the following procedure to install a network-connected device:

1.Obtain the device's function instance. In this example, the DeviceInstallUninstall function receives a pointer to the function instance's IFunctionInstance interface through the parameter list.

2.To obtain a pointer to the function instance's IPropertyStore interface, callIFunctionInstance::OpenPropertyStore.

3.To check whether the device is installed,callIPropertyStore::GetValue to get the function instance's PKEY_PNPX_Associated property key. This key records whether the device is associated.

4.To get a pointer to the function instance's IPNPXAssociation interface,callIFunctionInstance::QueryService.

5.If the device is not yet installed, to create an entry for the device in the PnP-X database and initiate the installation process,callIPNPXAssociation::Associate.

The procedure for uninstalling a device is identical, except for step 5. In that step,the application callsIPNPXAssociation::Delete to delete the device.

PnPX Out-of-Band Association

As discussed earlier, the standard PnP-X installation process uses the device's function instance to create an entry for the device in the PnP-X association database, which initiates the installation process. However, Network Explorer creates that function instance when it discovers the device on the local network. If the device has not yet been connected to the network, nosuch function instance exists.

The installation application for a multitransport device can create an out-of-band association for the device, whichassociates the device as a network-connected device before it is connected to the network.This procedure bypasses the standard PnP-X association process, so that when the device is discovered on the network, it is automatically installed and ready for use.

How to Create an Out-of-Band Association

To take advantage of out-of-band association capabilities in Windows Vista,a user must first connect the device directly to the computer, for example, by using a USB cable. The installation application, in addition to the usual procedures for installing USB drivers and so on, also creates a PnP-X out-of-band association for the device, as follows:

1.The installation application creates an object that emulates the function instance objects that the Function Discovery API created.

The emulated function instance returns the same PnP-X association metadata that the device provides to the network discovery providers during the discovery process.

2.The installation application uses the emulated function instance and the PnP-X Association API to create an entry for the device in the PnP-X association database.

The PnP-X association database entry is indistinguishable from the entry that would be created by the standard PnP-X installation process discussed earlier.

3.Creating the database entry initiates the PnP-X device installation process.

As a result of this out-of-band association, when Network Explorer discovers the device on the network, PnP-X automatically installs it and makes it ready for use.

Note: To use PnP-X out-of-band association to associate a network-connected device, your installation package must also provide the supporting files that are required for a standard PnP-X installation, including an INF. For details, see "PnPX: Plug and Play Extensions forWindows Specification" on the WHDC Web site.

Example: Creating an Out-of-Band Association

The following example shows how aninstallation application can create an out-of-band PnP-X association for a device:

HRESULT OutOfBandPnpXAssociation ()

{

HRESULT hr;

CEmulatedFunctionInstance oFunInst;

CComPtr<IUnknown> spUnk;

CComPtr<IPNPXAssociation> spPNPXAssociation;

hr = spUnk.CoCreateInstance( SID_PNPXAssociation );

if ( S_OK == hr )

{

IFunctionDiscoveryServiceProvider *pIFDServiceProvider;

hr = spUnk->QueryInterface(__uuidof(IFunctionDiscoveryServiceProvider ),

reinterpret_cast<LPVOID*>( &pIFDServiceProvider ));

if ( S_OK == hr )

{

hr = pIFDServiceProvider->Initialize(&oFunInst, __uuidof( IPNPXAssociation ),

reinterpret_cast<LPVOID*>( &spPNPXAssociation ));

pIFDServiceProvider->Release();

}

}

if ( S_OK == hr )

hr = spPNPXAssociation->Associate( NULL );

return hr;

}

As shown in the preceding example, an application uses the following procedure to create an out-of-band association:

1.Instantiate an emulated function instance object. For a discussion of how to implement this object, see "Example: How to Implement an Emulated Function Instance" later in this paper.

2.To create an instance of the PnP-X association service provider, call CoCreateInstance.

Note: The PnP-X association service must have elevated privileges to add an entry to the database. If this code is not running in a process that has elevated privileges, use the following function call to create the service:

hr = CoCreateInstanceAsAdmin(NULL,

SID_PNPXAssociation,

__uuidof(IPNPXAssociation ),

reinterpret_cast<LPVOID*>( &spUnk ));

3.To obtain a pointer to the PnP-X association service's IFunctionDiscoveryServiceProvider interface,callthe object's QueryInterface method.

4.To initialize anew PnP-X association object,pass the emulated function instance object toIFunctionDiscoveryServiceProvider::Initialize.

The Initialize method returns a pointer to the PnP association object's IPNPXAssociation interface.

5.To Create a PnP-X association database entry and enable the installation process,callIPNPXAssociation::Associate.

The Function Instance ID String

The function instance ID is the core ofan emulated function instance object. This string includes the metadata that allows a Function Discovery instance to construct a query for a particular device, including which network discovery provider should be used.