1. Introduction

SoapAgent is a C++ library for accessing web services. With the library, you can access web services using just a few lines of code with no SOAP or XML knowledge required. The library is an independent implementation of SOAP 1.1 specification. It supports Web Service Definition Language (WSDL).

The library was built using Microsoft VC++ 6.0 as a multi-threaded DLL.

1.1. Key Features

Support WSDL and WSDL import
Flexible SOAP Message Template (See below).
independent of third party components.
Embedded transport protocols.
Plug-in SAX XML Parser.
Light weight, with very small memory footprint.
Work on Win 95/98/NT/2000.
Compatible with many SOAP 1.1 implementations.
Capable of handling any data types (with message templates).

1.2. Limitations

The version 3.0 of the library has the following limitations:

Works only on Windows platform.
Supports only UTF-8 encoding

2. Installation

The installation is very easy. After downloading the library, run the installation program. It will copy the following files into the specified directory:

Sample: A directory contains a sample SOAP client function.

SoapActor.lib: The exported library.

SoapClient.doc: The programming guide

SoapClient.lic: A generated license file. It is required for using SoapAgent.dll

SoapClientApi.h: The main header file.

SoapActor.dll: The SoapAgent implementation library.

SoapTest.exe: A small test program.

XMLParser.dll: The XML Parser implementation.

dbsock.dll: A SOAP transport DLL.

SoapAgents.dll: A COM wrapper of the SOAP client library.

license.txt: The license agreement.

readme.txt: Last minutes changes and other information.

The SAMPLE subdirectory contains a sample project that demonstrates how to use the library.

3. Using the library

3.1. Environment Settings

Include the SoapClientApi..h file in your project, remember to add the include directory to the INCLUDE environment variable.
Make sure your linker can locate SoapActor.lib by adding it to your LIB path.
Put the BIN subdirectory into your PATH environment variable.
Copy the license file, soapclient.lic, to your application directory.

3.2. SoapAgent definition

All SOAP client services are provided inside a SoapAgent class. Its definition is in the SoapClientApi.h file. The file defines a pure virtual class and two exported functions from the class factory:

class SOAPAPI SoapAgent

{

public:

// execute a SOAP method given an WSDL file

virtual HRESULT ExecuteMethod(const TCHAR* szWSDL, const TCHAR* szMethodName, TCHAR** ppInputName, TCHAR** ppInputValue, vector<t_string>** ppOutputArray)=0;

// execute a SOAP method given a message template

virtual HRESULT ExecuteMethod(const TCHAR* szServerURI, const TCHAR* szTemplateFile, const TCHAR* szSoapAction, TCHAR**ppNameArray, TCHAR** ppInputArray, vector<t_string>**ppOutputArray)=0;

// set the proxy

virtual void SetProxy(const TCHAR* szProxyServer, short nPort=80, const TCHAR* szProxyUser=NULL, const TCHAR* bstrProxyPwd=NULL)=0;

// get error description

virtual TCHAR *GetErrorString()=0;

// set the http request header

virtual void SetHeader(const TCHAR* szName, const TCHAR * szValue)=0;

// set soap header

virtual void SetSoapHeader(const TCHAR* szName, const TCHAR * szValue, const TCHAR** pAttributeNames=NULL, const TCHAR** pAttributeValues=NULL)=0;

// clear the request and response objects

virtual void Clear()=0;

// get the complete response string or a particular element

virtual TCHAR* GetResponse(const TCHAR* szElementName, bool bUseNamespace)=0;

// instantiate a template file using soap response

virtual TCHAR* InstantiateTemplate(const TCHAR* szFileName, const TCHAR * szXMLString)=0;

};

extern "C" SoapAgent* MakeSoapAgent(const TCHAR* szUserName, const TCHAR* szPassword, int nDebugMode=0,const TCHAR* szCertFile=NULL);

extern "C" void DestroySoapAgent(SoapAgent* );

The SoapAgent specification is implemented inside the library, as the matter of fact, there are several implementations of the class. The class library creates a type of SoapAgent object based on the current configuration and the nature of the invocation.

There is no constructor and destructors in SoapAgent definition, so it cannot be constructed using the new operator. Instead, the library offers two exported functions: MakeSoapAgent and DestroySoapAgent, for object management.

3.3. Using SoapAgent Objects

Here are some simple steps for using the SoapAgent object:

1. Create a SoapAgent Object:
SoapAgent * pMyAgent= MakeSoapAgent(NULL, NULL);

2. Define an array of parameters to be passed to the remote server.

3. Call the ExecuteMethod function and specify the WSDL and name of the method to be executed.

4. Process the returned results.

5. Destroy the SoapAgent using the DestroySoapAgent function.

This is best illustrated by the sample program below.

3.3.1. A Sample Program

The sample shows how to write a SOAP client using SQLData SoapAgent object. The function invokes the Method1 method provided by a test web service at http://www.SoapClient.com, which echoes the two input string parameters.

SoapResponder()

{

// initialize input parameters.

TCHAR * ppParamNames[3]={"bstrParam1", "bstrParam2", NULL};

TCHAR * ppParamValues[3]={ "My First Param", "My Second Param", NULL};

// create a soapagent in debug mode (mode=4)

SoapAgent *pSoapAgent= MakeSoapAgent(NULL, NULL, 4);

if(pSoapAgent==NULL)

return -1;

HRESULT hr;

if(SUCCEEDED(hr=pSoapAgent->ExecuteMethod(

"https://soapclient.com/xml/soapresponder.wsdl", // WSDL file

"Method1", // method name to be invoked.

vParamNames, // vector of input parameter names.

vParamValues, // vector of input parameter values.

&pOutputValues // pointer to a vector of output parameters

)))

{

// print out results

int nSize = pOutputValues->size();

for(int i=0; i<nSize; i++)

_tprintf("%s\n", (*pOutputValues)[i].c_str());

}

else

{

// obtain error string when failed.

_tprintf("Error String %s\n", pSoapAgent->GetErrorString());