HTTP and SOAP Provider::HttpRequestWithNoRollback


Generates and sends Hypertext Transfer Protocol (HTTP) GET, PUT and POST requests to a remote Web server. This procedure supports requests such as queries that do not require rollback in the event of a failure. (A related procedure, HttpRequest, provides rollback for requests that perform updates.) 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>
	<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>
  <result>0..1</result>
</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 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 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".

Parent:
requestInfo

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

Parent:
requestInfo

Child:
param

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

Parent:
requestInfo

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.

Parent:
requestInfo

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 engine that executes the provider. Other engines will not list the server unless they also fail to execute requests against it.

Parents:
requestInfo

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

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.

Parent:
requestInfo

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

Parent:
requestInfo

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 .com?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "http://www.tailspintoys.com .com?lcid=1033&uid=Bill&pwd=foo".

Parent:
requestInfo

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

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.

Parent:
requestInfo

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.

Parent:
requestInfo

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 .com?lcid=1033 and queryString is "uid=Bill&pwd=foo", the combined value is "http://www.tailspintoys.com .com?lcid=1033&uid=Bill&pwd=foo".

Parent:
requestInfo

Maximum Length:
4,096

userId Description:
UI8 for the user logon ID. Not currently used.

Parent:
requestInfo

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

Parent:
requestInfo

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 "1" (true),  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: http://www.microsoft.com/transaction

Parent:
requestInfo

See Also

HTTP and SOAP Provider


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