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.
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.