Web Services on Devices

Web Services on Devices (WSD) Roadmap

Web Services on Devices (WSD) extends the existing Web services architecture to resource-constrained devices, such as PDAs, computer peripherals, computing appliances, and consumer electronics. WSD is one of four technologies that comprise the Network Connected Device (NCD). Those four are:

• PnP-X — a set of extensions to Plug and Play (PnP) that integrate NCDs into the Windows PnP subsystem, making the NCD appear as a local device inside of Windows and providing an installation experience that is similar to attaching a physically connected device.

• Function Discovery (FD) — a new API makes it easy for applications to enumerate and use devices of a specific type, regardless of the way in which they are connected to the computer. Function Discovery works through providers for the various device types to enumerate available devices (for example, PnP, registry, WSD, SSDP, NetBIOS, and third party providers).

• WSD — an implementation of the Device Profile for Web Services (DPWS) specification that enables devices to interact with Microsoft Windows over an IP-based network. The WSD functionality is part of the Rally licensing program (https://www.microsoft.com/rally/). The DPWS specification is available free of charge. This specification is under the licensing terms of Rally.

• Publication Services — a new Windows service that enables client applications to publish resources so that they can be discovered by other computers on the same subnet. Each application can dynamically register and unregister individual resources that it wants published.

These NCD technologies enable virtually-connected devices (those connected to a computer over a network) to appear and act as if they were physically connected. Such devices are loosely connected to one or more computers and use the network as a communication bus. A typical usage scenario for WSD is:

1. A device is connected to the network and receives a unique IP address.

2. The device then announces its presence.

3. A client uses the Function Discovery API to discover the device and enumerate its services. The FD runtime works through WSD to accomplish this for WSD devices, although it is possible for an application to call directly through to these WSD discovery functions.

4. The client invokes service functions on the device and can optionally subscribe to device events.

For more information about NCD, see "Network Connected Devices" in the Windows SDK, or visit the Microsoft Windows Hardware and Driver Central Web site (https://www.microsoft.com/whdc) site.

Publication Services enables a WSD device to advertise (publish) its functionality and then offer its functions as Web services over IP-based networks. It also enables devices to find (discover) and access Web services of other devices and computers on the same network. From a user's perspective, NCD technologies will largely eliminate the experiential difference between using devices directly connected to a computer and those virtually connected over a network (including the Internet). As explained above, typically a developer will uniformly access NCDs using higher-level publication services and function discovery.

Projected uses of WSD include:

• Printers and other shared network devices can be easily discovered, and when selected are automatically configured for the client computer.

• Automatic discovery of and connection to wireless devices, including cell phones, new overhead projectors, and home entertainment centers.

• Cameras that transfer pictures across the Internet to a user's home computer, to their MSN Spaces site, or even to other devices.

• Home control systems that automatically discover and configure new lighting, heating, and other systems. These systems could be monitored and controlled from a computer located in the home or over the Internet.

• Windows Vista® will automatically use WSD to discover Windows Vista computers and devices on the home network (for example, through the use of the Network Explorer). NetBIOS will be used to discover computers not otherwise found.

WSD facilitates easy two-way communication. For example, a printer typically receives print jobs, but could also send important notifications, such as a new device event when it is first connected, or a service event when its printer supplies run low.

WSD is Microsoft's implementation of the Devices Profile for Web Services (DPWS) standard, a specification that enables low-cost devices to use standard Web-based mechanisms to communicate with other devices, computers, and Web services. These mechanisms depend on a lightweight subset of the same open protocols as Developer Story Windows Communication Foundation does, namely XML, SOAP, WSDL, MTOM, WS-Addressing, WS-Eventing, and WS-Discovery. For more information about WSD, see "Web Services for Devices" in the Windows SDK.

Inside WSD: An Application Developer's View

The Web Services for Devices (WSD) API is the Windows implementation of the Device Profile for Web Services (DPWS) standard. WSD may be used for the development of both client and server (device) implementations for Windows and embedded systems. Typically, a device (for example, a network printer) will use a small amount of flash memory to store WSD-related information.

WSD supports the following uses by independent software and hardware vendors (ISVs and IHVs):

• The creation of WSD clients to access device services and the creation of WSD services on the host.

• The publishing and discovery of services via WS-Discovery. The WS-Discovery service will cover all default FD queries.

• Standard communication protocol support, including both HTTP and UDP (the latter is used for discovery), and secure communication via TLS/SSL. WSD can run on both IPv4 and IPv6.

WSDAPI Concepts and Architecture

A high-level architecture of an NCD-compliant application is shown below. In general, a WSD client application often uses two APIs for interacting with a WSD-compliant device:

• Function Discovery to enumerate device categories and identify a specific device.

• WSD for the primary use, management, and diagnosis of the device. It supports device control, event notification, and one- and two-way messaging.

Both of these APIs are COM-based, and rely on Web Service Description Language (WSDL) contracts, although Microsoft provides the WSDAPI Code Generation tool to generate much of the client interface code.

Note

Simple Service Discovery Protocol (SSDP) is the basis of the discovery protocol of Universal plug-and-play (UPnP). Devices can use SSL to secure transmissions and a subset of WSTL (Web Services Transaction Language) to control related operations more thoroughly.

A WSD device advertises a primary endpoint that can be located through WS-Discovery (via UDP). This endpoint supplies metadata about the device through WS-MetadataTransfer. This information typically includes manufacturer, device information, and service host metadata (information on offered services). Devices typically offer functionality, defined by WSDL contracts, in one or more of the following categories:

• Control — configuration, state manipulation, and processing.

• Status — results of control changes, current device status, usage statistics, and maintenance information.

• Diagnostics — remote diagnostics for customer support and delegates for remote services for device support.

Microsoft has written WSDL contract templates for common scenarios (for example, printing and scanning) which will be delivered in the Windows DDK.

Approach to Client-Side WSD Development

Although WSD can be used directly in a step-by-step programmatic way, the suggested method is to use a contract-first development approach, making use of the WSDAPI Code Generation tool. This tool uses either a WSDL/XSD contract or an assembly representing the service’s contract definition in conjunction with a code generation script to generate proxies and stubs for the client and host. This relieves much of the burden of dealing with the WSD API directly for the application developer. The following simplified diagram demonstrates the relationship of the different client, service, and infrastructure components.

The following explanatory points apply to the diagram:

• The term control point is used to describe the client.

• The client proxy is required whenever the client can subscribe to service events.

• Microsoft provides standard Function Discovery providers for the registry, Plug and Play (PnP), SSDP, WS-Discovery, and NetBIOS. Custom providers can be developed using the Function Discovery Provider API.

The following steps detail how to use a contract-first approach with the WSDAPI Code Generation tool to create a client application for an existing WSD-compliant device:

1. Install the Device SDK for the hosted device you want to develop against. At minimum, it should include native C/C++ header and COM IDL files for device interfaces and a service contract in the form of a WSDL/XSD. It may also contain an optional software emulator of the device, to aid application development.

2. If the Device SDK does not also provide the WSD host and client proxies and stub files (or a code generator script), then you must generate these with WSDAPI Code Generation tool through the following steps:

   1. Create a code generator script that the WSDAPI Code Generation tool uses to control its operation. This script is an XML file that defines constants, device metadata, and a description of the files to be generated. This script can be quite complicated. For more information, see "Creating a Code Generator Script" in the Windows SDK.

   2. Using the service contract and code generator script as input, run the WSDAPI Code Generation tool to generate the client and host proxies and stubs.

3. Create the core client application using C/C++ or a compatible language. Managed WSD development is not supported in this release. The hosted device manufacturer must supply the corresponding library that represents the device services to develop against. Although the client could be hard-coded to recognize a specific device with pre-defined interfaces, the recommended approach is to use Function Discovery to find the device and obtain a class-specific interface for the device.

4. Code and build a client application using the client proxy for outgoing service calls and the client stub for incoming event notifications.

The following diagram depicts this development process.

For more information about WSD development, see Web Services for Devices in the Windows SDK.

Resources

The following resources are available in the WSD API.

Library and Header	Description
Wsdapi.dll	Windows Vista standard WSD runtime.
Wsdapi.h	The header file for WSD functionality.
Wsdapi.lib	Static library for WSD functionality.

Although the WSD library has dozens of COM interfaces and independent functions, they can be logically separated into the following four more manageable groups: publishing, discovery, hosting and client APIs. Remember that most client applications will use Microsoft Function Discovery and Publishing Services instead of the corresponding WSD APIs, and that WSD Code Generation Tool greatly reduces the complexity of using the hosting and client APIs. However, advanced developers may need to use these APIs directly.

The Web Services on Devices programming interface defines and uses several interfaces. For more information on these interfaces, see Web Services on Devices Interfaces in the MSDN documentation.

For more information on the WSDAPI Code Generation tool, see the WSD development kit in the Windows Rally SDK.

For more information, see "Web Services for Devices" in the Windows SDK.