ulxr::Protocol Class Reference
[A transportation protocol for an XML-RPC call]

Base class for the protocol of the rpc transportation. More...

#include <ulxr_protocol.h>

Inheritance diagram for ulxr::Protocol:

[legend]Collaboration diagram for ulxr::Protocol:


Public Types
enum	State { ConnStart, ConnPendingCR, ConnPendingHeaderLine, ConnHeaderLine, ConnSwitchToBody, ConnBody, ConnError, ConnLast }
	General connection states while reading input stream. More...
Public Member Functions
	Protocol (Connection *conn)
	Constructs a Protocol.
virtual	~Protocol ()
	Destroys the Protocol.
void	writeRaw (char const *buff, long len)
	Writes data to the connection.
long	readRaw (char *buff, long len)
	Reads data from the connection.
virtual void	open ()
	Opens the connection in rpc client mode.
bool	accept (int timeout=0)
	Opens the connection in rpc server mode, thus waiting for connections from clients.
bool	isOpen () const
	Tests if the connection is open.
virtual void	shutdown (int mode)=0
	Shuts down the socket.
virtual void	close ()
	Closes the connection.
virtual bool	hasBytesToRead () const=0
	Tests if there are bytes left in the message body.
virtual void	resetConnection ()
	Resets the state of the Protocol.
virtual void	sendRpcCall (const MethodCall &call, const CppString &resource, bool wbxml_mode)
	Sends a MethodCall over the connection.
virtual void	sendRpcResponse (const MethodResponse &resp, bool wbxml_mode)
	Sends a MethodResponse over the connection.
void	setPersistent (bool pers)
	Sets the connections persistence.
bool	isPersistent () const
	Gets the persistence information.
virtual bool	responseStatus (CppString &phrase) const=0
	Tests if the response was successful regarding the transportation.
virtual State	connectionMachine (char *&buffer, long &len)
	Process a chunk of input data from the connection.
void	addAuthentication (const CppString &user, const CppString &pass, const CppString &realm)
	Adds another potential username, password and "range" for this connection (server mode).
virtual void	setMessageAuthentication (const CppString &user, const CppString &pass)
	Sets username and password for the next transmission (client mode).
virtual bool	checkAuthentication (const CppString &realm) const
	Checks for a valid user in the current message.
virtual void	rejectAuthentication (const CppString &realm)
	Sends a negative response to the caller.
virtual void	setTransmitOnly ()
	Sets the current transmission to expect/accept no return value.
virtual bool	isTransmitOnly ()
	Tests if the current transmission expects a return value.
Connection *	getConnection () const
	Returns the connection object.
virtual Protocol *	detach ()=0
	Detaches the protocol by creating a duplicate of the protocol + connection and closing the original connection afterwards.
Protected Member Functions
void	setConnection (Connection *conn)
	Sets the connection object.
void	setConnectionState (State state)
	Sets the connection state.
State	getConnectionState () const
	Gets the connection state.
void	setRemainingContentLength (long len)
	Sets the length of the remaining content.
long	getRemainingContentLength () const
	Gets the length of the remaining content.
long	getContentLength () const
	Gets the length of the content.
void	setContentLength (long len)
	Sets the length of the content.
virtual bool	getUserPass (CppString &user, CppString &pass) const
	Extracts username and password from current message.
virtual void	determineContentLength ()=0
	Determines the length of the message body.
virtual CppString	getProtocolName ()=0
	Returns the protocol name.
	Protocol (const Protocol &)
Private Member Functions
void	init ()
	Initializes internal variables.
Protocol &	operator= (const Protocol &)
Private Attributes
PImpl *	pimpl
Classes
struct	AuthData
struct	PImpl

Detailed Description

Base class for the protocol of the rpc transportation.

Definition at line 52 of file ulxr_protocol.h.

Member Enumeration Documentation

enum ulxr::Protocol::State

General connection states while reading input stream.

Enumerator:

ConnStart
ConnPendingCR
ConnPendingHeaderLine
ConnHeaderLine
ConnSwitchToBody
ConnBody
ConnError
ConnLast

Definition at line 158 of file ulxr_protocol.h.

Constructor & Destructor Documentation

ulxr::Protocol::Protocol ( Connection * conn )

Constructs a Protocol.

Parameters:

conn

pointer to connection object

Definition at line 81 of file ulxr_protocol.cpp.

References ulxr::Protocol::PImpl::connection, ulxr::Protocol::PImpl::delete_connection, init(), pimpl, ULXR_PCHAR, and ULXR_TRACE.

ulxr::Protocol::~Protocol ( ) [virtual]

Destroys the Protocol.

Definition at line 91 of file ulxr_protocol.cpp.

References ulxr::Protocol::PImpl::connection, ulxr::Protocol::PImpl::delete_connection, pimpl, ULXR_PCHAR, and ULXR_TRACE.

ulxr::Protocol::Protocol ( const Protocol & ) [protected]

Definition at line 74 of file ulxr_protocol.cpp.

References pimpl.

Member Function Documentation

void ulxr::Protocol::writeRaw	(	char const *	buff,
		long	len
	)

Writes data to the connection.

Parameters:

	buff	pointer to data
	len	valid buffer length

Definition at line 110 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

long ulxr::Protocol::readRaw	(	char *	buff,
		long	len
	)

Reads data from the connection.

Parameters:

	buff	pointer to data buffer
	len	maimum number of bytes to read into buffer

Returns:: number of actually read bytes

Definition at line 117 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::Protocol::open ( ) [virtual]

Opens the connection in rpc client mode.

Definition at line 136 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::Requester::send_call().

bool ulxr::Protocol::accept ( int timeout = 0 )

Opens the connection in rpc server mode, thus waiting for connections from clients.

Parameters:

timeout

the timeout value [sec] (0 - no timeout)

Returns:: true when connection has been accepted

Definition at line 153 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

bool ulxr::Protocol::isOpen ( ) const

Tests if the connection is open.

Returns:: true if connection is already open.

Definition at line 144 of file ulxr_protocol.cpp.

References ulxr::Connection::isOpen(), ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::Requester::send_call().

virtual void ulxr::Protocol::shutdown ( int mode ) [pure virtual]

Shuts down the socket.

Only meaningful for certain connections based on TcpIpConnection.

Parameters:

mode

shutdown mode

Unix: SHUT_RD, SHUT_WR or SHUT_RDWR
Win32: SD_RECEIVE, SD_SEND or SD_BOTH

Implemented in ulxr::HttpProtocol.

void ulxr::Protocol::close ( ) [virtual]

Closes the connection.

Reimplemented in ulxr::HttpProtocol.

Definition at line 162 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::HttpProtocol::close(), and funtik::MultiProcessRpcServer::doChild().

virtual bool ulxr::Protocol::hasBytesToRead ( ) const [pure virtual]

Tests if there are bytes left in the message body.

Returns:: true: there is at least one byte available

Implemented in ulxr::HttpProtocol.

void ulxr::Protocol::resetConnection ( ) [virtual]

Resets the state of the Protocol.

Before starting a transfer you should call this to ensure a defined state of the internal state machine processing the protocol.

Reimplemented in ulxr::HttpProtocol.

Definition at line 346 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::HttpProtocol::resetConnection(), and ulxr::Requester::send_call().

void ulxr::Protocol::sendRpcCall	(	const MethodCall &	call,
		const CppString &	resource,
		bool	wbxml_mode
	)			`[virtual]`

Sends a MethodCall over the connection.

Parameters:

	call	pointer to the calling data
	resource	resource for rpc on remote host
	wbxml_mode	true: data is sent as wbxml

Reimplemented in ulxr::HttpProtocol.

Definition at line 254 of file ulxr_protocol.cpp.

References ULXR_PCHAR, ULXR_TRACE, and ulxr::unicodeToUtf8().

Referenced by ulxr::Requester::send_call().

void ulxr::Protocol::sendRpcResponse	(	const MethodResponse &	resp,
		bool	wbxml_mode
	)			`[virtual]`

Sends a MethodResponse over the connection.

Parameters:

	resp	pointer to the response data
	wbxml_mode	true: data is sent as wbxml

Reimplemented in ulxr::HttpProtocol.

Definition at line 232 of file ulxr_protocol.cpp.

References ULXR_PCHAR, ULXR_TRACE, and ulxr::unicodeToUtf8().

Referenced by funtik::MultiProcessRpcServer::doChild().

void ulxr::Protocol::setPersistent ( bool pers )

Sets the connections persistence.

Usually an xml rpc call closes after the response has been received. To improve performance or to transfer other protocls you may set the connection to remain open. It is closed at the latest when an error occurs.

Note:: If you are using TCP/IP connections with TcpIpConnection you might want to call TcpIpConnection::setTcpNoDelay() to enforce sending packets immediately. Otherwise the transmission of the rather small xmlrpc packets may be significantly delayed by the socket buffer mechanism.

Parameters:

pers

true if connection shall be persistent.

Definition at line 356 of file ulxr_protocol.cpp.

References ulxr::Connection::getDefaultTimeout(), ulxr::Connection::getPersistentTimeout(), ulxr::Connection::setTimeout(), ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::HttpProtocol::machine_switchToBody(), and ulxr::Requester::send_call().

bool ulxr::Protocol::isPersistent ( ) const

Gets the persistence information.

Returns:: true if connection is persistent

Definition at line 369 of file ulxr_protocol.cpp.

Referenced by funtik::MultiProcessRpcServer::doChild().

virtual bool ulxr::Protocol::responseStatus ( CppString & phrase ) const [pure virtual]

Tests if the response was successful regarding the transportation.

Parameters:

phrase

return value describing the problem.

Returns:: true response is OK.

Implemented in ulxr::HttpProtocol.

Protocol::State ulxr::Protocol::connectionMachine	(	char *&	buffer,
		long &	len
	)			`[virtual]`

Process a chunk of input data from the connection.

Usually you call read() to get some more data and pass it to this method. It processes the header (depending on your protocol). Normally you only have to take care of two states: ConnError which results in terminating the connection. ConnBody on the other side indicates user data which might be fed to a parser.

See also:: Dispatcher.

Parameters:

	buffer	pointer to input data
	len	valid length of buffer

Returns:: current state of the processing. This return state may differ from the state returned by getConnectionState() due to internal processing. You should ignore everything except ConnBody and ConnError.

Reimplemented in ulxr::HttpProtocol.

Definition at line 224 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::Protocol::addAuthentication	(	const CppString &	user,
		const CppString &	pass,
		const CppString &	realm
	)

Adds another potential username, password and "range" for this connection (server mode).

Parameters:

	user	Username
	pass	Password
	realm	Synonym for area which shall be accessed

Definition at line 278 of file ulxr_protocol.cpp.

References ulxr::stripWS(), ULXR_PCHAR, and ULXR_TRACE.

void ulxr::Protocol::setMessageAuthentication	(	const CppString &	user,
		const CppString &	pass
	)			`[virtual]`

Sets username and password for the next transmission (client mode).

This makes the next transmission block use a simple authentication scheme with a username and password.

Parameters:

	user	Username
	pass	Password

Reimplemented in ulxr::HttpProtocol.

Definition at line 326 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

bool ulxr::Protocol::checkAuthentication ( const CppString & realm ) const [virtual]

Checks for a valid user in the current message.

There must be an appropriate AuthData set and the connection must support username + password transmission (default is NOT to do so). The caller is resonsible for sending a negative response if approriate.

Parameters:

realm

Synonym for area which shall be accessed

Returns:: true: access shall be granted.

Definition at line 287 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::Protocol::rejectAuthentication ( const CppString & realm ) [virtual]

Sends a negative response to the caller.

Parameters:

realm

Description for the caller which username and password to pass in request

Returns:: true: access shall be granted.

Reimplemented in ulxr::HttpProtocol.

Definition at line 320 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::Protocol::setTransmitOnly ( ) [virtual]

Sets the current transmission to expect/accept no return value.

Reimplemented in ulxr::HttpProtocol.

Definition at line 333 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

bool ulxr::Protocol::isTransmitOnly ( ) [virtual]

Tests if the current transmission expects a return value.

Returns:: true: return value for request

Reimplemented in ulxr::HttpProtocol.

Definition at line 339 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by funtik::MultiProcessRpcServer::doChild().

Connection * ulxr::Protocol::getConnection ( ) const

Returns the connection object.

Returns:: pointer to connection object

Definition at line 171 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::Requester::startDispatch().

virtual Protocol* ulxr::Protocol::detach ( ) [pure virtual]

Detaches the protocol by creating a duplicate of the protocol + connection and closing the original connection afterwards.

Returns:: the current protocol

Implemented in ulxr::HttpProtocol.

Referenced by ulxr::MultiThreadRpcServer::MultiThreadRpcServer(), and ulxr::Requester::startDispatch().

void ulxr::Protocol::setConnection ( Connection * conn ) [protected]

Sets the connection object.

The connection is then owned by the Protocol

Parameters:

conn

pointer to connection object

Definition at line 178 of file ulxr_protocol.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by ulxr::HttpProtocol::detach().

void ulxr::Protocol::setConnectionState ( State state ) [protected]

Sets the connection state.

Parameters:

state

new connection state

Definition at line 193 of file ulxr_protocol.cpp.

Referenced by ulxr::HttpProtocol::machine_switchToBody().

Protocol::State ulxr::Protocol::getConnectionState ( ) const [protected]

Gets the connection state.

Returns:: current connection state

Definition at line 187 of file ulxr_protocol.cpp.

void ulxr::Protocol::setRemainingContentLength ( long len ) [protected]

Sets the length of the remaining content.

See also:: getRemainingContentLength().

Parameters:

len

number of bytes of content to come

Definition at line 199 of file ulxr_protocol.cpp.

Referenced by ulxr::HttpProtocol::machine_switchToBody().

long ulxr::Protocol::getRemainingContentLength ( ) const [protected]

Gets the length of the remaining content.

Depending on the type of connection the results from here are more or less accurate and up to date. Chunked encoding for http has not neccessarily an overall content length. This implementation returns the length of the current chunk.