Overview of the WSDAPI Interfaces

  • Article

Web Services on Devices API (WSDAPI) is used to develop client applications that find and access devices, and to develop device hosts and associated services that run on Windows Vista and Windows Server 2008. The Function Discovery API and the WsdCodeGen tool are supplemental tools that can be used for client, device host, and service development. The WSDAPI interfaces can be used directly to expose advanced functionality.

Major WSDAPI interfaces

The four major WSDAPI interfaces are IWSDiscoveryProvider, IWSDiscoveryPublisher, IWSDDeviceProxy, and IWSDDeviceHost. For a list of all of the WSDAPI interfaces, see Web Services on Devices Interfaces.

IWSDiscoveryProvider

IWSDiscoveryProvider is used to implement WS-Discovery functionality on clients.

IWSDiscoveryProvider issues WS-Discovery Probe and Resolve messages, and receives Hello, Bye, ProbeMatches, and ResolveMatches messages. Use the information retrieved through the IWSDiscoveryProvider interface when creating an IWSDDeviceProxy interface used to describe and control a specific DPWS device.

An IWSDiscoveryProvider interface is not necessary when simply resolving a particular DPWS device address before creating a device proxy. WSDCreateDeviceProxy will automatically resolve the device address if required.

The Function Discovery API can be used for generic device and service discovery, as the API can discover DPWS devices and also devices using other protocols. Consider using Function Discovery when writing a generic discovery application.

IWSDiscoveryPublisher

IWSDiscoveryPublisher is used to implement WS-Discovery functionality on target services, such as devices.

IWSDiscoveryPublisher allows an application to publish its presence using WS-Discovery Hello and Bye messages. This interface allows an application to receive Probe and Resolve requests, and construct and send ProbeMatches and ResolveMatches responses.

An IWSDiscoveryPublisher interface is not necessary when simply publishing the existence of an IWSDDeviceHost object. IWSDDeviceHost manages its own WS-Discovery presence.

IWSDDeviceProxy

IWSDDeviceProxy is used to implement client-side WS-Discovery, WS-MetadataExchange, and control functionality. This functionality includes optional secure channel, WS-Eventing, and attachment capabilities.

The IWSDDeviceProxy interface has the following three uses.

  • Resolves logical device addresses, if necessary.
  • Initiates metadata requests to devices to enumerate the types and addresses of services.
  • Provides a source for IWSDServiceProxy objects, which can be used to issue control messages to specific services on a device.

The IWSDDeviceProxy object is typically created and used entirely inside code generated by WsdCodeGen.

IWSDDeviceHost

IWSDDeviceHost is used to implement device-side WS-Discovery, WS-MetadataExchange, and service hosting functionality. Hosted services may respond to control messages, and may support secure channel, WS-Eventing, and attachment capabilities.

The IWSDDeviceHost interface has the following uses.

  • Hosts service objects.
  • Announces the presence of a device host on the network using WS-Discovery.
  • Responds to WS-MetadataExchange requests and describes the types and locations of hosted services.
  • Dispatches network requests into service objects.

WS-Discovery, WS-MetadataExchange, and WS-Eventing subscription management functionality is handled entirely within the device host object. Before a service can be hosted inside a device host, the following requirements must be met.

  • The host must be created by calling WSDCreateDeviceHost.
  • The metadata associated with the service must be registered.
  • The service itself must be registered.
  • The device host must be started.

The IWSDDeviceHost object is typically created and used inside code generated by WsdCodeGen.