
The c++wsp_src.zip contains the following files and folders.
 - readme.txt  (this file)
 - license.txt 
 - servlet_app_readme.txt
 - gsop-license.pdf
 - /cpp_servlet_lib
 - /mod_cpp_servlet
 - /servlet_container    
 - /user_servlets        - example servlets
 - /user_servlet/soap    - SOAPServlet and soap applications

Setup
=====
To setup the C++WSP platform, you need to have these s/w on your machine.
 1. Apache Web Server (Win32) version 2.0.40
 2. gSOAP (win32) version 2.1.7
 3. ACE version 5.2.1
 4. Xerces-C++ Version 1.7.0

To compile the projects, you might have to change the include paths and lib paths
depending on the location where these s/w are installed. 



Steps to create your own SOAP application for CPP servlet container, which utilizes and integrates with gsoap:


PLEASE NOTE: As of now the instructions are only for Win32 systems and for 
Visual studio (VC++ compiler)

The high level steps to create a SOAP application are as following:

1) Install gsoap version 2.1.7 (Will be installed automatically if used the C++WSP installer)
2) Create a SOAP application(.dll) by following the steps described under 
   "Developing C++ SOAP application".
3) Deploy the SOAP application under CPP servlet engine by following the steps
   described under "Deploying the C++ SOAP application".
4) Test the application by following the steps under 
   "Testing the C++ SOAP application".

Developing C++ SOAP application
-------------------------------

NOTE: Please refer to the gsoap documentation (soapdoc2.pdf in the gsoap install location) for
detailed instructions and theory on gsoap.

The steps below explain the creation of a SOAP application by using an example 
application called trysoap.

1) Create a project of type empty dll. Chose the location as C++WSP\DEV\SRC\SOAP\APPS 
2) Create a header file (.h) and add it to the project. Put the functions you want to 
   expose as SOAP interface in these header file.
   // e.g. contents of trysoap.h
   typedef struct ResponseStruct
   {
   	int status;
   	char * message;
   } Response;
   
   // struct ReponseStruct & rS
   int Infosys__trySoap(char * name, Response * rS);

   NOTE: Infosys is the name space
    gsoap takes the first part of the function name preceeding 2 _'s (two 
    underscores as the name space of the function. It will generate a <namespace.wsdl>
    file for each namespace encountered.  
   
 3) Compile this header file using the gsoap compiler soapcpp2. It can be found under C++WSP\dev\soap-2.1.7
 e.g. soapcpp2 trysoap.h
 It will generate the following files:
  soapStub.h, soapH.h, soapC.cpp, soapClient.cpp, soapServer.cpp
  
  Apart from the above code files, it also generated the following files:
  
   Infosys.wsdl Web Service description
   Infosys.trySoap.req.xml ( sample SOAP/XML request )
   Infosys.trySoap.res.xml ( sample SOAP/XML response )
   Infosys.nsmap            ( namespace mapping table )
   Infosys.xsd              ( XML schema description )
   
 4) Add the .h and .cpp files to your project
   a) Add the files soapStub.h, soapH.h, soapC.cpp, soapServer.cpp to the project.
     The file soapClient.cpp will be needed to develop the test client.
 
   b) Add the filed stdsoap2.h and stdsoap2.cpp. to the project. You can get these two 
     files from the gsoap install location(i.e. C++WSP\dev\soap-2.1.7) . These two files have all the code that you need
     from gsoap installable.
 
 5) Provide the implementation of the service method.
 Create a file called trysoapImpl.cpp and put the definition there. Broadly you 
 need to do the following things
 a) Include the generated soapH.h and SOAPHandlerFactory.h
 b) Register the soap resource to the SOAP Handler Factory, add the following line 
    in the implementation (i.e. trysoapImpl.cpp)
     REGISTER_SOAP_RESOURCE("trysoap", trysoap)
 c) Add the definition for the function with signature having struct soap * as the
    first argument
    For our example: add the definition for the following function
    int Infosys__trySoap(struct soap * s, char * name, Response * rS);
 d) Add the struct having the definition of name spaces - Copy and paste the contents of 
    the generated file of type nsmap e.g. Infosys.nsmap
    
 6) Compilation of the SOAP application to a DLL
   a) Ensure In the VC++ studio the compile option option /MDd is set. Check by 
      clicking on the menu Project -> Settings and then on  'C/C++' tab
      on the resulting window. In many cases the default might be /MTd, if it is overwrite it with /MDd.
   b) Also ensure that the include path has the path to the dev/include/soap/ directory i.e
      the directory having the include files for the SOAPServlet (SOAP adaptor for this 
      application. e.g.  /I "../../../../include/soap"
   c) On the same window (in step [a] above) click on the 'link' tab and enter the
      path to the libraries on which the soap application is dependent. It has dependencies 
      to the following two libraries. Also add the paths to the libraries it uses as part 
      of the application logic, if any.
      i) library SOAPServlet.lib e.g. ../../../../lib/SOAPServlet.lib
      ii) wsock32.lib
   d) You may add the following pragma directive as the first line of the code in your implemenetation
      (e.g. trysoapImpl.cpp) to get rid of the template related warnings.
      #pragma warning ( disable : 4786 )
    

Developing C++ SOAP test client
-------------------------------

To test the application we need a test client. The steps below describe the same. 
Please refer to the gsoap documentation (soapdoc2.pdf in the gsoap install location) for
detailed instructions and theory on gsoap.

1) Create a VC++ project of type "Console Application". To test our example application "trysoap"
which we created by following the steps in the section 'Developing C++ SOAP application',
let us create a project named trysoapclient. Choose the location as the soap application you developed 
e.g. C++WSP\dev\src\soap\apps\trysoap

2) Add the files generated by soapcpp2 application and set the appropriate 
include paths
  a) Add the generated soapClient.cpp. Also add stdsoap2.cpp, soapC.cpp.
  b) add the include path to the directory having the header files for the 
    soap application and also the path for stdsoap2.h  e.g. /I "../../trysoap" /I "../../../../../include/soap"
  c) Create and add a source file having the main program. Look at the samples as 
  part of gsoap installable (e.g. C++WSP\dev\src\soap\apps\trysoap\trysoapclient\trysoapclientmain.cpp ) to
  write your client program. 
    The call to soap server for our trysoap example is given below:
    soap_call_Infosys__trySoap(&soap, "http://192.168.206.90:80/cpp_servlet/soap/SOAPServlet?soap_res=trysoap", NULL, name, &rs)
    Please note that the breakup of the URL 192.168.206.90:80/cpp_servlet/soap/SOAPServlet?soap_res=trysoap
    is as following:
    192.168.206.90:80 host and port where apache web server (and hence soap application) is listening
    cpp_servlet       directive to apache to hand over this request to the servlet engine
    soap              soap application deployed as a cpp_servlet application
    SOAPServlet       The servlet name withing the SOAP application
    soap_res=trysoap  The parameters to the servlet. If your soap application 
                      name is cow you should do soap_res=cow 
                      
  d) Add wsock32.lib in the Link tab of the window got by clicking the menu
  Project -> Settings
  e) compile to get the the client exe (trysoapclient.exe in our example)
   
Deploying the C++ SOAP application
----------------------------------
The instructions to deploy your soap application on C++WSP.

1) Make sure the SOAPServlet.dll is present in the C++WSP/Apache2/modules directory.
Also check if there is a directory C++WSP/Apache2/cpp_servlet/soap/. This directory 
should have a web.xml file and an apps directory. If you don't find the soap 
directory already created or any of the above things missing then there is some problem
with the installation of C++WSP. Installing C++WSP again may be a good option!

2) Copy the application dll (e.g. trysoap.dll) to the C++WSP/Apache2/cpp_servlet/soap/apps 
directory

3) Configure the new soap application in web.xml
 Add the trysoap configuration within the <context-param> element directly 
 under the <web-app> element. Put this element (context-param) as immediate 
 child od web-app, and before the <servlet> child element. The section to add
 for our example trysoap application is given below.
 
 <context-param>
               <param-name>trysoap</param-name>
               <param-value>trysoap.dll</param-value>
 </context-param>
 
 4) Restart the Apache web server


Testing the C++ SOAP application
--------------------------------

The steps to test that the application is deployed properly is really simple.

1) Make sure apache is running after the steps under 'Deploying the C++ SOAP application'
are done.

2) Run the test client e.g. trysoapclient to test the trysoap application
  We get the following result on running trysoapclient (our trysoap client 
  sends the name to the trysoap sever. The server sends back a "Hello <name sent by client>".
  
  C:\Program Files\C++WSP\dev\src\soap\apps\try2\try2client\Debug>try2client cow

  Status - 0    Message - "Hi cow!!!"
