A class to handle XML RPC requests. More...

#include <XmlRpcServer.h>

Inheritance diagram for XmlRpc::XmlRpcServer:

Public Member Functions
	XmlRpcServer ()
	Create a server object.
virtual	~XmlRpcServer ()
	Destructor.
void	enableIntrospection (bool enabled=true)
	Specify whether introspection is enabled or not. Default is not enabled.
void	addMethod (XmlRpcServerMethod *method)
	Add a command to the RPC server.
void	removeMethod (XmlRpcServerMethod *method)
	Remove a command from the RPC server.
void	removeMethod (const std::string &methodName)
	Remove a command from the RPC server by name.
XmlRpcServerMethod *	findMethod (const std::string &name) const
	Look up a method by name.
bool	bindAndListen (int port, int backlog=5)
	Create a socket, bind to the specified port, and set it in listen mode to make it available for clients.
int	getPort (void) const
	Get the port number this server is listening on.
void	work (double msTime)
	Process client requests for the specified time.
void	exit ()
	Temporarily stop processing client requests and exit the work() method.
void	shutdown ()
	Close all connections with clients and the socket file descriptor.
void	listMethods (XmlRpcValue &result)
	Introspection support.
virtual std::string	executeRequest (std::string const &request)
	Parses the request xml, runs the method, generates the response (header+xml).
virtual unsigned	handleEvent (unsigned eventType)
	Handle client connection requests.
virtual void	removeConnection (XmlRpcServerConnection *)
	Remove a connection from the dispatcher.
Public Member Functions inherited from XmlRpc::XmlRpcSource
	XmlRpcSource (int fd=-1, bool deleteOnClose=false)
	Constructor.
virtual	~XmlRpcSource ()
	Destructor.
int	getfd () const
	Return the file descriptor being monitored.
void	setfd (int fd)
	Specify the file descriptor to monitor.
bool	getKeepOpen () const
	Return whether the file descriptor should be kept open if it is no longer monitored.
void	setKeepOpen (bool b=true)
	Specify whether the file descriptor should be kept open if it is no longer monitored.
virtual void	close ()
	Close the owned fd. If deleteOnClose was specified at construction, the object is deleted.

Protected Types
typedef std::map< std::string, XmlRpcServerMethod * >	MethodMap
	Collection of methods. This could be a set keyed on method name if we wanted...

Protected Member Functions
virtual void	acceptConnection ()
	Accept a client connection request.
virtual XmlRpcServerConnection *	createConnection (int socket)
	Create a new connection object for processing requests from a specific client.
virtual void	dispatchConnection (XmlRpcServerConnection *sc)
	Hand off a new connection object to a dispatcher.
std::string	parseRequest (std::string const &request, XmlRpcValue &params)
	Parse the methodName and parameters from the request.
bool	executeMethod (const std::string &methodName, XmlRpcValue &params, XmlRpcValue &result)
	Execute a named method with the specified params.
bool	executeMulticall (const std::string &methodName, XmlRpcValue &params, XmlRpcValue &result)
	Execute multiple calls and return the results in an array.
std::string	generateResponse (std::string const &resultXml)
	Construct a response from the result XML.
std::string	generateFaultResponse (std::string const &msg, int errorCode=-1)
	Construct a fault response.
std::string	generateHeader (std::string const &body)
	Return the appropriate headers for the response.

Protected Attributes
bool	_introspectionEnabled
	Whether the introspection API is supported by this server.
XmlRpcDispatch	_disp
	Event dispatcher.
MethodMap	_methods
	Registered RPC methods.
XmlRpcServerMethod *	_listMethods
	List all registered RPC methods (only available if introspection is enabled)
XmlRpcServerMethod *	_methodHelp
	Return help string for a specified method (only available if introspection is enabled)

Static Protected Attributes
static const char	METHODNAME_TAG [] = "<methodName>"
static const char	PARAMS_TAG [] = "<params>"
static const char	PARAMS_ETAG [] = "</params>"
static const char	PARAM_TAG [] = "<param>"
static const char	PARAM_ETAG [] = "</param>"
static const std::string	SYSTEM_MULTICALL
static const std::string	METHODNAME = "methodName"
static const std::string	PARAMS = "params"
static const std::string	FAULTCODE = "faultCode"
static const std::string	FAULTSTRING = "faultString"

Additional Inherited Members
Public Attributes inherited from XmlRpc::XmlRpcSource
bool	_ssl
SSL_CTX *	_ssl_ctx
SSL *	_ssl_ssl
SSL_METHOD *	_ssl_meth

Detailed Description

A class to handle XML RPC requests.

Definition at line 40 of file XmlRpcServer.h.

Member Typedef Documentation

typedef std::map< std::string, XmlRpcServerMethod* > XmlRpc::XmlRpcServer::MethodMap

protected

Collection of methods. This could be a set keyed on method name if we wanted...

Definition at line 154 of file XmlRpcServer.h.

Constructor & Destructor Documentation

XmlRpcServer::XmlRpcServer ( )

Create a server object.

Definition at line 34 of file XmlRpcServer.cc.

{
  _introspectionEnabled = false;
  _listMethods = 0;
  _methodHelp = 0;
}

XmlRpcServer::~XmlRpcServer ( )

virtual

Destructor.

Definition at line 42 of file XmlRpcServer.cc.

{
  this->shutdown();
  _methods.clear();
  delete _listMethods;
  delete _methodHelp;
}

Member Function Documentation

void XmlRpcServer::acceptConnection ( )

protectedvirtual

Accept a client connection request.

Definition at line 175 of file XmlRpcServer.cc.

Referenced by handleEvent().

{
  int s = XmlRpcSocket::accept(this->getfd());
  XmlRpcUtil::log(2, "XmlRpcServer::acceptConnection: socket %d", s);
  if (s < 0)
  {
    //this->close();
    XmlRpcUtil::error("XmlRpcServer::acceptConnection: Could not accept connection (%s).", XmlRpcSocket::getErrorMsg().c_str());
  }
  else if ( ! XmlRpcSocket::setNonBlocking(s))
  {
    XmlRpcSocket::close(s);
    XmlRpcUtil::error("XmlRpcServer::acceptConnection: Could not set socket to non-blocking input mode (%s).", XmlRpcSocket::getErrorMsg().c_str());
  }
  else  // Notify the dispatcher to listen for input on this source when we are in work()
  {
    XmlRpcUtil::log(2, "XmlRpcServer::acceptConnection: creating a connection");
    XmlRpcServerConnection* c = this->createConnection(s);
    if (c) this->dispatchConnection(c);
  }
}

void XmlRpcServer::addMethod ( XmlRpcServerMethod * method )

Add a command to the RPC server.

Definition at line 53 of file XmlRpcServer.cc.

Referenced by enableIntrospection(), and XmlRpc::XmlRpcServerMethod::XmlRpcServerMethod().

{
  _methods[method->getName()] = method;
}

bool XmlRpcServer::bindAndListen	(	int	port,
		int	backlog = `5`
	)

Create a socket, bind to the specified port, and set it in listen mode to make it available for clients.

Parameters

port	The port to bind and listen on (zero to choose an arbitrary port)
backlog

Definition at line 91 of file XmlRpcServer.cc.

{
  int fd = XmlRpcSocket::getSocket();
  if (fd < 0)
  {
    XmlRpcUtil::error("XmlRpcServer::bindAndListen: Could not create socket (%s).", XmlRpcSocket::getErrorMsg().c_str());
    return false;
  }
  this->setfd(fd);
  // Don't block on reads/writes
  if ( ! XmlRpcSocket::setNonBlocking(fd))
  {
    this->close();
    XmlRpcUtil::error("XmlRpcServer::bindAndListen: Could not set socket to non-blocking input mode (%s).", XmlRpcSocket::getErrorMsg().c_str());
    return false;
  }
  // Allow this port to be re-bound immediately so server re-starts are not delayed
  if ( ! XmlRpcSocket::setReuseAddr(fd))
  {
    this->close();
    XmlRpcUtil::error("XmlRpcServer::bindAndListen: Could not set SO_REUSEADDR socket option (%s).", XmlRpcSocket::getErrorMsg().c_str());
    return false;
  }
  // Bind to the specified port on the default interface
  if ( ! XmlRpcSocket::bind(fd, port))
  {
    this->close();
    XmlRpcUtil::error("XmlRpcServer::bindAndListen: Could not bind to specified port (%s).", XmlRpcSocket::getErrorMsg().c_str());
    return false;
  }
  // Set in listening mode
  if ( ! XmlRpcSocket::listen(fd, backlog))
  {
    this->close();
    XmlRpcUtil::error("XmlRpcServer::bindAndListen: Could not set socket in listening mode (%s).", XmlRpcSocket::getErrorMsg().c_str());
    return false;
  }
  XmlRpcUtil::log(2, "XmlRpcServer::bindAndListen: server listening on port %d fd %d", port, fd);
  // Notify the dispatcher to listen on this source when we are in work()
  _disp.addSource(this, XmlRpcDispatch::ReadableEvent);
  return true;
}

XmlRpcServerConnection * XmlRpcServer::createConnection ( int socket )

protectedvirtual

Create a new connection object for processing requests from a specific client.

If the client is not authorized to connect, close the socket and return 0.

Definition at line 200 of file XmlRpcServer.cc.

Referenced by acceptConnection().

{
  // Specify that the connection object be deleted when it is closed
  return new XmlRpcServerConnection(s, this, true);
}

void XmlRpcServer::dispatchConnection ( XmlRpcServerConnection * sc )

protectedvirtual

Hand off a new connection object to a dispatcher.

Definition at line 209 of file XmlRpcServer.cc.

Referenced by acceptConnection().

{
  _disp.addSource(sc, XmlRpcDispatch::ReadableEvent);
}

void XmlRpcServer::enableIntrospection ( bool enabled = true )

Specify whether introspection is enabled or not. Default is not enabled.

Definition at line 285 of file XmlRpcServer.cc.

{
  if (_introspectionEnabled == enabled)
    return;
  _introspectionEnabled = enabled;
  if (enabled)
  {
    if ( ! _listMethods)
    {
      _listMethods = new ListMethods(this);
      _methodHelp = new MethodHelp(this);
    } else {
      addMethod(_listMethods);
      addMethod(_methodHelp);
    }
  }
  else
  {
    removeMethod(LIST_METHODS);
    removeMethod(METHOD_HELP);
  }
}

bool XmlRpcServer::executeMethod	(	const std::string &	methodName,
		XmlRpcValue &	params,
		XmlRpcValue &	result
	)

protected

Execute a named method with the specified params.

Definition at line 376 of file XmlRpcServer.cc.

Referenced by executeMulticall(), and executeRequest().

{
  XmlRpcServerMethod* method = findMethod(methodName);
  if ( ! method) return false;
  method->execute(params, result);
  // Ensure a valid result value
  if ( ! result.isValid())
      result = std::string();
  return true;
}

bool XmlRpcServer::executeMulticall	(	const std::string &	methodName,
		XmlRpcValue &	params,
		XmlRpcValue &	result
	)

protected

Execute multiple calls and return the results in an array.

System.multicall implementation

Definition at line 395 of file XmlRpcServer.cc.

Referenced by executeRequest().

{
  if (methodName != MULTICALL) return false;
  // There ought to be 1 parameter, an array of structs
  if (params.size() != 1 || params[0].getType() != XmlRpcValue::TypeArray)
    throw XmlRpcException(MULTICALL + ": Invalid argument (expected an array)");
  int nc = params[0].size();
  result.setSize(nc);
  for (int i=0; i<nc; ++i) {
    if ( ! params[0][i].hasMember(METHODNAME) ||
         ! params[0][i].hasMember(PARAMS)) {
      result[i][FAULTCODE] = -1;
      result[i][FAULTSTRING] = MULTICALL +
              ": Invalid argument (expected a struct with members methodName and params)";
      continue;
    }
    const std::string& methodName = params[0][i][METHODNAME];
    XmlRpcValue& methodParams = params[0][i][PARAMS];
    XmlRpcValue resultValue;
    resultValue.setSize(1);
    try {
      if ( ! executeMethod(methodName, methodParams, resultValue[0]) &&
           ! executeMulticall(methodName, params, resultValue[0]))
      {
        result[i][FAULTCODE] = -1;
        result[i][FAULTSTRING] = methodName + ": unknown method name";
      }
      else
        result[i] = resultValue;
    } catch (const XmlRpcException& fault) {
        result[i][FAULTCODE] = fault.getCode();
        result[i][FAULTSTRING] = fault.getMessage();
    }
  }
  return true;
}

std::string XmlRpcServer::executeRequest ( std::string const & request )

virtual

Parses the request xml, runs the method, generates the response (header+xml).

Returns a fault response if an error occurs during method execution.

Definition at line 327 of file XmlRpcServer.cc.

Referenced by XmlRpc::XmlRpcServerConnection::executeRequest().

{
  XmlRpcValue params, resultValue;
  std::string methodName = parseRequest(request, params);
  XmlRpcUtil::log(2, "XmlRpcServer::executeRequest: server calling method '%s'", 
                    methodName.c_str());
  std::string response;
  try {
    if ( ! executeMethod(methodName, params, resultValue) &&
         ! executeMulticall(methodName, params, resultValue))
      response = generateFaultResponse(methodName + ": unknown method name");
    else
      response = generateResponse(resultValue.toXml());
  } catch (const XmlRpcException& fault) {
    XmlRpcUtil::log(2, "XmlRpcServer::executeRequest: fault %s.",
                    fault.getMessage().c_str()); 
    response = generateFaultResponse(fault.getMessage(), fault.getCode());
  }
  return response;
}

void XmlRpcServer::exit ( )

Temporarily stop processing client requests and exit the work() method.

Definition at line 225 of file XmlRpcServer.cc.

{
  _disp.exit();
}

XmlRpcServerMethod * XmlRpcServer::findMethod ( const std::string & name ) const

Look up a method by name.

Definition at line 79 of file XmlRpcServer.cc.

Referenced by executeMethod().

{
  MethodMap::const_iterator i = _methods.find(name);
  if (i == _methods.end())
    return 0;
  return i->second;
}

std::string XmlRpcServer::generateFaultResponse	(	std::string const &	msg,
		int	errorCode = `-1`
	)

protected

Construct a fault response.

Definition at line 482 of file XmlRpcServer.cc.

Referenced by executeRequest().

{
  const char RESPONSE_1[] = 
    "<?xml version=\"1.0\"?>\r\n"
    "<methodResponse><fault>\r\n\t";
  const char RESPONSE_2[] =
    "\r\n</fault></methodResponse>\r\n";
  XmlRpcValue faultStruct;
  faultStruct[FAULTCODE] = errorCode;
  faultStruct[FAULTSTRING] = errorMsg;
  std::string body = RESPONSE_1 + faultStruct.toXml() + RESPONSE_2;
  std::string header = generateHeader(body);
  return header + body;
}

std::string XmlRpcServer::generateHeader ( std::string const & body )

protected

Return the appropriate headers for the response.

Definition at line 464 of file XmlRpcServer.cc.

Referenced by generateFaultResponse(), and generateResponse().

{
  std::string header = 
    "HTTP/1.1 200 OK\r\n"
    "Server: ";
  header += XMLRPC_VERSION;
  header += "\r\n"
    "Content-Type: text/xml\r\n"
    "Content-length: ";
  char buffLen[40];
  sprintf(buffLen,"%zu\r\n\r\n", body.size());
  return header + buffLen;
}

std::string XmlRpcServer::generateResponse ( std::string const & resultXml )

protected

Construct a response from the result XML.

Definition at line 445 of file XmlRpcServer.cc.

Referenced by executeRequest().

{
  const char RESPONSE_1[] = 
    "<?xml version=\"1.0\"?>\r\n"
    "<methodResponse><params><param>\r\n\t";
  const char RESPONSE_2[] =
    "\r\n</param></params></methodResponse>\r\n";
  std::string body = RESPONSE_1 + resultXml + RESPONSE_2;
  std::string header = generateHeader(body);
  std::string response = header + body;
  XmlRpcUtil::log(5, "XmlRpcServer::generateResponse:\n%s\n", response.c_str());
  return response;
}

int XmlRpcServer::getPort ( void ) const

Get the port number this server is listening on.

Definition at line 145 of file XmlRpcServer.cc.

{
  return XmlRpcSocket::getPort(getfd());
}

unsigned XmlRpcServer::handleEvent ( unsigned eventType )

virtual

Handle client connection requests.

Implements XmlRpc::XmlRpcSource.

Definition at line 165 of file XmlRpcServer.cc.

{
  acceptConnection();
  return XmlRpcDispatch::ReadableEvent;         // Continue to monitor this fd
}

void XmlRpcServer::listMethods ( XmlRpcValue & result )

Introspection support.

Definition at line 312 of file XmlRpcServer.cc.

{
  int i = 0;
  result.setSize(_methods.size()+1);
  for (MethodMap::iterator it=_methods.begin(); it != _methods.end(); ++it)
    result[i++] = it->first;
  // Multicall support is built into XmlRpcServer::executeRequest
  result[i] = MULTICALL;
}

std::string XmlRpcServer::parseRequest	(	std::string const &	request,
		XmlRpcValue &	params
	)

protected

Parse the methodName and parameters from the request.

Returns: the methodName

Definition at line 354 of file XmlRpcServer.cc.

Referenced by executeRequest().

{
  int offset = 0;   // Number of chars parsed from the request
  std::string methodName = XmlRpcUtil::parseTag(METHODNAME_TAG, request, &offset);
  if (methodName.size() > 0 && XmlRpcUtil::findTag(PARAMS_TAG, request, &offset))
  {
    int nArgs = 0;
    while (XmlRpcUtil::nextTagIs(PARAM_TAG, request, &offset)) {
      params[nArgs++] = XmlRpcValue(request, &offset);
      (void) XmlRpcUtil::nextTagIs(PARAM_ETAG, request, &offset);
    }
    (void) XmlRpcUtil::nextTagIs(PARAMS_ETAG, request, &offset);
  }
  return methodName;
}

void XmlRpcServer::removeConnection ( XmlRpcServerConnection * sc )

virtual

Remove a connection from the dispatcher.

Definition at line 217 of file XmlRpcServer.cc.

Referenced by XmlRpc::XmlRpcServerConnection::~XmlRpcServerConnection().

{
  _disp.removeSource(sc);
}

void XmlRpcServer::removeMethod ( XmlRpcServerMethod * method )

Remove a command from the RPC server.

Definition at line 60 of file XmlRpcServer.cc.

Referenced by enableIntrospection(), and XmlRpc::XmlRpcServerMethod::~XmlRpcServerMethod().

{
  MethodMap::iterator i = _methods.find(method->getName());
  if (i != _methods.end())
    _methods.erase(i);
}

void XmlRpcServer::removeMethod ( const std::string & methodName )

Remove a command from the RPC server by name.

Definition at line 69 of file XmlRpcServer.cc.

{
  MethodMap::iterator i = _methods.find(methodName);
  if (i != _methods.end())
    _methods.erase(i);
}

void XmlRpcServer::shutdown ( )

Close all connections with clients and the socket file descriptor.

Definition at line 233 of file XmlRpcServer.cc.

Referenced by ~XmlRpcServer().

{
  // This closes and destroys all connections as well as closing this socket
  _disp.clear();
}

void XmlRpcServer::work ( double msTime )

Process client requests for the specified time.

Definition at line 154 of file XmlRpcServer.cc.

{
  XmlRpcUtil::log(2, "XmlRpcServer::work: waiting for a connection");
  _disp.work(msTime);
}

Member Data Documentation

XmlRpcDispatch XmlRpc::XmlRpcServer::_disp

protected

Event dispatcher.

Definition at line 151 of file XmlRpcServer.h.

Referenced by bindAndListen(), dispatchConnection(), exit(), removeConnection(), shutdown(), and work().

bool XmlRpc::XmlRpcServer::_introspectionEnabled

protected

Whether the introspection API is supported by this server.

Definition at line 148 of file XmlRpcServer.h.

Referenced by enableIntrospection(), and XmlRpcServer().

XmlRpcServerMethod* XmlRpc::XmlRpcServer::_listMethods

protected

List all registered RPC methods (only available if introspection is enabled)

Definition at line 160 of file XmlRpcServer.h.

Referenced by enableIntrospection(), XmlRpcServer(), and ~XmlRpcServer().

XmlRpcServerMethod* XmlRpc::XmlRpcServer::_methodHelp

protected

Return help string for a specified method (only available if introspection is enabled)

Definition at line 163 of file XmlRpcServer.h.

Referenced by enableIntrospection(), XmlRpcServer(), and ~XmlRpcServer().

MethodMap XmlRpc::XmlRpcServer::_methods

protected

Registered RPC methods.

Definition at line 157 of file XmlRpcServer.h.

Referenced by addMethod(), findMethod(), listMethods(), removeMethod(), and ~XmlRpcServer().

const std::string XmlRpcServer::FAULTCODE = "faultCode"

staticprotected

Definition at line 110 of file XmlRpcServer.h.

Referenced by executeMulticall(), and generateFaultResponse().

const std::string XmlRpcServer::FAULTSTRING = "faultString"

staticprotected

Definition at line 111 of file XmlRpcServer.h.

Referenced by executeMulticall(), and generateFaultResponse().

const std::string XmlRpcServer::METHODNAME = "methodName"

staticprotected

Definition at line 107 of file XmlRpcServer.h.

Referenced by executeMulticall().

const char XmlRpcServer::METHODNAME_TAG = "<methodName>"

staticprotected

Definition at line 100 of file XmlRpcServer.h.

Referenced by parseRequest().

const char XmlRpcServer::PARAM_ETAG = "</param>"

staticprotected

Definition at line 104 of file XmlRpcServer.h.

Referenced by parseRequest().

const char XmlRpcServer::PARAM_TAG = "<param>"

staticprotected

Definition at line 103 of file XmlRpcServer.h.

Referenced by parseRequest().

const std::string XmlRpcServer::PARAMS = "params"

staticprotected

Definition at line 108 of file XmlRpcServer.h.

Referenced by executeMulticall().

const char XmlRpcServer::PARAMS_ETAG = "</params>"

staticprotected

Definition at line 102 of file XmlRpcServer.h.

Referenced by parseRequest().

const char XmlRpcServer::PARAMS_TAG = "<params>"

staticprotected

Definition at line 101 of file XmlRpcServer.h.

Referenced by parseRequest().

const std::string XmlRpc::XmlRpcServer::SYSTEM_MULTICALL

staticprotected

Definition at line 106 of file XmlRpcServer.h.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation