WSD Provider
Collapse the table of content
Expand the table of content

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 NamePossible ValuesRemarks
FD_QUERYCONSTRAINT_PROVIDERINSTANCEIDA 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_DIRECTEDADDRESSA 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_TYPEA 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.

PrefixNamespace
wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing
wsdhttp://schemas.xmlsoap.org/ws/2006/02/devprof
wsdiscohttp://schemas.xmlsoap.org/ws/2005/04/discovery
pnpxhttp://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.

PKEYElementType
PKEY_PNPX_GlobalIdentitywsa:AddressVT_LPWSTR
PKEY_PNPX_IDwsa:AddressVT_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.

PKEYElementType
PKEY_PNPX_MetadataVersionwsdisco:MetadataVersionVT_UI8
PKEY_PNPX_Scopeswsdisco:ScopesVT_VECTOR|VT_LPWSTR
PKEY_PNPX_Typeswsdisco:TypesVT_VECTOR|VT_LPWSTR
PKEY_PNPX_XAddrswsdisco:XAddrsVT_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.

PKEYElementType
PKEY_PNPX_CompatibleTypesSee PnP-X specification.VT_VECTOR|VT_LPWSTR
PKEY_PNPX_DeviceCategorywsd:ThisModel/pnpx:DeviceCategoryVT_VECTOR|VT_LPWSTR
PKEY_PNPX_Manufacturerwsd:ThisModel/wsd:ManufacturerVT_LPWSTR
PKEY_PNPX_ManufacturerUrlwsd:ThisModel/wsd:ManufacturerURLVT_LPWSTR
PKEY_PNPX_ModelNamewsd:ThisModel/wsd:ModelNameVT_LPWSTR
PKEY_PNPX_ModelNumberwsd:ThisModel/wsd:ModelNumberVT_LPWSTR
PKEY_PNPX_ModelUrlwsd:ThisModel/wsd:ModelURLVT_LPWSTR
PKEY_PNPX_PresentationUrlwsd:ThisModel/wsd:PresentationURLVT_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.

PKEYElementType
PKEY_PNPX_FirmwareVersionwsd:ThisDevice/wsd:FirmwareVersionVT_LPWSTR
PKEY_PNPX_FriendlyNamewsd:ThisDevice/wsd:FriendlyNameVT_LPWSTR
PKEY_PNPX_SerialNumberwsd:ThisDevice/wsd:SerialNumberVT_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.

PKEYElementType
PKEY_Device_CompatibleIdswsd:Hosted/pnpx:CompatibleIDVT_VECTOR|VT_LPWSTR
PKEY_Device_HardwareIdswsd:Hosted/pnpx:hardwareIDVT_VECTOR|VT_LPWSTR
PKEY_PNPX_Installablen/aVT_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.

PKEYElementType
PKEY_PNPX_ServiceAddresswsd:Hosted/wsd:ServiceAddressVT_VECTOR|VT_LPWSTR
PKEY_PNPX_ServiceIdwsd:Hosted/wsd:ServiceIdVT_LPWSTR
PKEY_PNPX_ServiceTypeswsd:Hosted/wsd:ServiceTypesVT_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 PKEYPnP-X PKEY
PKEY_Device_DeviceDescPKEY_PNPX_ModelName
PKEY_Device_FriendlyNamePKEY_PNPX_FriendlyName
PKEY_Device_LocationInfoPKEY_PNPX_XAddrs
PKEY_Device_ManufacturerPKEY_PNPX_Manufacturer
PKEY_Device_ModelPKEY_PNPX_ModelName
PKEY_DriverPackage_VendorWebSitePKEY_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.

Related topics

Built-in Providers

 

 

Community Additions

ADD
Show:
© 2016 Microsoft