Share via


WSD Provider

[Function Discovery is available for use in the following versions of Windows: Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, and Windows Vista. It may be altered or unavailable in subsequent versions.]

The Web Services on Devices (WSD) provider is an asynchronous Function Discovery provider that enumerates devices that use the Devices Profile for Web Services (DPWS) for discovery. The WSD provider uses the Web Services on Devices API (WSDAPI) to discover WSD-enabled devices, perform metadata exchange, and process metadata. Once a device is discovered, the WSD provider gets the device metadata, processes it, and returns a function instance that represents the WSD device.

Query Results

The WSD provider supports collection queries and instance queries. That means the provider supports both the IFunctionInstanceCollectionQuery::Execute and IFunctionInstanceQuery::Execute methods. Because the WSD provider is asynchronous, Execute always returns E_PENDING for a successful query.

When a collection query is executed, the WSD provider sends a multicast Probe message, which is used to search for WSD devices on the local subnet that match the constraints (if any) specified in the Function Discovery query. When an instance query is executed, the WSD provider sends a multicast Resolve message, which is used to search for the target device. In either case, the WSD provider then performs metadata exchange with the devices that responded to the Probe or Resolve message, processes the metadata, and returns the corresponding function instances. Applications can then call IFunctionInstance::QueryService on a returned function instance to get the collection of function instances corresponding to each service hosted on the device.

Function instances are returned using the IFunctionDiscoveryNotification::OnUpdate method. Also, after the WSD provider has finished enumerating resources, the provider sends a FD_EVENTID_SEARCHCOMPLETE notification using IFunctionDiscoveryNotification::OnEvent.

After the initial query results have been returned, the WSD provider continues to listen for messages from devices on the network. When a device sends a Hello message, the WSD provider sends a QUA_ADD notification to the Function Discovery client. When a device sends a Bye message, the WSD provider sends a QUA_REMOVE notification to the Function Discovery client. That means the client application is notified whenever a device comes online or goes offline until the client releases the query object by calling Release on the IFunctionInstanceCollectionQuery or on the IFunctionInstanceQuery object.

Query Constraints

Query constraint can be added by calling IFunctionInstanceCollectionQuery::AddQueryConstraint on an IFunctionInstanceCollectionQuery object before executing the query.

The following table shows the query constraints supported by the WSD provider. The table also shows possible values to pass to the pszConstraintValue parameter of the AddQueryConstraint method.

Constraint Name Possible Values Remarks
FD_QUERYCONSTRAINT_PROVIDERINSTANCEID A WS-Discovery endpoint. This constraint limits query results to a single device. The WSD provider returns a function instance representing the device matching the specified endpoint address, if there is such a device.
This constraint can be applied to collection queries. It can also be combined with the PROVIDERWSD_QUERYCONSTRAINT_DIRECTEDADDRESS constraint.
PROVIDERWSD_QUERYCONSTRAINT_DIRECTEDADDRESS A HTTP transport address. When this constraint is used, a Probe message is sent over HTTP to search for a device at a known URL. The query results are limited to the device, if any, responding to Probe messages sent over HTTP at the given URL.
This constraint can be applied to collection and instance queries. It can also be combined with the FD_QUERYCONSTRAINT_PROVIDERINSTANCEID constraint.
PROVIDERWSD_QUERYCONSTRAINT_TYPE A string that specifies the type of device or service being searched. The string must be a URI that specifies the namespace and the type. This constraint limits query results to devices or hosted services of the specified type. For example, to query for WSD devices of type "IBlinds" defined in the namespace "http://www.fabrikam.com/remotecontrolhome/Multi", use "http://www.fabrikam.com/remotecontrolhome/Multi/IBlinds" for the constraint value.
Applications may specify multiple PROVIDERWSD_QUERYCONSTRAINT_TYPE constraints to search for devices (also referred to as discovery hosts) that support multiple types.
This constraint can only be applied to collection queries. It cannot be combined with any other query constraints.

For more information about a named constraint, see Constraint Definitions. For general information about query constraints, see Constraints.

Notifications

Because the WSD provider is asynchronous, a non-NULL IFunctionDiscoveryNotification pointer must be passed to the query creation method (either IFunctionDiscovery::CreateInstanceCollectionQuery or IFunctionDiscovery::CreateInstanceQuery). The WSD provider will listen for Hello and Bye messages and send QUA_ADD and QUA_REMOVE notifications to the IFunctionDiscoveryNotification interface as appropriate. An implementation of the IFunctionDiscoveryNotification::OnUpdate method should handle these two notifications. The QUA_CHANGE notification is not used.

Events

The FD_EVENTID_SEARCHCOMPLETE event is dispatched by the WSD provider. This event notifies the application that the initial search for devices has been completed and that the application will receive function instances for added or removed devices that match the query constraints. The semantics are similar to IWSDiscoveryProviderNotify::SearchComplete. Applications that must return results synchronously can wait for this event to return the result set to their callers. For more information about FD_EVENTID_SEARCHCOMPLETE, see IFunctionDiscoveryNotification::OnEvent.

Services

The WSD provider implements the SID_PNPXServiceCollection service.

An application can use the SID_PNPXServiceCollection service to get the collection of child function instances (representing hosted services) from a given function instance. To do this, the application calls IFunctionInstance::QueryService on a returned function instance with the guidService parameter set to SID_PNPXServiceCollection and the riid parameter set to _uuidof(IFunctionInstanceCollection). If a function instance does not have any child function instances, then an empty collection is returned.

Although the WSD provider does not implement the SID_PNPXAssociation service, function instances created by the WSD provider are returned when an application calls IFunctionInstance::QueryService on a function instance with the guidService parameter set to SID_PNPXAssociation and the riid parameter set to _uuidof(IPNPXAssociation).

Property Store

The WSD provider implements read-only property stores.

The IFunctionInstance::OpenPropertyStore method can be used to access the property keys (PKEYs) associated with a function instance. The methods of the IPropertyStore interface can be used to get the PKEYs associated with the function instance.

Supported PKEYs

The WSD provider supports a number of device and PnP-X PKEYs. These PKEYs are used to store information from discovery and metadata messages. For more information about these messages, see Discovery and Metadata Exchange Message Patterns. This section enumerates the PKEYs supported by the WSD provider and, when relevant, names the XML element from the original message that corresponds with the PKEY.

The following table shows the namespace prefixes used in this section.

Prefix Namespace
wsa https://schemas.xmlsoap.org/ws/2004/08/addressing
wsd https://schemas.xmlsoap.org/ws/2006/02/devprof
wsdisco https://schemas.xmlsoap.org/ws/2005/04/discovery
pnpx https://schemas.microsoft.com/windows/pnpx/2005/10

The following table shows the identity-related PKEYs supported by the WSD provider, the type of each PKEY, and the XML element from which the PKEY value is derived.

PKEY Element Type
PKEY_PNPX_GlobalIdentity wsa:Address VT_LPWSTR
PKEY_PNPX_ID wsa:Address VT_LPWSTR

The following table shows the discovery-related PKEYs supported by the WSD provider, the type of each PKEY, and the XML element from which the PKEY value is derived. Discovery-related PKEYs are retrieved from Hello, Bye, ResolveMatch, and ProbeMatch messages.

PKEY Element Type
PKEY_PNPX_MetadataVersion wsdisco:MetadataVersion VT_UI8
PKEY_PNPX_Scopes wsdisco:Scopes VT_VECTOR|VT_LPWSTR
PKEY_PNPX_Types wsdisco:Types VT_VECTOR|VT_LPWSTR
PKEY_PNPX_XAddrs wsdisco:XAddrs VT_VECTOR|VT_LPWSTR

The following table shows the model-related PKEYs supported by the WSD provider, the type of each PKEY, and the XML element from which the PKEY value is derived.

PKEY Element Type
PKEY_PNPX_CompatibleTypes See PnP-X specification. VT_VECTOR|VT_LPWSTR
PKEY_PNPX_DeviceCategory wsd:ThisModel/pnpx:DeviceCategory VT_VECTOR|VT_LPWSTR
PKEY_PNPX_Manufacturer wsd:ThisModel/wsd:Manufacturer VT_LPWSTR
PKEY_PNPX_ManufacturerUrl wsd:ThisModel/wsd:ManufacturerURL VT_LPWSTR
PKEY_PNPX_ModelName wsd:ThisModel/wsd:ModelName VT_LPWSTR
PKEY_PNPX_ModelNumber wsd:ThisModel/wsd:ModelNumber VT_LPWSTR
PKEY_PNPX_ModelUrl wsd:ThisModel/wsd:ModelURL VT_LPWSTR
PKEY_PNPX_PresentationUrl wsd:ThisModel/wsd:PresentationURL VT_LPWSTR

The following table shows the PnP-X device-related PKEYs supported by the WSD provider, the type of each PKEY, and the XML element from which the PKEY value is derived.

PKEY Element Type
PKEY_PNPX_FirmwareVersion wsd:ThisDevice/wsd:FirmwareVersion VT_LPWSTR
PKEY_PNPX_FriendlyName wsd:ThisDevice/wsd:FriendlyName VT_LPWSTR
PKEY_PNPX_SerialNumber wsd:ThisDevice/wsd:SerialNumber VT_LPWSTR

The following table shows the PnP-X installation-related PKEYs supported by the WSD provider, the type of each PKEY, and the XML element from which the PKEY value is derived.

PKEY Element Type
PKEY_Device_CompatibleIds wsd:Hosted/pnpx:CompatibleID VT_VECTOR|VT_LPWSTR
PKEY_Device_HardwareIds wsd:Hosted/pnpx:hardwareID VT_VECTOR|VT_LPWSTR
PKEY_PNPX_Installable n/a VT_BOOL

The following table shows the service-related PKEYs supported by the WSD provider, the type of each PKEY, and the XML element from which the PKEY value is derived.

PKEY Element Type
PKEY_PNPX_ServiceAddress wsd:Hosted/wsd:ServiceAddress VT_VECTOR|VT_LPWSTR
PKEY_PNPX_ServiceId wsd:Hosted/wsd:ServiceId VT_LPWSTR
PKEY_PNPX_ServiceTypes wsd:Hosted/wsd:ServiceTypes VT_VECTOR|VT_LPWSTR

The WSD provider supports the following networking-related PKEYs. For PKEY descriptions and PROPVARIANT types, see PnP-X Provider PKEYs.

  • PKEY_PNPX_IpAddress
  • PKEY_PNPX_NetworkInterfaceGuid
  • PKEY_PNPX_NetworkInterfaceLuid
  • PKEY_PNPX_PhysicalAddress
  • PKEY_PNPX_RemoteAddress

The WSD provider supports the following PKEYs related to publication services device hosts. For PKEY descriptions and PROPVARIANT types, see General PKEYs.

  • PKEY_PUBSVCS_METADATA
  • PKEY_PUBSVCS_TYPE

The WSD provider sets PnP-X PKEYs. It also maps some PnP-X-specific keys to general device PKEYs. The following table shows the device PKEYs populated by the WSD provider and the PnP-X PKEY equivalents.

Device PKEY PnP-X PKEY
PKEY_Device_DeviceDesc PKEY_PNPX_ModelName
PKEY_Device_FriendlyName PKEY_PNPX_FriendlyName
PKEY_Device_LocationInfo PKEY_PNPX_XAddrs
PKEY_Device_Manufacturer PKEY_PNPX_Manufacturer
PKEY_Device_Model PKEY_PNPX_ModelName
PKEY_DriverPackage_VendorWebSite PKEY_PNPX_ManufacturerUrl

The PKEY_Device BIOSVersion key is also supported. This key does not have a PnP-X equivalent.

For more information about all PnP-X PKEYs, see PnP-X Provider PKEYs. For information about the WSD device metadata requirements in general, and also about the relationship between WSD device elements and PKEYs, see PnP-X: Plug and Play Extensions for Windows Specification.

Built-in Providers