IWSDiscoveryPublisher::MatchResolveEx method (wsddisco.h)

Determines whether a Resolve message matches the specified host and sends a WS-Discovery ResolveMatches message with extended information if the match is made.

Syntax

HRESULT MatchResolveEx(
  [in]           const WSD_SOAP_MESSAGE *pResolveMessage,
  [in]           IWSDMessageParameters  *pMessageParameters,
  [in]           LPCWSTR                pszId,
  [in]           ULONGLONG              ullMetadataVersion,
  [in]           ULONGLONG              ullInstanceId,
  [in]           ULONGLONG              ullMessageNumber,
  [in, optional] LPCWSTR                pszSessionId,
  [in, optional] const WSD_NAME_LIST    *pTypesList,
  [in, optional] const WSD_URI_LIST     *pScopesList,
  [in, optional] const WSD_URI_LIST     *pXAddrsList,
  [in, optional] const WSDXML_ELEMENT   *pHeaderAny,
  [in, optional] const WSDXML_ELEMENT   *pReferenceParameterAny,
  [in, optional] const WSDXML_ELEMENT   *pPolicyAny,
  [in, optional] const WSDXML_ELEMENT   *pEndpointReferenceAny,
  [in, optional] const WSDXML_ELEMENT   *pAny
);

Parameters

[in] pResolveMessage

Pointer to a WSD_SOAP_MESSAGE structure that represents the Resolve message passed in to the notification sink's ResolveHandler.

[in] pMessageParameters

Pointer to an IWSDMessageParameters object that represents the transmission parameters passed in to the notification sink's ResolveHandler.

[in] pszId

The logical or physical address of the device, which is used as the device endpoint address. A logical address is of the form urn:uuid:{guid}. A physical address can be a URI prefixed by http or https, or simply a URI prefixed by uri. Whenever possible, use a logical address.

[in] ullMetadataVersion

Current metadata version.

Note  For compatibility with the WS-Discovery specification, this value must be less than or equal to UINT_MAX (4294967295).
 

[in] ullInstanceId

Identifier for the current instance of the device being published. This identifier must be incremented whenever the service is restarted. For more information about instance identifiers, see Appendix I of the WS-Discovery specification.

Note  For compatibility with the WS-Discovery specification, this value must be less than or equal to UINT_MAX (4294967295).
 

[in] ullMessageNumber

Counter within the scope of the instance identifier for the current message. The message number must be incremented for each message.

Note  For compatibility with the WS-Discovery specification, this value must be less than or equal to UINT_MAX (4294967295).
 

[in, optional] pszSessionId

Unique identifier within the scope of the instance identifier for the current session. This parameter corresponds to the sequence identifier in the AppSequence block in the Probe message. For more information about sequence identifiers, see Appendix I of the WS-Discovery specification.

This parameter may be NULL.

[in, optional] pTypesList

Pointer to a WSD_NAME_LIST structure that represents the list of types supported by the publishing host. May be NULL. If pTypesList is specified, MatchResolveEx will use WS-Discovery matching logic to verify that the types match those specified in pResolveMessage.

[in, optional] pScopesList

Pointer to a WSD_URI_LIST structure that represents the list of matching scopes supported by the publishing host. The list contains hash values in string form. May be NULL. If pScopesList is specified, MatchResolveEx will use WS-Discovery matching logic to verify that the scopes match those specified in pResolveMessage.

[in, optional] pXAddrsList

Pointer to a WSD_URI_LIST structure that represents the list of transport addresses supported by the publishing host. Each transport address string contains an address and port number which can be used for connection by a remote host. pXAddrsList and pXAddrsList->Element may not be NULL.

[in, optional] pHeaderAny

Pointer to a WSDXML_ELEMENT structure that contains an XML element to be inserted in the "ANY" section of the header.

[in, optional] pReferenceParameterAny

Pointer to a WSDXML_ELEMENT structure that contains an XML element to be inserted in the "ANY" section of the reference parameter properties.

[in, optional] pPolicyAny

Not used.

[in, optional] pEndpointReferenceAny

Pointer to a WSDXML_ELEMENT structure that contains an XML element to be inserted in the "ANY" section of the endpoint.

[in, optional] pAny

Pointer to a WSDXML_ELEMENT structure that contains an XML element to be inserted in the "ANY" section of the message body.

Return value

Possible return values include, but are not limited to, the following:

Return code Description
S_OK
The method completed successfully.
E_INVALIDARG
One or more of the following conditions is true:
  • pszId is NULL.
  • The length in characters of pszId exceeds WSD_MAX_TEXT_LENGTH (8192).
  • The length in characters of pszSessionId exceeds WSD_MAX_TEXT_LENGTH (8192).
  • pProbeMessage is NULL.
E_ABORT
The publisher has not been started. Attaching a notification sink starts the publisher. To attach a sink, call RegisterNotificationSink.
E_OUTOFMEMORY
Insufficient memory to complete the operation.

Remarks

MatchResolveEx should be only when the discovery publisher has issued a ResolveHandler callback. pResolveMessage and pMessageParameters are passed directly from the callback into MatchResolveEx. The ResolveHandler also passes information required by the publisher to determine if the supplied Resolve message matches and, if so, to issue a ResolveMatches response if appropriate.

MatchResolveEx sends ResolveMatches messages on all bound adapters and automatically issues message retransmissions when required by WS-Discovery.

The parameters referring to WSDXML_ELEMENT structures can be used to extend the contents of the ResolveMatches message being sent with custom information.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header wsddisco.h (include Wsdapi.h)
DLL Wsdapi.dll

See also

IWSDiscoveryPublisher