HTTP and SOAP Provider

Contains procedures to generate requests for remote Web servers and to encrypt request information. Used by Microsoft Provisioning Framework (MPF).

Implementation

Program Files\Microsoft Provisioning\Providers\MPFSoapProv.dll

Properties
Name SOAP Provider
Version 1
Provider Source Provisioning.SOAPProvider.1
Errors

The following table lists the errors returned by this provider.

HRESULT Description
0x80020004L Parameter not found.
0x80020005L Type mismatch.
0x80020006L Unknown name.
0x80020009L Exception occurred.
0x8002000EL Invalid number of parameters.
0x800401F3L Invalid class string.
0x8009030DL The credentials supplied to the package were not recognized.
0x80090322L The target principal name is incorrect.
0x80090325L The certificate chain was issued by an authority that is not trusted.
0x80090328L The received certificate has expired.
0x87000001L Unspecified httplib error.
0x8700000AL Error while sending or receiving data. The connection was possibly aborted.
0x8700000BL Engine failed because of a memory allocation error.
0x8700000CL A header was unsuccessfully parsed from the HTTP response.
0x8700000DL Attempt to combine relative URLs failed.
0x8700000EL The DNS queue is full. No more requests can be inserted.
0x8700000FL Failure connecting to the Web server.
0x87000010L Error sending data or the connection was aborted by the Web server.
0x87000011L Error receiving data or the connection was aborted by the Web server.
0x87000012L The DNS resolution failed or host could not be found.
0x87000013L The scheduler queue is full. No more requests can be inserted into it.
0x87000014L An external caller using ExternalAbort() forced the connection object to abort.
0x87000015L No valid HTTP response was received; request was possibly bad.
0x87000016L Unchunking of the HTTP response failed.
0x87000017L HTTP response parser failed.
0x87000018L Some error happened in SSL decoder; see extended error code.
0xC210106FL Multi-dimensional arrays not supported.
0xC2101070L Type '%1' not supported in Safe Arrays.
0xC2101071L Using the 'isXML' attribute requires exactly zero or one child element.
0xC5000001L The parameter 'Url' is missing. You must provide a URL for this operation.
0xC5000002L The parameter 'Url' is invalid. It exceeds the maximum allowed for a URL.
0xC5000003L The parameter 'Timeout' is invalid. It should be in the range '1,000-3,600,000'.
0xC5000004L Invalid HTTP METHOD used in the 'command' node, please use either GET or POST.
0xC5000005L The remote service is currently unavailable. Please try again later.
0xC5000006L The Operation timed out. The remote system didn't respond in a timely manner.
0xC5000007L The registry value '%1' has an invalid value. Please check the documentation for the allowed values.
0xC5000009L The HTTPS protocol is required for ExecuteAs, but it was not the protocol specified in a URL.
0xC500000AL SSL is required for ExecuteAs, but the UseSSL connector property was not set appropriately.
0xC500000BL The temporary directory '%1' was not found.
0xC5000020L Invalid SOAP response. Please check the SOAP envelope and namespace.
0xC5000021L SOAP response returns an unknown FAULT code.
0xC5000030L Cannot load certificate from either the user's store or the system store. Also check permissions to the system store.
0xC5000048L useTip is true, but tipUrl is not found from MPF.
0xC5000049L Invalid data type used. You may need to turn on schema validation.
0xC500004AL Site ID and key version are not specified in parameters nor registry.
0xC500004BL Passport manager was not installed when attempting to encrypt data.
0xC500004CL Invalid protocol used.
0xC500004DL An expected node is not present. You may need to turn on schema validation.
0xC5000051L SOAP fault is: VersionMismatch.
0xC5000052L SOAP fault is: MustUnderstand.
0xC5000053L SOAP fault is: Client.
0xC5000054L SOAP fault is: Server.
0xC5000100L Http and Soap Provider reported an error, HR='%1', %2 %3
0xC5000101L Failed to execute the HTTP(GET/POST) request. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000102L Failed to execute the HTTP(GET/POST) rollback request. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000103L Failed to execute the SOAP request. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000104L Failed to execute the SOAP rollback request. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000105L Failed to execute the WSDL request. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000106L Failed to execute the WSDL rollback request. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000107L Failed to execute the PassportEncrypt procedure. HR='%1' TransactionID='%2' ClientTransactionID='%3'.
0xC5000108L Required element '%1' was not found.
0xC5000109L The WSDL method '%1' was not found.
0xC500010AL Failed to get WSDL parameter '%1'.
0xC500010BL The WSDL port '%1' was not found.
0xC500010CL The WSDL service '%1' was not found.
0xC500010DL Incorrect number of parameters for the WSDL method.
0xC500010EL Failed to find WSDL parameter number %1.
0xC500010FL FinalConstruct failed.
0xC5000110L Unable to parse the URL '%1'.
0xC500012CL HTTP error 300. (All HTTP 3xx errors are just 0xC5000000 plus the error number)
0xC5000190L HTTP error 400. (All HTTP 4xx errors are just 0xC5000000 plus the error number)
0xC50001F4L HTTP error 500. (All HTTP 5xx errors are just 0xC5000000 plus the error number)

The following table lists additional SOAP Toolkit errors that can be returned by the WSDL procedures.

HRESULT ERROR
0x800A1388 AMBIGUOUS
0x800A13BA BAD_REQUEST
0x800A13BB ACCESS_DENIED
0x800A13BC FORBIDDEN
0x800A13BD NOT_FOUND
0x800A13BE BAD_METHOD
0x800A13BF REQ_TIMEOUT
0x800A13C0 CONFLICT
0x800A13C1 GONE
0x800A13C2 TOO_LARGE
0x800A13C3 ADDRESS
0x800A13EC SERVER_ERROR
0x800A13ED SRV_NOT_SUPPORTED
0x800A13EE BAD_GATEWAY
0x800A13EF NOT_AVAILABLE
0x800A13F0 SRV_TIMEOUT
0x800A13F1 VER_NOT_SUPPORTED
0x800A1450 BAD_CONTENT
0x800A1464 CONNECTION_ERROR
0x800A1465 BAD_CERTIFICATE_NAME
0x800A1BBC WSDL_MUSTUNDERSTAND
Remarks
Using the Provider with Secure Hypertext Transfer Protocol (S-HTTP):

Sending HTTP and SOAP requests using S-HTTP requires additional setup.

Customizing Registry Settings

Several Microsoft® Windows® registry values allow customization of the HTTP and SOAP Provider. These values are located in \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Provisioning\Providers\MPFSoapProv.

Value Description
CleanupSleepTime Number of milliseconds the cleanup thread sleeps before browsing the list of connections to clean up. Cleaning up connections locks out all threads from connections, which is why this should not be done too frequently.

Default Value: 120,000
Minimum Value: 0
Maximum Value: 4,294,967,295 (infinite)

CompletionThreads Number of completion threads to specify when initializing the provider's HTTP engine.

Default Value: 0 (auto-adjusts four threads per processor)
Minimum Value: 0
Maximum Value: 4,294,967,295 (infinite)

If either CompletionThreads or ConnectionThreads is zero, set both as follows:
CompletionThreads = 4 * number of CPUs
ConnectionThreads = ( number of CPUs + 1 ) / 2

ConnectionExclusionInterval Number of milliseconds to wait before re-attempting a failed connection with a server.

Default Value: 0 (no waiting)
Minimum Value: 0
Maximum Value: 345,600,000
Out-of-Range Action: Error

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 50,000 milliseconds), the provider re-attempts the connection.

This setting minimizes 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.

Connection unavailable time can be specified either in the registry or in individual requests (in the connectionExclusionInterval node). Requests use the default registry value whenever they do not have a value for connectionExclusionInterval.

Note: The provider adds a server to the bad server list only for the provisioning engine that executes the provider. Other engines include the server on their bad server lists only if they also experience a failure.

ConnectionThreads Number of connection threads to specify when initializing the provider's HTTP engine.

Default Value: 0 (auto-adjusts one thread for every two processors)
Minimum Value: 0
Maximum Value: 4,294,967,295 (infinite)

If either ConnectionThreads or CompletionThreads is zero, set both as follows:
ConnectionThreads = ( number of CPUs + 1 ) / 2
CompletionThreads = 4 * number of CPUs

ConnectionTimeout Number of milliseconds to waith for a server connection to complete before terminating and returning an error. The server connection can be shared and left open for multiple requests.

Default Value: 30,000
Minimum Value: 1
Maximum Value: 4,294,967,295 (infinite)
Out-of-Range Action: Error if value is zero

FailureTriggerForExclusionList Number of consecutive failures that must occur before a URL is included on a bad server list.

Default Value: 5
Minimum Value: 0
Maximum Value: 4,294,967,295 (full range of a DWORD)

LogEvents Identifies whether the provider logs transaction failures to the event log.

Default Value: 1 (logs events)
Minimum Value: 0 (disables logging)
Maximum Value: 1
Out-of-Range Action: Error

MaxConnections Number of connections a connection pool can contain. An attempt to generate additional connections will result in an error.

Default Value: 150
Minimum Value: MinConnections value
Maximum Value: 4,294,967,295
Out-of-Range Action: Error

MinConnections Number of connections a connection pool starts out with.

Default Value: 3
Minimum Value: 0
Maximum Value: 4,096
Out-of-Range Action: Error

RetrySleepTime Number of milliseconds to wait before retrying after receiving an erroneous response.

Default Value: 1,000
Minimum Value: 0
Maximum Value: 600,000
Out-of-Range Action: Error

ServerTTL Number of milliseconds to allow a server to remain inactive. If the cleanup thread is cleaning up and the server is inactive longer than this value, its pool of connections will be disconnected and deleted.

Default Value: 60,000
Minimum Value: 0
Maximum Value: 4,294,967,295

UseConnectionPool Boolean that specifies whether the provider uses connection pooling.

0: Connection pooling is disabled. Every request creates and destroys its own connection.

1 (default): A connection pool is created for each unique connection string, and connection objects are created and added to the pool as needed to satisfy the pool's minimum size requirement (as specified by the MinConnections setting).

UseProxy Boolean that specifies whether to use a proxy server.

0 (default): Do not use proxy server.

1: Use proxy server.

If you have difficulties getting the HTTP and SOAP Provider to connect to a remote server (for example, you keep getting DNS errors) and you have a proxy server on the network, change UseProxy to 1. Afterwards, shut down and restart the MPF provisioning engine in Administrative Tools, Component Services.

By default, the HTTP and SOAP Provider derives its proxy handling from the Internet Explorer proxy server settings defined for the MPFServiceAcct logon account. (In Internet Explorer, on the Tools menu, click Internet Options, click Connections, click LAN Settings, and then click Proxy server.) However, for security reasons, an Active Directory security policy might prohibit MPFServiceAcct from local logons. There are two ways to work around this situation.

First, you can disable the existing proxy setting and set the new proxy information directly into the Windows registry.

  1. Open Regedt32.exe.
  2. Add the following key/value of type REG_DWORD to the subkey \HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Internet Settings.

    ProxySettingsPerUser = 0
  3. Update the following subkey values for
    \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings

    ProxyEnable = 1
    ProxyServer = server:port #
    ProxyOverride = <local>

Alternatively, you can temporarily deactivate the security policy for MPFServiceAcct, then log on to update the proxy setting in Internet Explorer. Afterward, you would log off and re-establish the security policy for MPFServiceAcct.

Note The provider currently only supports a ProxyOverride value of "<local>". Other semicolon-delimited server names in the list are ignored.

Troubleshooting

The following table lists common problems and solutions.

Problem Solution
Proxy or DNS errors Consider setting the UseProxy registry key.
Server timeouts If a server application runs too slowly, you can review NetMon and PerfMon (for MPF performance counters such as Latency) or attach a debugger to the server process. If the timeout only occurs under stress, try increasing the NumThreads value for the registry key \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSSOAP\SOAPISAP on the server until there are enough threads to support the required load.
Invalid SSL certificate for WSDL procedures Use Internet Explorer to verify that the URL for the wsdlFile element works, then verify the service port address returned in the WSDL file. All three must use S-HTTP, and all three must have exactly the same target server name. The typical error codes are 0x80090322 and 0x80090325.
15-second delay in the first request to a server This problem can be caused by a DNS lookup timeout before a successful NetBIOS name lookup. Fix the DNS problem, use the IP address, or try the full DNS name.
Error 0x800401F3 This error occurs when a wsmlFile node is specified, but the object specified by the WSML file's ProgId is not installed on the same machine as the provider. To prevent this problem, either omit wsmlFile or install the object.
Public Methods
Procedure Description
HttpRequest Generates and sends Hypertext Transfer Protocol (HTTP) GET and POST requests to a remote Web server. This procedure supports requests that perform updates subject to rollback.
HttpRequestWithNoRollback Generates and sends HTTP GET 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.
PassportEncrypt Wrapper for Passport.Crypt object. Encrypts request information before passing it to a Microsoft® .NET Passport site.
SoapRequest Generates and sends Simple Object Access Protocol (SOAP) requests to a remote server. This procedure supports requests that perform updates subject to rollback.
SoapRequestWithNoRollback Generates and sends SOAP requests to a remote server. This procedure supports requests such as queries that do not require rollback in the event of a failure.
WSDLRequest Sends SOAP requests in Web Services Descriptor Language (WSDL) to COM objects on remote servers. This procedure supports requests that perform updates subject to rollback.
WSDLRequestWithNoRollback Sends SOAP requests in WSDL to COM objects on remote servers. This procedure supports requests such as queries that do not require rollback in the event of a failure.
 Applies To