SOAP Client in Windows XP

Bosco Wilfred
18y
62.9k
0
0

Article

EXECUTIVE SUMMARY

This article covers the basics of using the SOAP Client software included with Microsoft Windows XP Professional to access Web Services using SOAP. It begins with a brief introduction to SOAP and WSDL standards and then discusses how to implement a client that can communicate with a SOAP-enabled Web service.

INTRODUCTION

Microsoft Windows XP Professional includes the client portion of the Microsoft SOAP Toolkit 2.0, making it possible to build SOAP client applications or to distribute them to Windows XP Professional clients without distributing the client portions of the SOAP Toolkit 2.0. This paper covers the basics of using the SOAP client software included with Windows XP to access Web services using SOAP. It begins with a brief introduction to SOAP and Web Services Description Language (WSDL) standards, and then discusses how to implement a client that can communicate with a SOAP-enabled Web service.

What Is SOAP?

SOAP, which stands for Simple Object Access Protocol, is defined by the SOAP standard available at http://www.w3.org/TR/SOAP. The SOAP protocol defines the format of standard XML messages that are used to communicate among systems. Because the message format is standardized and based on the XML standard, SOAP can be used to communicate among multiple computer architectures, languages, and operating systems. SOAP enables a new class of applications called Web services, which expose services in a standard way so that application developers can create new applications by putting together services from many different sources on the Web.

There are four main areas covered by the SOAP specification: a required SOAP Envelope format that defines what the envelope that surrounds the XML content of a SOAP message must look like; an optional set of encoding rules that defines how language types are mapped to XML in a SOAP message (since this is defined in section 5 of the specification, it is referred to as "section 5 encoding"); an optional RPC format that defines how function calls are expressed in SOAP messages; and an HTTP binding that defines how SOAP messages may be exchanged through HTTP. HTTP is the only communications protocol binding defined by the standard; thus almost all SOAP implementations include an HTTP binding. Note that SOAP doesn't impose limitations on what other communications protocols can be used to transport SOAP messages.

Here's a simple SOAP message:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAPSDK1:Add xmlns:SOAPSDK1="http://tempuri.org/message/">
<a>333</a>
<b>888</b>
</SOAPSDK1:Add>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Let's go through this in detail to understand the format of a SOAP message. The first line is the XML declaration that defines the character set used in the SOAP document. The Envelope element is a required element that is always the root of a SOAP message, and is always in the "http://schemas.xmlsoap.org/soap/envelope/" namespace.

The SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" attribute defines the encoding style used in the message. In this case, standard section 5 encoding is used. The Body sub element of the Envelope element contains the SOAP Message. As defined in section 7 of the SOAP specification, the Add element represents a call on an operation named Add. The sub elements of Add are the parameters of the Add method call.

The response to this message would look like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAPSDK1:AddResponse xmlns:SOAPSDK1="http://tempuri.org/message/">
<Result>1221</Result>
</SOAPSDK1:AddResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

What Is WSDL?

WSDL stands for Web Service Definition Language. In order to successfully call a Web service you will need to know how to get to the service, what operations the service supports, what parameters the service expects, and what the service returns. WSDL provides all of this information in an XML document that can be read or machine-processed.

To understand the format of a WSDL file, let's examine the following WSDL file:

<?xml version="1.0" encoding="UTF-8" ?>
<definitions name="net.xmethods.services.currencyexchange.CurrencyExchange"
targetNamespace="http://www.themindelectric.com/wsdl/
net.xmethods.services.currencyexchange.CurrencyExchange/"
xmlns:tns="http://www.themindelectric.com/wsdl/
net.xmethods.services.currencyexchange.CurrencyExchange/"
xmlns:electric=http://www.themindelectric.com/
xmlns:soap=http://schemas.xmlsoap.org/wsdl/soap/
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:soapenc=http://schemas.xmlsoap.org/soap/encoding/
xmlns:wsdl=http://schemas.xmlsoap.org/wsdl/
xmlns="http://schemas.xmlsoap.org/wsdl/">
<message name="getRateRequest1">
<part name="country1" type="xsd:string" />
<part name="country2" type="xsd:string" />
</message>
<message name="getRateResponse1">
<part name="Result" type="xsd:float" />
</message>
<portType name="net.xmethods.services.
currencyexchange.CurrencyExchangePortType">
<operation name="getRate" parameterOrder="country1 country2">
<input message="tns:getRateRequest1" />
<output message="tns:getRateResponse1" />
</operation>
</portType>
<binding
name="net.xmethods.services.currencyexchange.CurrencyExchangeBinding"
type="tns:net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="getRate">
<soap:operation soapAction="urn:xmethods-CurrencyExchange#getRate" />
<input>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>
<service name="net.xmethods.services.currencyexchange.CurrencyExchangeService">
<documentation>
net.xmethods.services.currencyexchange.CurrencyExchange web service
</documentation>
<port name="net.xmethods.services.currencyexchange.CurrencyExchangePort"
binding="tns:net.xmethods.services.currencyexchange.CurrencyExchangeBinding">
<soap:address location="http://206.135.115.109:9090/soap" />
</port>
</service>
</definitions>

This is the WSDL file for an exchange rate service implemented in Glue from The Mind Electric. Therefore, the format is not identical to a Microsoft SOAP Toolkit WSDL file, but it is compatible. The first element of the WSDL file is the definitions element, which is the root element of the file and normally contains several namespace declarations:

Note that the xsd namespace is the 2001 version. The SOAP Toolkit defaults to the 2001 Recommendation version of the XSD Schema namespace but it can understand WSDL files written with older namespace versions.

If the WSDL used any complex types, the XSD Schema definition for these types would be contained in a <types></types> element. Since this WSDL file doesn't use any complex types, that element is missing.

The next section defines the messages used by the service defined in this WSDL:

<message name="getRateRequest1">
<part name="country1" type="xsd:string" />
<part name="country2" type="xsd:string" />
</message>
<message name="getRateResponse1">
<part name="Result" type="xsd:float" />
</message>

The names and datatypes of the method parameters are defined here.

The portType element defines a mapping between the messages defined in the previous section and the operations that use them:

<portType name="net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<operation name="getRate" parameterOrder="country1 country2">
<input message="tns:getRateRequest1" />
<output message="tns:getRateResponse1" />
</operation>
</portType>

The binding element defines a binding between the abstract operations defined in the portType element and how they are implemented in SOAP. This is done is a separate element because WSDL is intended to define other non-SOAP protocols. A few thing to note here: the style="rpc" means that this message uses the rpc rules defined in section 7 of the SOAP standard. If style="document" was specified, the contents of the SOAP message would be an XML document. The transport attribute indicates that the SOAP messages will be sent in SOAP HTTP messages, the soapAction attribute defines the contents of the soapAction header in the HTTP packet, and the use="encoded" attribute indicates that SOAP section 5 encoding is used for parameter values.

<portType name="net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<operation name="getRate" parameterOrder="country1 country2">
<input message="tns:getRateRequest1" />
<output message="tns:getRateResponse1" />
</operation>
</portType>
<binding name="net.xmethods.services.currencyexchange.CurrencyExchangeBinding"
type="tns:net.xmethods.services.currencyexchange.CurrencyExchangePortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="getRate">
<soap:operation soapAction="urn:xmethods-CurrencyExchange#getRate" />
<input>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</input>
<output>
<soap:body use="encoded" namespace="urn:xmethods-CurrencyExchange"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding>

The service element ties a SOAP binding to a physical implementation of the service. This is where the URL of the service is defined. Notice that this service is found at port 9090—SOAP doesn't just work through port 80. (There is also a copy of the service running on port 80 if your firewall requires you to use port 80.)<service name="net.xmethods.services.currencyexchange.CurrencyExchangeService">
<documentation>
net.xmethods.services.currencyexchange.CurrencyExchange web service
</documentation>
<port name="net.xmethods.services.currencyexchange.CurrencyExchangePort"
binding="tns:net.xmethods.services.currencyexchange.CurrencyExchangeBinding">
<soap:address location="http://206.135.115.109:9090/soap" />
</port>
</service>

The SOAP Client Object

This section reviews the object model exposed by the SOAPClient object. Each method and property exposed by the SOAPClient is described.

Mssoapinit Method

The mssoapinit method initializes the SOAPClient object using the Web Services Description Language (WSDL) file as input. All of the operations in the identified service are bound to the SOAPClient object during initialization. Thus, you can call the operations defined in the service using the SOAPClient object.

Method definition

HRESULT mssoapinit(
[in] BSTR bstrWSDLFile,
[in, optional, defaultvalue("")] BSTR bstrServiceName,
[in, optional, defaultvalue("")] BSTR bstrPort,
[in, optional, defaultvalue("")] BSTR bstrWSMLFile);

Parameters

bstrWSDLFile

bstrWSDLFile is the URL of the WSDL file that describes the services offered by the server.

bstrServiceName

bstrServiceName is the optional service in the WSDL file that contains the operation specified in the Simple Object Access Protocol (SOAP) request. If this parameter is missing, null, or an empty string, the mssoapinit method uses the first service in the specified WSDL file when initializing the SOAPClient object.

bstrPort

bstrPort, also optional, is the name of the port in the WSDL file that contains the operation specified in the SOAP request. If this parameter is missing, null, or an empty string, the mssoapinit method uses the first port in the specified service when initializing the SOAPClient object.

bstrWSMLFile, also optional, is the URL of the Web Services Meta Language (WSML) file. This is a required parameter only when using custom type mappers.

Visual Basic syntax

Sub mssoapinit(bstrWSDLFile As String,_
[bstrServiceName As String],_
[bstrPort As String],_
[bstrWSMLFile As String])

Visual Basic example

set soapclient = CreateObject("MSSOAP.SOAPClient")
call soapclient.mssoapinit("DocSample1.wsdl", "", "", "")
wscript.echo soapclient.AddNumbers(2,3)
wscript.echo soapclient.SubtractNumbers(3,2)

Remarks

The mssoapinit method is part of the high-level API on the client side. To use this method, you must first create a SOAPClient object on the client. Then, call the mssoapinit method using the WSDL file name, service name, and port name as parameters. Now the client can call any operations defined in the WSDL file for the requested service or port.

ClientProperty Property

The ClientProperty property sets and retrieves properties specific to the SOAPClient object.

Method definition

[propget] HRESULT ClientProperty(
[in] BSTR PropertyName,
[out, retval] VARIANT* pPropertyValue);

[propput] HRESULT ClientProperty(
[in] BSTR PropertyName,
[in] VARIANT pPropertyValue);

Parameters

PropertyName PropertyName is the name of the property to set or retrieve. See the following Remarks section for a list of properties. The following properties are supported (the property names are case sensitive):

Property Name	Description
ServerHTTPRequest	A True/False value indicating whether to use the "server-safe" XML components to load the Web Services Description Language (WSDL) and Web Services Meta Language (WSML) files. Set to True when an Active Server Pages (ASP) application or an ISAPI DLL uses the SOAPClient object. When ServerHTTPRequest is set to true, the WinHTTP Proxy Configuration Utility must be used to configure WinHTTP. This is necessary even if a proxy server is not being used
ConnectorProgID	Specifies the ProgID of a class that implements the ISOAPConnector interface. Will create and use objects of this class when sending requests to the service. When set to an empty string, the default value, SOAPClient uses a SOAPConnectorFactory object to create a connector for the transport protocol specified the WSDL.

pPropertyValue

pPropertyValue is the property's value.

Visual Basic syntax

Property ClientProperty(ByVal PropertyName As String) As Object

Visual Basic example

Dim Client As New SOAPClient
Client.ClientProperty("ServerHTTPRequest") = True

ConnectorProperty Property

Sets and retrieves properties specific to the transport protocol connector used by a SOAPClient object.

Method definition

[propget] HRESULT ConnectorProperty (
[in] BSTR PropertyName,
[out, retval] VARIANT* pPropertyValue);

[propput] HRESULT ConnectorProperty (
[in] BSTR PropertyName,
[in] VARIANT pPropertyValue);

Parameters

PropertyName

PropertyName is the name of the property to set or retrieve. Which properties are supported depends on the connector being used. The protocol specified by the <soap:binding> transport attribute in the Web Services Description Language (WSDL) file determines the connector to use.

pPropertyValue

pPropertyValue is the value of the property.

Visual Basic syntax

Property ConnectorProperty(ByVal PropertyName As String)

Visual Basic example

Dim Client As New SOAPClient
Client.mssoapinit WSDLFile, Service, Port
Client.ConnectorProperty("ProxyUser") = User
Client.ConnectorProperty("ProxyPassword") = Password

Connector properties

Property	Description
AuthPassword	The password used for end point authentication.
AuthUser	The user name used for end point authentication.
EndPointURL	The end point URL.
ProxyPassword	The password used for proxy authentication.
ProxyPort	The port of the proxy server to use.
ProxyServer	The IP address or host name of the proxy server
ProxyUser	The user name used for proxy authentication.
SOAPAction	The value used in the SOAPAction HTTP header.
SSLClientCertificateName	A string identifying the client certificate to use for the Secure Sockets Layer (SSL) protocol, if any. The syntax is: [CURRENT_USER \| LOCAL_MACHINE\[store-name\]]cert-name with the defaults being CURRENT_USER\MY (the same store that Microsoft Internet Explorer uses).
Timeout	The timeout for HttpConnector. This timeout is in milliseconds.
UseSSL	A Boolean value (true or false) that specifies the use of SSL.

Detail Property

The detail property is read-only. It provides the value of the <detail> element of the <Fault> element in the Simple Object Access Protocol (SOAP) message.

Method definition

[propget] HRESULT detail(
[out, retval] BSTR* bstrDetail);

Parameters

bstrDetail

bstrDetail is the detail of the fault.

Visual Basic syntax

Property detail() As String

HeaderHandler (SOAPClient)

Sets the header handler for the next call against this client instance.

Method definition

HRESULT HeaderHandler([in] IDispatch* rhs);

Parameters

rhs

rhs is the reference to the COM class interface that implements the IHeaderHandler.

Visual Basic syntax

Property HeaderHandler() As Object

Visual Basic example

Set sc = WScript.CreateObject("MSSOAP.SOAPClient")
sc.mssoapinit=http://localhost/DocSample7/DocSample7.wsdl
sc.HeaderHandler = WScript.CreateObject("SessionInfoClient.clientHeaderHandler")
Sc.SomeMethod "param1", "param2"

Faultactor Property (SOAPClient)

The faultactor property is read-only, and provides the Universal Resource Identifier (URI) that generated the fault.

Method definition

[propget] HRESULT faultactor(
[out, retval] BSTR* bstrActor);

Parameters

bstrActor

The bstrActor is the URI that generated the fault.

Visual Basic syntax

Property faultactor() As String

Visual Basic example

wscript.echo soapclient.faultactor

Faultcode Property (SOAPClient)

The faultcode property is read-only. It provides the value of the <faultcode> element of the <Fault> element in the Simple Object Access Protocol (SOAP) message.

Method definition

[propget] HRESULT faultcode(
[out, retval] BSTR* bstrFaultcode);

Parameters

bstrFaultcode

bstrFaultcode is the value of the <faultcode> element.

Visual Basic syntax

Property faultcode() As String

Visual Basic example

wscript.echo soapclient.faultcode

Faultstring Property (SOAPClient)

This faultstring property is read-only. It provides the value of the <faultstring> element of the <Fault> element in the Simple Object Access Protocol (SOAP) message.

Method definition

[propget] HRESULT faultstring(
[out, retval] BSTR* bstrFaultstring);

Parameters

bstrFaultstring

bstrFaultstring is the value of the <faultstring> element.

Visual Basic syntax

Property faultstring() As String

Visual Basic example

wscript.echo soapclient.faultstring

For More Information and Referred

http://msdn.microsoft.com/soap/

Up Next

Ebook Download

View all

Printing in C# Made Easy

Read by 10.8k people

Download Now!

Learn

View all