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