Share via

HTTP and SOAP Provider::HttpRequest

  • Article

Generates and sends Hypertext Transfer Protocol (HTTP) GET, PUT and POST requests to a remote Web 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.) Used by Microsoft Provisioning Framework (MPF).

Arguments

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

Element Description, relationships, and attributes

body

Description:
Content posted for HTTP POST or PUT requests. Required for HTTP POST or PUT requests; not used for GET requests. Illustrated by the following sample code:

<body>username=Bill&password=foo</body>

There are two ways to pass parameters: as a single string in the body node or as param nodes of the bodyParams node. Use the first style to pass an existing parameter string. Use the second style if you want the Providers [HMC SDK] to build the query string for you from other input parameters when it sends the POST or PUT request. The following sample code illustrates this:

<body>username=Bill&password=foo</body>, 
 
<!-- or --> 
 
<bodyParams> 
  <param name="username" value="Bill"/> 
  <param name="password" value="foo"/> 
<bodyParams>

For the latter, the provider combines the param names and values into a body with a value of "username=Bill&password=foo".

Parents:
requestInfo, rollbackInfo

bodyParams

Description:
List of parameters for HTTP POST or PUT requests. Not used for GET requests.

There are two ways to pass parameters: as a single string in the body node or as param nodes of the bodyParams node. Use the first style to pass an existing parameter 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 POST or PUT request. The following sample code illustrates both styles:

<body>username=Bill&password=foo</body>, 
 
<!-- or --> 
 
<bodyParams> 
  <param name="username" value="Bill"/> 
  <param name="password" value="foo"/> 
<bodyParams>

For the latter, the provider combines the param names and values into a body with a value of "username=Bill&password=foo".

Parents:
requestInfo, rollbackInfo

Child:
param

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

command

Description:
Enumeration that specifies the type of HTTP request: GET, POST or PUT.

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

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

httpHeaders

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

Parents:
requestInfo, rollbackInfo

Child:
param

ignoreRedirect

Description:
Boolean that specifies whether the provider executes a redirect when it receives an HTTP 302 "Object Moved" response. If "0" (false, default), the provider automatically redirects to the new URL.

Parent:
requestInfo

isXML

Description:
Boolean that specifies whether the HTTP POST or PUT request body is in XML. Used only for HTTP POST or PUT requests.

If this element is not specified, the provider loads the body into an XML DOM so it can determine whether the body is XML and apply the appropriate Content-Type header to the HTTP request. This process consumes more cycles than necessary. If you specifically include this element, the DOM load is bypassed, which improves performance.

Parent:
requestInfo

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 .com?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "https://www.tailspintoys.com .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:
body (minOccurs="0" maxOccurs="1")
bodyParams (minOccurs="0" maxOccurs="1")
certificateName (minOccurs="0" maxOccurs="1")
certificateStore (minOccurs="0" maxOccurs="1")
command (minOccurs="1" maxOccurs="1")
connectionExclusionInterval (minOccurs="0" maxOccurs="1")
httpHeaders (minOccurs="0" maxOccurs="1")
isXML (minOccurs="0" 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:
body (minOccurs="0" maxOccurs="1")
bodyParams (minOccurs="0" maxOccurs="1")
certificateName (minOccurs="0" maxOccurs="1")
certificateStore (minOccurs="0" maxOccurs="1")
command (minOccurs="1" maxOccurs="1")
httpHeaders (minOccurs="0" maxOccurs="1")
ignoreRedirect (minOccurs="0" 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 .com?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "https://www.tailspintoys.com .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 appends it to the HTTP header. The following code illustrates a sample HTTP header:

GET /articles/news/today.asp HTTP/1.1 
Accept: */* 
Accept-Language: en-us 
Connection: Keep-Alive 
Host: www.microsoft.com 
User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) 
Accept-Encoding: gzip, deflate 
tipUrl: https://www.microsoft.com/transaction

Parent:
requestInfo

Remarks

No remarks.

Schema Definition

Input

<executeData>1..1
  <requestInfo>1..1
    <useTip>0..1</useTip>
    <isXML>0..1</isXML>
    <url>1..1</url>
    <queryString>0..1</queryString>
    <queryStringParams>0..1
      <param name=".." value="..">1..unbounded</param>
    </queryStringParams>
    <httpHeaders>
      <param name=".." value="..">1..unbounded</param>
    </httpHeaders>
    <command>1..1</command>
    <body>0..1</body>
    <bodyParams>0..1</body>
      <param name=".." value="..">1..unbounded</param>
    <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>
    <ignoreRedirect>0..1</ignoreRedirect>
    <codePageAutoDetect>0..1</codePageAutoDetect>
    <codePage>0..1</codePage>
  </requestInfo>
  <rollbackInfo>0..1
    <url>1..1</url>
    <queryString>0..1</queryString>
    <queryStringParams>0..1
      <param name=".." value="..">1..unbounded</param>
    </queryStringParams>
    <httpHeaders>
      <param name=".." value="..">1..unbounded</param>
    </httpHeaders>
    <command>1..1</command>
    <body>0..1</body>
    <bodyParams>0..1</body>
      <param name=".." value="..">1..unbounded</param>
    <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>
  </rollbackInfo>
  <result>0..1</result>
</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::HttpRequestWithNoRollback