About Web Services on Devices
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
Web Service on Devices API (WSDAPI) is a Microsoft implementation of the Devices Profile for Web Services (DPWS) specifications. DPWS defines a set of standard communication protocols for operations such as web service messaging, discovery, description and eventing. These operations provide the building blocks with which you can build DPWS-compliant devices and DPWS-compliant clients applications. These operations also allow a resource-constrained client application to easily discover a DPWS-compliant device. After a client application discovers a device, the client can retrieve a description of the services hosted on that device and use those services.
For more information about DPWS, see this Web site.
Devices and Services
A device is a hardware component that is attached to the network. Example devices include printers, Web cameras, and video systems.
A device can include zero or more services. For example, a video device can include a service that supports power on and off, another service that supports play control, and other services to support media ejection and video streaming. A service can support multiple actions. For example, a play control service can support actions such as play, pause, rewind, and fast-forward.
Discovering and Manipulating a Device
WSDAPI extends the local Plug and Play model by allowing a client application to discover and access a remote device and its associated services across a network. WSDAPI supports one-way and two-way control messaging, discovery, description, and eventing. The following figure shows how WSDAPI allows a client to discover the services provided by a device.
.gif "Bb821872.28610c78-acd3-4d7c-892b-6bfcd1866595(en-us,MSDN.10).gif")
A DPWS-compliant device announces its presence and exposes any services using a unique address and a standardized set of XML messages. Each client application can use the discovery process to find the device, enumerate its services, and connect to those services to perform specific actions.
A client application first queries the device for complete descriptions of its services, including the service types, such as a printer service type or a scanner service type. The client application then controls the device by calling commands defined by a service type, such as by calling CreatePrintJob on a device with a printer service type. Optionally, the client application can also monitor state changes in each service by subscribing to events that occur during command execution. The following figure shows an example of client application and device host communication.
.gif "Bb821872.86d07291-ffde-4cc3-ae73-fad23e33c01d(en-us,MSDN.10).gif")
For more information about messaging patterns, see Discovery and Metadata Exchange Message Patterns.
Logical and Physical Addressing
Logical addressing uniquely identifies a device independently of its physical address. The WS-Discovery protocol provides a mechanism to resolve a logical address to a physical address, allowing client-to-device messaging to take place. For example, if you have a laptop and a network attached storage (NAS) device, the IP addresses of the laptop and the device will change as you move between subnets. The laptop should be able to recognize the unique device, regardless of its current IP address. Matching logical and physical addresses requires that the device's identity be independent of the IP address it obtains. Traditional mechanisms such as DNS are not available in a normal roaming scenario, so two DPWS protocols, WS-Addressing and WS-Discovery, provide logical addressing and resolution as an ad-hoc alternative.
The device manufacturer gives the device a globally unique identifier, represented as a UUID URI. This identifier never changes. When the device powers on, it always announces its logical address by using a WS-Discovery Hello message, and accepts requests to convert that to a physical address, typically an IP address, by using WS-Discovery Resolve or Probe messages. After the device obtains a valid physical address, all messaging happens using that physical address. Thereafter, WS-Discovery is used only if the address changes, the device changes state and the clients need to be notified, or the device goes offline.
Building Applications
WSDAPI provides a generic DPWS SOAP stack for use by client applications and device hosts. You can use the Web Services on Devices Code Generator (WsdCodeGen.exe) to convert a service description (WSDL) into proxy and stub code that applications can call directly. This generated code automatically transforms function calls and parameters into SOAP messages and XML fields, and then calls into WSDAPI to issue to requests to the remote device or client.
See Also
Concepts
WSDAPI Devices and Services Concepts
Discovery and Metadata Exchange Message Patterns