Link to Home page Main Banner


WebServices

LocalLinks

  

Embedded SOAP Toolkit - eSoap

The Embedded SOAP Toolkit - eSoap, is a SOAP framework target to embedded systems that need to expose interfaces as WEB Services.

The eSoap kit is a C++ library that provides a compact, fast and very portable SOAP engine that can be used on your embedded system.

The eSoap implementation is based upon the SOAP 1.1.

eSoap is totally written in ANSI C++ and it is very portable. It has been designed to use STL whenever it is available. Also, it has its own container library for systems where STL is not available. Exception handling and RTTI have been avoided because these features are usually not available on some embedded platforms.

eSoap Architecture

eSoap has been design as a class library to be used on C++ applications that need to expose their interfaces as Web Services. The figure below shows the strict separation of application code and the eSoap libraries. This separation is intentional, and the goal is to decouple the application code as much as possible from the SOAP framework.

eSoap Diagram
Fig 1. - eSoap Components.

The eSoap class framework is designed as tree basic components:

  • Core Library -- a set of classes that provides basic elemements used on the development of both, server and client applications.
  • Client Library -- a set of classes used to reach other Web Services applications, including the ones written with the eSoap toolkit. These classes could be used on a service application that requires to reach other Web Service.
  • Server Library -- a set of classes used on the development of Web Services. It provides a framework to build server side code.

Core Library

The core classes are the heart of the eSoap kit. They provide classes for composition of SOAP messages , and mechanisms to iterate through them.

The main classes are:

  • esoap::Envelope
  • esoap::Parameter
  • esoap::Method
  • esoap::Header
  • esoap::Fault

The class esoap::Envelope is the center of all things. As its name suggest, it is the place where the SOAP requests and responses are composed. It provides interface to access diferent elements of a SOAP message. For a complete description of the core classes, see the the class hierarchy documentation:

add link here:

The esoap::Parameter class is a very basic element used as parameters of the calls and responses. It is sub-classed in some cases such as esoap::Array, esoap::DateTime and esoap::Base64.

Client Library

The main class of the client interface is esoap::Transport. It is a base class that provides the interface to send/receive SOAP messages to/from a particular Web Service. At this point there is support for HTTP protocol.

Server Library

The main class of the server interface is esoap::Server. It is a base class that provides the interface to an application to listen for SOAP messages. A full callback mechanism is provided to isolate the eSoap toolkit code, from the application specific code. This framework allows you to plug-in the HTTP engine for your application.

The server framework is based on the concept of callback. See this link for more information about callbacks:
C++ Callback framework

eSoap Classes Reference

The classes of the eSoap toolkit are documented using this wonderful tool called DoxyGen ( add link here ).

Examples

Client Example -- Adding two integers

This section shows a client sample program that call a method called "add" with parameters "a" and "b" as integers. This call returns the sum of both numbers as an integer.

// Includes for clients
#include "soap_envelope.h"
#include "soap_transport.h"


// server location
#define ESOAP_SERVER_URL    "http://localhost:8080/rpcrouter"


int main(int, char ** )
{
  // envelope to hold the SOAP request...
  esoap::Envelope    env;

  // set method name and parameters...
  esoap::Method *m = env.setMethod( "add" );
  m->addInteger( "a", 100 );
  m->addInteger( "b", 20 );

  // Create a HTTP transport instance to take care of
  // the messages being sent/received. 
  esoap::Transport *ht;
  ht = esoap::TransportFactory::create( ESOAP_SERVER_URL,
                                        esoap::TransportFactory::HTTP );
  
  esoap::Envelope *in = 0;   // receives SOAP response

  // make call to a SOAP server
  bool rc = ht->call( env, 0, &in );
  if( rc )
  {
    if( in->success() )
    {
      // return value is always first parameter...
      esoap::Parameter *sum  = in->getMethod()->getParameter( 0 );
      printf( "Sucess: SUM is: %d\n", sum->getInteger() );
    }
    else
    {
      // Something went wrong... show Fault element info...
      if( in->isFault() )
      {
         esoap::Fault *f = in->getFault();
         printf( "Fault Received: Faultcode: %s\nFaultstring:%s\n",
                  f->getCodeString().c_str(), f->getFaultString().c_str() );
      }
    }
    delete in;
  }
  else
  {
    printf( "ERROR: could not contact server...\n" );
  }
  
  delete ht;
}

Server Example -- Adding two integers


// server includes 
#include "soap_server.h"
#include "soap_envelope.h"


// Default Port Number and Config file
#define ESOAP_PORT  8080
#define ESOAP_CONF  "esoapserver.conf"


/**
 * The SOAP server framework call this method 
 * to add two parameters.
 */
int methodAdd( esoap::MethodDataBlock *mdata )
{
  esoap::Parameter *pa; 
  esoap::Parameter *pb;

  // let's access the parameters...
  esoap::Method *m = mdata->in()->getMethod();
  pa = m->getParameter( "a" );
  pb = m->getParameter( "b" );

  if( pa && pb )
  {
    esoap::String respName = "returnResponse";
    esoap::Method *resp = mdata->out()->setMethod( respName.c_str(), 
                                                  m->getURI().c_str() );
    int res = pa->getInteger() + pb->getInteger();
    resp->addInteger( "sum", res );
  }
  else
  {
    printf( "ERROR: parameter not found\n" );
    esoap::Fault *resp = mdata->out()->setFault( esoap::Fault::Server, 
                                               "Server Error" );
    resp->addToDetail( new esoap::Parameter( "message", "Parameters not found" ) );
  }

  return 0;   // yes we have a reponse ( 1 -- oneway call )
}


int main(int, char ** )
{
  // Create server instance..
  esoap::ServerFactory::create( esoap::ServerFactory::ABYSS );

  // Init server...
  esoap::Server::instance()->init( "SOAPServer", ESOAP_PORT, ESOAP_CONF );

  // register method "add" with the callback above.
  esoap::Server::instance()->getRegistry().addMethod( "add", 
            new FunctionCallback< esoap::MethodDataBlock >( methodAdd ) );

  // run the server...
  esoap::Server::instance()->run();
  return 0;
}

Windows & Linux

eSoap is not target at these OS. There are already too many SOAP implementations for them :-).

In order to make installation very easy, eSoap has been packaged for Windows and Linux as a single library.

  • Windows -- DLL called esoapmsvc.dll
  • Linux -- static library called esoap.a

Feedback

If you have any comment or want to help with this porting, please send me one e-mail: mailto:rdasilva@connecttel.com

Visitors:



Last modified Feb 17, 2001
Copyright ©2001 Rosimildo da Silva. All rights reserved.


   e-mail me