Share via

HTTP and SOAP Provider::WSDLRequest

  • Article

Sends Simple Object Access Protocol (SOAP) requests in Web Services Descriptor Language (WSDL) to COM objects on remote servers. This procedure supports requests that perform updates subject to rollback. (A related procedure, HTTP and SOAP Provider::WSDLRequestWithNoRollback, supports requests such as queries that do not require rollback.) Used by Microsoft Provisioning Framework (MPF).

Arguments

The following table describes the XML elements and attributes. Unless otherwise indicated, the data type is string.

Element Description, relationships, and attributes

codePage

Description:
Specifies the code page of the request.

By default, the Providers [HMC SDK] assumes that incoming HTTP is encoded as UTF-8. If it is, the provider automatically converts the HTTP to Unicode.

If the incoming stream is not UTF-8, you will have faster performance if you specify the codePage value (for example, "932" for Japanese). Alternately, you can set the provider to scan for the code page (codePageAutoDetect = 1), but this will slow down performance.

If the auto-detect is used, you can still specify a codePage value as a backup in case the auto-detect fails.

Parent:
RequestInfo, rollbackInfo

codePageAutoDetect

Description:
Boolean that determines whether the provider automatically detects the code page for the request.

0 (default): The provider does not automatically detect the code page.
1: The provider invokes mlang.dll to scan the incoming HTTP stream and convert it to Unicode.

By default, the provider assumes that incoming HTTP is encoded as UTF-8. If it is, the provider automatically converts the HTTP to Unicode, and there is no need to specify a value for codePageAutoDetect.

If the incoming stream is not UTF-8, you can set the provider to scan for the code page (codePageAutoDetect = 1), but note that this will slow down performance. You will have better performance if you specify the code page (for example, for Japanese, set codePage to "932").

If the auto-detect fails, the provider looks for a codePage value; if it does not find one, it converts the HTTP to UTF-8, then to Unicode.

Parent:
requestInfo, rollbackInfo

connectionExclusionInterval

Description:
UI4 that specifies the interval (milliseconds) for re-attempting a failed connection with a server.

Whenever the provider cannot successfully send requests to a server, it immediately places the server on a bad server list and returns an error to indicate that the remote service is currently unavailable. At periodic intervals (for example, every 50000 milliseconds), the provider re-attempts the connection.

This option mimimizes unnecessary resource consumption of network bandwidth, CPU cycles, and other system resources during a failure. It also enables the provider to generate a more immediate error to alert the caller that the server is not available.

If no value is specified in the request for connectionExclusionInterval, the provider uses the value for the ConnectionExclusionInterval registry key, defined in \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Provisioning\Providers\MPFSoapProv.

Note: The provider lists a server only for the provisioning engine that executes the provider. Other engines will not list the server unless they also fail to execute requests against it.

Parents:
requestInfo, rollbackInfo

errorCodePath

Description:
Instead of returning an HRESULT based on the faultcode, a custom XML path such as "detail/ErrorCode" can be used to specify where to get the HRESULT within the soap:Fault node.

Parents:
requestInfo, rollbackInfo

executeData

Description:
Element that encapsulates the procedure's input and output data.

Children:
requestInfo (minOccurs="1" maxOccurs="1", input and output)
rollbackInfo (minOccurs="1" maxOccurs="1", input only)

method

Description:
Name of the method to invoke in the COM object.

Parents:
requestInfo, rollbackInfo

parameters

Description:
Encapsulates input and output data for the request.

Parents:
requestInfo (input and output), rollbackInfo

Child:
parameter (minOccurs="0" maxOccurs="*", input and output)

parameter

Description:
Optional input/output element.

If the parameter has multiple values, specify them using value nodes. The following example sends the method a VARIANT array of size two in which each VARIANT contains an integer.

<parameter> 
  <value xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="int">1</value> 
  <value xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="int">2</value> 
</parameter>

To send XML as a string, specify isXML ="1". The next example sends the string value <rootNode><value>1</value><value>2</value></rootNode>.

<parameter isXML="1"> 
  <rootNode> 
    <value>1</value> 
    <value>2</value> 
  </rootNode> 
</parameter>

Parent:
parameters

Attributes:

arrayTypeOptional. Indicates that the parameter is an array and specifies the data type for all elements. If arrayType is not specified and there are multiple values, the default is "anyType," which means an array of VARIANT. On output, this attribute is either set to the array type or removed ( if the response is not an array).
isXMLOptional. On input, if parameter contains well- formed XML, the method converts it to a string; otherwise, the provider fails the request. On output, if the response is well-formed XML, the method places this XML under the parameter element; otherwise, it removes the isXML attribute and returns the value in the response format.

password

Description:
User password that the Web server accepts for basic authentication.

Parents:
requestInfo, rollbackInfo

Maximum Length:
128

port

Description:
Name of the port in the WSDL file that contains the operation specified in the SOAP request. If this parameter is missing, null, or an empty string, the provider uses the first port in the specified service (serviceName node) when initializing the SOAP client.

Parents:
requestInfo, rollbackInfo

receiveTimeout

Description:
UI4 that specifies the timeout interval in milliseconds. If the Web server does not return a response within the specified interval, the provider automatically retries the request. If the Web server does not return a response the second time within the specified interval, the provider generates a timeout error. If the retryTimes element is specified, that is the number of pairs of requests that will be attempted.

The minimum value allowed is 1,000 and the maximum is 3,600,000. If a value outside this range is specified, the provider will fail with error c5000003. The default is 30,000.

Parent:
requestInfo, rollbackInfo

requestInfo

Description:
Encapsulates the information the provider uses to send the WSDL request.

Parent:
executeData

Children:
codePage (minOccurs="0" maxOccurs="1")
codePageAutoDetect (minOccurs="0" maxOccurs="1")
connectionExclusionInterval (minOccurs="0" maxOccurs="1")
method (minOccurs="1" maxOccurs="1", input only)
parameters (minOccurs="1" maxOccurs="1", input and output)
password (minOccurs="1" maxOccurs="1", input only)
port (minOccurs="1" maxOccurs="1", input only)
receiveTimeout (minOccurs="0" maxOccurs="1")
retryTimes (minOccurs="0" maxOccurs="1")
returnValue (minOccurs="0" maxOccurs="1", optional input, required output)
serviceName (minOccurs="1" maxOccurs="1", input only)
userName (minOccurs="1" maxOccurs="1", input only)
wsdlFile (minOccurs="1" maxOccurs="1", input only)
wsmlFile (minOccurs="1" maxOccurs="1", input only)

retryTimes

Description:
UI4 that specifies the number of times the provider attempts to resend the provisioning request whenever it experiences difficulty establishing a connection to the Web server. A lower protocol layer already performs one retry, so the retryTimes element actually specifies how many extra pairs of retry attempts to perform.

Parent:
requestInfo, rollbackInfo

returnValue

Description:
Value returned by the WSDL request. The element is created if not already there. The isXML attribute determines the format for the returned value.

Parent:
requestInfo

Attributes:

arrayTypeOptional; output only. Specifies that the returned value is an array and specifies the data type for all elements. This attribute is either set to the array type or removed (if the response is not an array).
isXMLOptional. If specified and the response is well- formed XML, the method places the XML under the returnValue element; otherwise, it removes the isXML attribute and returns the value in the response format.

rollbackInfo

Description:
Encapsulates the transaction rollback information for the WSDL request.

Parent:
executeData

Children:
codePage (minOccurs="0" maxOccurs="1")
codePageAutoDetect (minOccurs="0" maxOccurs="1")
connectionExclusionInterval (minOccurs="0" maxOccurs="1")
method (minOccurs="1" maxOccurs="1", input only)
parameters (minOccurs="1" maxOccurs="1", input only)
password (minOccurs="0" maxOccurs="1", input only)
port (minOccurs="0" maxOccurs="1", input only)
receiveTimeout (minOccurs="0" maxOccurs="1")
retryTimes (minOccurs="0" maxOccurs="1")
serviceName (minOccurs="0" maxOccurs="1", input only)
userName (minOccurs="0" maxOccurs="1", input only)
wsdlFile (minOccurs="1" maxOccurs="1", input only)
wsmlFile (minOccurs="0" maxOccurs="1", input only)

serviceName

Description:
Service in the WSDL file that contains the operation specified in the SOAP request. If this parameter is missing, null, or an empty string, the provider uses the first service in the specified WSDL file (wsdlFile node) when initializing the SOAP client.

Parents:
requestInfo, rollbackInfo

userName

Description:
User name that the Web server accepts for basic authentication.

Parents:
requestInfo, rollbackInfo

Maximum Length:
128

wsdlFile

Description:
URL of the WSDL file that describes the services offered by the server.

If the WSDL URL uses the HTTPS protocol then the POST URLs in the WSDL file must also use the HTTPS protocol.

Parents:
requestInfo, rollbackInfo

wsmlFile

Description:
URL of a Web Services Meta Language (WSML) file. Required only when using custom type mappers to convert between XML and COM data types.

Parents:
requestInfo, rollbackInfo

Remarks

No remarks

Schema Definition

Input

<executeData>1..1
  <requestInfo>1..1
    <wsdlFile>1..1</wsdlFile>
    <method>1..1</method>
    <parameters>1..1
      <parameter arrayType=".." isXML="..">0..unbounded</parameter>
    </parameters>
    <serviceName>0..1</serviceName>
    <port>0..1</port>
    <wsmlFile>0..1</wsmlFile>
    <userName>0..1</userName>
    <password>0..1</password>
    <retryTimes>0..1</retryTimes>
    <receiveTimeout>0..1</receiveTimeout>
    <connectionExclusionInterval>0..1</connectionExclusionInterval>
    <codePageAutoDetect>0..1</codePageAutoDetect>
    <codePage>0..1</codePage>
    <errorCodePath>0..1</errorCodePath>
    <returnValue isXML="..">0..1</returnValue>
  </requestInfo>
  <rollbackInfo>1..1
    <wsdlFile>1..1</wsdlFile>
    <method>1..1</method>
    <parameters>1..1
      <parameter arrayType=".." isXML="..">0..unbounded</parameter>
    </parameters>
    <serviceName>0..1</serviceName>
    <port>0..1</port>
    <wsmlFile>0..1</wsmlFile>
    <userName>0..1</userName>
    <password>0..1</password>
    <codePage>0..1</codePage>
    <codePageAutoDetect>0..1</codePageAutoDetect>
    <connectionExclusionInterval>0..1</connectionExclusionInterval>
    <receiveTimeout>0..1</receiveTimeout>
    <retryTimes>0..1</retryTimes>
    <errorCodePath>0..1</errorCodePath>
  </rollbackInfo>
</executeData>

Output

<executeData>1..1 
  <requestInfo>1..1</requestInfo>
    <parameters>1..1
      <parameter arrayType=".." isXML="..">0..unbounded</parameter>
    </parameters>
    <returnValue arrayType=".." isXML="..">1..1</returnValue>
  </requestInfo>
</executeData>

Sample Code

Example XML Request

The following sample request XML describes a method call for a sample COM object. For detailed instructions on setting up DocSample1, refer to the MSDN topic "Using a High Level API for SOAP Messages."

<request> 
  <procedure> 
    <execute namespace='HTTP and SOAP Provider' procedure='WSDLRequestWithNoRollback'> 
      <executeData> 
        <requestInfo> 
          <wsdlFile>https://localhost/MyProvisioning/UserAdmin.wsdl</wsdlFile> 
          <method>CreateUser</method> 
          <parameters> 
            <parameter>John</parameter> 
          </parameters> 
        </requestInfo> 
        <rollbackInfo> 
          <wsdlFile>https://localhost/MyProvisioning/UserAdmin.wsdl</wsdlFile> 
          <method>DeleteUser</method> 
          <parameters> 
            <parameter>John</parameter> 
          </parameters> 
        </rollbackInfo> 
      </executeData> 
      <after source='executeData' sourcePath='requestInfo/returnValue' destination='data'/>  
    </execute> 
  </procedure> 
</request>

Example XML Response

The following code fragment shows the format for data this procedure returns. For more information on individual elements and attributes, see the Elements and Attributes table.

<response> 
  <data> 
    <returnValue>John@MyDomain.com</returnValue> 
  </data> 
</response>

Applies To

HTTP and SOAP Provider for:

  • Hosted Messaging and Collaboration version 4.5

  • Hosted Messaging and Collaboration version 4.0

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

  • Windows-based Hosting version 4.5

  • Windows-based Hosting version 4.0

  • Windows-based Hosting version 3.5

  • Windows-based Hosting for Applications version 1.0

See also

Tasks

HTTP and SOAP Provider::WSDLRequestWithNoRollback