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