Share via

HTTP and SOAP Provider::SoapRequest

  • Article

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, HTTP and SOAP Provider::SoapRequestWithNoRollback, supports requests such as queries that do not require rollback.) It is used by Microsoft Provisioning Framework (MPF).

Arguments

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 Providers [HMC SDK] 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 Engines [HMC SDK] 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 https://www.tailspintoys.com ?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "https://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 https://www.tailspintoys.com ?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "https://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:

nameRequired. The name for the parameter.
valueRequired. 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 https://www.tailspintoys.com ?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "https://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: https://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

Remarks

No remarks.

Schema Definition

Input

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

Output

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

Sample Code

Example XML Request

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.

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.

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::SoapRequestWithNoRollback