Microsoft Corporation
May 2002
Applies To:
Microsoft Windows XP
Microsoft Device Host API for UPnP Devices
Summary: This article discusses how to create PC-based Universal Plug and Play devices and bridges using the Microsoft Device Host API for UPnP Devices. (6 printed pages)
Contents
Introduction
Device Host Scenarios
Leveraging the Device Host API
Security Considerations
Device Host COM Object Model
Summary
For More Information
Introduction
As more devices are networked, there is an increasing interest in sharing these devices and the resources and services provided through them. Transparent visibility and availability of all networked resources throughout the network was a complex task until Universal Plug and Play enabled devices arrived. Microsoft® Windows® XP includes UPnP technology through a Control Point API, allowing the PC to control these devices. In addition, Windows XP also allows developers to build compliant UPnP devices through a device host API.
UPnP technology provides support for communication between "control points" and devices and services. XML descriptions of devices and the associated services can be defined and published using UPnP technology. Control points, for example an application using the control point API in Windows XP, can then discover the devices and use information from these descriptions to control or subscribe to the services provided.
The network media, the TCP/IP protocol suite and HTTP provide basic network connectivity and addressing requirements for building a compliant UPnP device. On top of these open, standard, Internet-based protocols, UPnP technology defines a set of HTTP servers to handle device discovery, description, control, events, and presentation.
There are additional devices, services, and resources on or connected to the PC that are not network or UPnP technology aware, examples of which are listed below. Windows XP supports the Microsoft Device Host API that will expose these types of devices or resources through UPnP technology on the Microsoft Windows Platform. The developer need only implement the functionality for the device or service and can then leverage the Device Host API and supporting protocols to expose this functionality as a compliant UPnP device.
This article lists examples of resources that can be exposed with UPnP technology with the Device Host API, and discusses how to implement the Device Host API objects. For more information on the Control Point API for UPnP devices, see Universal Plug and Play. Additional information on the Device Host API will be published in a future Platform SDK release.
Device Host Scenarios
As the PC grows into the central point of the network, providing richer media and connectivity services, many new scenarios can be envisioned where resources on or connected to the PC can be made transparently available to the network. The following examples are just a few of the many possibilities.
Connecting Networks
Many homes have existing Home Control networks such as X10 networks that can be used to control and monitor the environmental, lighting, security, and other home devices. These networks may be connected to the PC, but may not be accessible outside of that PC. Bridging these networks to a network with UPnP devices provides users more control from more places through device hosting. Implementation can be completed without expensive upgrades to existing cabling and equipment and all devices in the X10 network will appear as UPnP devices and can communicate with and be controlled by control points on the network.
Digital Music Jukebox
Digitizing of music and other audio for playback on the PC and other devices has grown exponentially over the past several years. Many times the PC, or several PCs in the house are used to store these audio files. With the Device Host API, these music libraries, distributed across PCs, can be exposed as UPnP applications (or devices). These devices are then discoverable and controllable from other control points such as PCs, UPnP receivers, or boom boxes. These control points could route the music to any set of speakers in the home.
Picture Library
Many people now use digital cameras to take pictures, and upload these pictures onto their computers to categorize them, view them as slide shows, and so on. With device host APIs, this process can be taken one step further. The picture library itself can be exposed as a "device," which advertises its presence on the network, making it available to both applications, such as a slide show, and devices, such as an electronic picture frame, set-top boxes, and television sets.
Leveraging the Device Host API
Once the functionality to be hosted is implemented with the Device Host API, the developer need do little more than create an XML description of the device and service; the Device Host API exposes interfaces that enable connectivity using UPnP technology. All of the core UPnP protocols necessary for discovery, description, control and eventing are provided through the API and are abstracted.
The Device Description
All UPnP devices require an XML document that describes each of the devices and services to be provided by the device. This document is written using the UPnP template language (UTL) that is described in Universal Plug and Play Device Architecture. Among other information about each device, device descriptions also contain pointers to the service descriptions for that device.
Since Windows is hosting the device and provides support for eventing and control, some of the fields in the description document specified in the UPnP Device Architecture are different than they would be for a stand-alone device. For example, the URLs that are used for eventing and control in a stand-alone device are not provided in the description, but are filled in by Windows.
Implementing the Service and Device Control Objects
A device is a container for services. Each service contains state variables that describe its state, and actions that can be called upon to control the service. These state variables and actions are discussed in Universal Plug and Play Device Architecture and define how control points can interact with UPnP devices.
For each exposed service, hosted devices must provide a COM object, called a service object, which implements the interfaces described in the service descriptions for that device. The Device Host API includes a tool called utl2idl that can be used to translate from the XML service description to an IDL file. A COM object must be created to provide the functionality for each interface and to handle errors.
The developer must also implement a device control object to serve as the central point of control for the device's service objects. The device control object is passed to the Device Host API when the device registers, and is called to obtain service objects when service is requested by a control point. One device control object must be provided to support all of the nested devices and services.
Hosted Device Registration
In order for the Device Host to publish a device and announce its presence on the network, the device object and XML device description must be registered with the Device Host API.
When registered, the device will be published and announced immediately, but the device code may not immediately be loaded. Whether the device code is loaded depends upon whether the application creates an instance of the device object to pass into the registration API or passes in the ProgID. If the ProgID is passed, the device code will not be loaded until a control or event subscription request arrives.
It might be appropriate to create the device object instance and register the device if the device must be running before any action or subscription requests can be entertained. The Device Host API also provides for registration of running devices by an application. In this case the device will not be published on boot, but only when the application registers the device.
During registration, the application can control how often the device discovery announcement is refreshed and receives a unique device identifier for the device. Each device can be registered multiple times and will receive a different device identifier. These identifiers are used along with the unique device name (UDN) for the device to identify each device.
A device can be unregistered, either permanently or temporarily, for various reasons such as upgrading or changing device properties. In the temporary case, the device can be re-registered with the same device identifier.
Device Providers
Some devices may not always be available, but may be plugged in or unplugged from the PC periodically or randomly. These devices should not be published until they are available and removed when they are unavailable.
A device provider object can be created to detect when the transient device is available and register the device at that time. The device provider is registered with the device host and will be started upon system initialization. It can then wait for an event or poll for device availability and register the device object at that time. A common use for device providers would be in a bridge application, to register devices on a bridged network (a network that does not contain UPnP devices) as they become available.
Security Considerations
UPnP Devices are announced on and made available on all networks connected to the device. In the hosted device case, this means all network connections for the targeted Windows XP PC. This means that control points, possibly running on a network outside of your control, may be able to control these devices. For this reason, in actual deployments it is recommended that a firewall be deployed on the network edge.
Hosted devices and device host also run as the LocalService account with the service name "upnphost," which gives it access to read some local registry keys and to generate audits (this is the lowest privilege service running on the system). To limit access, the device can be created in a separate process and registered as a running device.
Registering hosted devices is generally limited to administrators. More details on registering devices will be available in the next edition of the Platform SDK.
Device Host COM Object Model
Figure 1 is a diagram of the Device Host COM Object Model. The following interfaces are provided by the various objects in this model.
- IUPnPRegistrar — Methods in this interface are used by devices to register with the device host.
- IUPnPReregistrar — This interface is used by devices to reregister with the device host after a temporary unregistration.
- IUPnPEventSink — This interface is used by devices to send event notifications to the device host.
- IUPnPDeviceControl — This interface is used by the device host to manage registered devices and related services.
- IUPnPDeviceProvider — This interface is implemented by device providers and used by the device host to start and stop device providers.
- IUPnPEventSource — This interface, implemented in the service object, is used by the device host to subscribe or unsubscribe to events provided by the service.
.gif)
Figure 1. Device Host Object Model
Summary
UPnP technology has revolutionized the network by making devices and services transparently available to users anywhere on the network. Additional devices, services, and resources, on or connected to the PC but not network or UPnP device capable, can be incorporated into a network of UPnP certified devices with the Windows XP Device Host API.
For More Information