HTTP and SOAP Provider::SoapRequest

Generates and sends Simple Object Access Protocol (SOAP) requests to a remote server. This procedure supports requests that perform updates subject to rollback. (A related procedure, SoapRequestWithNoRollback, supports requests such as queries that do not require rollback.) Used by Microsoft® Provisioning Framework (MPF).

XML Input Schema

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

<executeData>1..1
  <requestInfo>1..1
	<useTip>0..1</useTip>
	<url>1..1</url>
	<queryString>0..1</queryString>
	<queryStringParams>0..1
	<param name=".." value="..">1..unbounded</param>
	</queryStringParams>
	<action>0..1</action>
	<httpHeaders>
	<param name=".." value="..">1..unbounded</param>
	</httpHeaders>
	<header>0..1</header>
	<body>0..1</body>
	<userName>0..1</userName>
	<password>0..1</password>
	<certificateName>0..1</certificateName>
	<certificateStore>0..1</certificateStore>
	<userId>0..1</userId>
	<retryTimes>0..1</retryTimes>
	<receiveTimeout>0..1</receiveTimeout>
	<connectionExclusionInterval>0..1</connectionExclusionInterval>
	<getCookies>0..1</getCookies>
	<cookie>0..unbounded</cookie>
	<codePageAutoDetect>0..1</codePageAutoDetect>
	<codePage>0..1</codePage>
	<errorCodePath>0..1</errorCodePath>
  </requestInfo>
  <rollbackInfo>0..1
	<url>1..1</url>
	<queryString>0..1</queryString>
	<queryStringParams>0..1
	<param name=".." value="..">1..unbounded</param>
	</queryStringParams>
	<action>0..1</action>
	<httpHeaders>
	<param name=".." value="..">1..unbounded</param>
	</httpHeaders>
	<header>0..1</header>
	<body>0..1</body>
	<userName>0..1</userName>
	<password>0..1</password>
	<certificateName>0..1</certificateName>
	<certificateStore>0..1</certificateStore>
	<userId>0..1</userId>
	<retryTimes>0..1</retryTimes>
	<receiveTimeout>0..1</receiveTimeout>
	<connectionExclusionInterval>0..1</connectionExclusionInterval>
	<errorCodePath>0..1</errorCodePath>
  </rollbackInfo>
  <result>0..1</result>
<executeData>1..1</executeData>

XML Output Schema

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.

<executeData>1..1
  <requestInfo>1..1</requestInfo>
	<getCookies>0..1</getCookies>
	<cookie>0..unbounded</cookie>
  </requestInfo>
  <result>0..1</result>
</executeData>

Elements and Attributes

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

Element Description, relationships, and attributes
action Description:
 Corresponding node for the SOAPAction header defined by the SOAP protocol. Servers use this node to identify the namespace and method for the request or rollback transaction. This eliminates the need to crack the SOAP envelope.

Parents:
requestInfo, rollbackInfo

Maximum Length:
1,024
body Description:
 Body node of the SOAP payload.

Parents:
requestInfo, rollbackInfo

certificateName Description:
 Name of the authentication certificate for HTTPS authentication.

Parents:
requestInfo, rollbackInfo

Maximum Length:
128
certificateStore Description:
 Store for the authentication certificate. Illustrated by the following sample code: 
<certificateStore>MY</certificateStore>

A certificate store can be a system store or a user's store. Initially, the provider attempts to load the certificate from the system store. If it fails, it loads the certificate from the user store.

Parents:
requestInfo, rollbackInfo

Maximum Length:
128
codePage Description:
 Specifies the code page of the request.

By default, the provider 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

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

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
cookie Description:
Value that the provider uses to receive a cookie returned by Microsoft® .NET Passport. See also getCookies.

Parent:
getCookies

Maximum Length:
128
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:
 Encapsulates the procedure's input and output data.

Children:
requestInfo (minOccurs="1" maxOccurs="1")
result (minOccurs="0" maxOccurs="1")
rollbackInfo (minOccurs="1" maxOccurs="1")
getCookies Description: 
 Encapsulates cookies returned by Microsoft® .NET Passport. Illustrated by the following sample code. 
<getCookies>
  <cookie name="user">kima</cookie>
  <cookie name="authInfo">
	<user>kima</user>
	<pass>78%4@</pass>
  </cookie>
</getCookies>

Whenever the value of a child cookie node in the request matches the name of a cookie in the HTTP response, the provider resets the cookie node to match the returned value.

Parent:
requestInfo

Child:
cookie

header Description:
 SOAP header node of the SOAP payload.

Parents:
requestInfo, rollbackInfo

httpHeaders Description:
 Option to append additional headers to the HTTP request.

Parents:
requestInfo, rollbackInfo

Child:
param

queryString Description:
 Query string for the HTTP request.

There are two ways to pass parameters: as a single string in the queryString node or as param nodes of the queryStringParams node. Use the first style to pass an existing query string. Use the second style if you want the provider to build the query string for you from other input parameters when it sends the HTTP request. The following sample code illustrates both styles:

<queryString>uid=Bill&pwd=foo</queryString>

<!-- or -->

<queryStringParams>

  <param name="uid" value="Bill"/>
  <param name="pwd" value="foo"/>
</queryStringParams>

For the latter, the provider combines the param names and values into a queryString with a value of "uid=Bill&pwd=foo".

When the provider sends the request, it appends the queryString value to the url for the receiving server. For example, if the url for the receiving server is http://www.tailspintoys.com ?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "http://www.tailspintoys.com ?lcid=1033&uid=Bill&pwd=foo".

Parents:
requestInfo, rollbackInfo

queryStringParams Description:
 Individual parameter for the HTTP query.

There are two ways to pass parameters: as a single string in the queryString node or as param nodes of the queryStringParams node. Use the first style to pass an existing query string. Use the second style if you want the provider to build the query string for you from other input parameters when it sends the HTTP request. The following sample code illustrates both styles:

<queryString>uid=Bill&pwd=foo</queryString>

<!-- or -->

<queryStringParams>

  <param name="uid" value="Bill"/>
  <param name="pwd" value="foo"/>
</queryStringParams>

For the latter, the provider combines the param names and values into a queryString with a value of "uid=Bill&pwd=foo".

When the provider sends the request, it appends the queryString value to the url for the receiving server. For example, if the url for the receiving server is http://www.tailspintoys.com ?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "http://www.tailspintoys.com ?lcid=1033&uid=Bill&pwd=foo".

Parents:
requestInfo, rollbackInfo

Child:
param

param Description:
 Node that specifies a name/value pair for an input or output parameter. If either the name or value attribute does not have a value, then the param element is ignored. Illustrated by the following sample code: 
<param name="uid" value="Bill"/>

Parents:
httpHeaders, queryStringParams

Attributes:

name Required. The name for the parameter.
value Required. The value for the parameter.
password Description:
 User password that the Web server accepts for basic authentication.

Parents:
requestInfo, rollbackInfo

Maximum Length:
128
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.

Parents:
requestInfo, rollbackInfo

requestInfo Description:
 Encapsulates the information the provider uses to send the HTTP request.

Parent:
executeData

Children:
action (minOccurs="0" maxOccurs="1")
body (minOccurs="0" maxOccurs="1")
certificateName (minOccurs="0" maxOccurs="1")
certificateStore (minOccurs="0" maxOccurs="1")
connectionExclusionInterval (minOccurs="0" maxOccurs="1")
httpHeaders (minOccurs="0" maxOccurs="1")
header (minOccurs="1" maxOccurs="1")
password (minOccurs="0" maxOccurs="1")
queryString (minOccurs="0" maxOccurs="1")
queryStringParams (minOccurs="0" maxOccurs="1")
receiveTimeout (minOccurs="0" maxOccurs="1")
retryTimes (minOccurs="0" maxOccurs="1")
url (minOccurs="1" maxOccurs="1")
userId (minOccurs="0" maxOccurs="1")
userName (minOccurs="0" maxOccurs="1")
useTip (minOccurs="0" maxOccurs="1")
result Description: 
Encapsulates the response from the remote server. If the input XML does not explicitly specify a result node, the provider will create it for you.

Parent:
executeData

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.

Parents:
requestInfo, rollbackInfo

rollbackInfo Description: 
Encapsulates the transaction rollback information for the HTTP request.

Parent:
executeData

Children:
action (minOccurs="0" maxOccurs="1")
body (minOccurs="0" maxOccurs="1")
certificateName (minOccurs="0" maxOccurs="1")
certificateStore (minOccurs="0" maxOccurs="1")
httpHeaders (minOccurs="0" maxOccurs="1")
header (minOccurs="1" maxOccurs="1")
password (minOccurs="0" maxOccurs="1")
queryString (minOccurs="0" maxOccurs="1")
queryStringParams (minOccurs="0" maxOccurs="1")
receiveTimeout (minOccurs="0" maxOccurs="1")
retryTimes (minOccurs="0" maxOccurs="1")
url (minOccurs="1" maxOccurs="1")
userId (minOccurs="0" maxOccurs="1")
userName (minOccurs="0" maxOccurs="1")
url Description:
 URL of the host computer that receives the HTTP request from the provider. When the provider sends the request, it appends the queryString value to the url. For example, if the url is http://www.tailspintoys.com ?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "http://www.tailspintoys.com ?lcid=1033&uid=Bill&pwd=foo".

Parents:
requestInfo, rollbackInfo

Maximum Length:
4,096
userId Description:
 UI8 for the user logon ID. Not currently used.

Parents:
requestInfo, rollbackInfo

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

Parents:
requestInfo, rollbackInfo

Maximum Length:
128
useTip Description:
 Boolean that specifies whether transaction rollback is managed by the provisioning engine or by the server that owns the transaction. If useTip is "0" (false), the provisioning engine uses the information in the rollbackInfo node to execute the rollback. If useTip is "1" (true), the request does not need a rollbackInfo node and will ignore it if it is present. The provider retrieves the tipUrl server name from the request's transactionContext node and creates a child node for the SOAP header node. The following code illustrates a sample header node. 
<header>
  ...
  <tipUrl>tipUrl: http://www.microsoft.com/transaction</tipUrl>
</header>

If the input XML does not contain a header node, the provider creates one and populates it with the tipUrl.

Parent:
requestInfo

See Also

HTTP and SOAP Provider

Up Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.