Interface for an Urbi wrapper object. More...

#include <uabstractclient.hh>

Inheritance diagram for urbi::UAbstractClient:

Collaboration diagram for urbi::UAbstractClient:

Public Types
enum	{ URBI_BUFLEN = 128000 }
	Connection Buffer size. More...
enum	{ URBI_PORT = 54000 }
	Standard port of Urbi server. More...
typedef int	error_type
	Error code.
Public Member Functions
	UAbstractClient (const std::string &host=default_host(), unsigned port=URBI_PORT, size_t buflen=URBI_BUFLEN, bool server=false)
	Create a new instance and connect to the Urbi server.
virtual	~UAbstractClient ()
bool	init () const
error_type	error () const
	Return current error status, or zero if no error occurred.
error_type	send (const char *format,...)
	Send an Urbi command.
error_type	send (const std::string &s)
	A C++ string.
error_type	send (const urbi::UValue &v)
	Send the value without any prefix or terminator.
error_type	send (std::istream &is)
	Send the remainder of the stream.
error_type	sendBinary (const void *data, size_t len, const std::string &header)
	Send an urbi Binary value.
error_type	sendBin (const void *, size_t len)
	Send binary data.
error_type	sendBin (const void , size_t len, const char header,...)
	Send an Urbi header followed by binary data.
error_type	startPack ()
	Lock the send buffer (for backward compatibility, will be removed in future versions).
error_type	endPack ()
	Unlock the send buffer (for backward compatibility, will be removed in future versions).
error_type	pack (const char *format,...)
	Append Urbi commands to the send buffer (for backward compatibility, will be removed in future versions).
error_type	vpack (const char *format, va_list args)
	va_list version of pack.
error_type	sendFile (const std::string &f)
	Send urbi commands contained in a file.
UCallbackID	sendCommand (UCallback, const char *,...)
	Send a command, prefixing it with a tag, and associate the given callback with this tag.
UCallbackID	sendCommand (UCustomCallback, void , const char ,...)
	Send a command, prefixing it with a tag, and associate the given callback with this tag.
error_type	sendSound (const char device, const urbi::USound &sound, const char tag=0)
	Send sound data to the robot for immediate playback.
error_type	putFile (const char localName, const char remoteName=0)
	Put a file on the robot's mass storage device.
error_type	putFile (const void buffer, size_t length, const char remoteName)
	Save a buffer to a file on the robot.
int	getAssociatedTag (UCallbackID id, char *tag)
	Get the tag associated with a registered callback.
int	deleteCallback (UCallbackID id)
	Delete a callback.
std::string	fresh ()
	Return a identifier, for tags for instance.
ATTRIBUTE_DEPRECATED void	makeUniqueTag (char *tag)
	Fill tag with a unique tag for this client.
virtual void	notifyCallbacks (const UMessage &msg)
	Pass the given UMessage to all registered callbacks with the corresponding tag, as if it were comming from the Urbi server.
virtual void	printf (const char *format,...)=0
	Notify of an error.
virtual unsigned int	getCurrentTime () const =0
	Get time in milliseconds since an unspecified but constant reference time.
virtual void	setKeepAliveCheck (unsigned pingInterval, unsigned pongTimeout)=0
	Active KeepAlive functionality Sends an Urbi message at specified interval, if no anwser is received close the connection and notify 'URBI_ERROR_CONNECTION_TIMEOUT'.
const std::string &	getServerName () const
	Return the server name or IP address.
unsigned	getServerPort () const
	Return the server port.
void	processRecvBuffer ()
	Called each time new data is available in recvBuffer.
std::ostream &	stream_get ()
	This, as a stream.
const std::string &	connectionID () const
int	getCurrentTimestamp () const

UCallbackID	setCallback (UCallbackWrapper &callback, const char *tag)
	Associate a callback function with a tag. New style.
UCallbackID	setErrorCallback (UCallbackWrapper &callback)
	Associate a callback function with all error messages from the server.
UCallbackID	setWildcardCallback (UCallbackWrapper &callback)
	Associate a callback with all messages.
UCallbackID	setClientErrorCallback (UCallbackWrapper &callback)
	Associate a callback with local connection errors.
UCallbackID	setCallback (UCallback, const char *tag)
	OLD-style callbacks.
UCallbackID	setCallback (UCustomCallback, void callbackData, const char tag)
	Associate a callback function with a tag, specifiing a callback custom value that will be passed back to the callback function.

template<class C >
UCallbackID	setCallback (C &ref, UCallbackAction(C::)(const UMessage &), const char tag)
template<class C , class P1 >
UCallbackID	setCallback (C &ref, UCallbackAction(C::)(P1, const UMessage &), P1, const char tag)
template<class C , class P1 , class P2 >
UCallbackID	setCallback (C &ref, UCallbackAction(C::)(P1, P2, const UMessage &), P1, P2, const char tag)
template<class C , class P1 , class P2 , class P3 >
UCallbackID	setCallback (C &ref, UCallbackAction(C::)(P1, P2, P3, const UMessage &), P1, P2, P3, const char tag)
template<class C , class P1 , class P2 , class P3 , class P4 >
UCallbackID	setCallback (C &ref, UCallbackAction(C::)(P1, P2, P3, P4, const UMessage &), P1, P2, P3, P4, const char tag)
Static Public Member Functions
static const char *	default_host ()
	Default host.
Static Public Attributes
static const char *	CLIENTERROR_TAG = "client_error"
	dummy tag for client error callback.
Protected Member Functions
void	onConnection ()
	Lock on send buffer.
virtual error_type	onClose ()
	Executed when closing connection.
virtual error_type	effectiveSend (const void *buffer, size_t size)=0
	Queue data for sending, returns zero on success, nonzero on failure.
error_type	effective_send (const void *buffer, size_t size)
	Direct forward the call to effectiveSend.
error_type	effective_send (const char *buffer)
	Bounce to effective_send() using strlen.
error_type	effective_send (const std::string &buffer)
	Bounce to effective_send() using c_str().
UCallbackID	addCallback (const char *tag, UCallbackWrapper &w)
	Add a callback to the list.
void	clientError (std::string msg, int code=0)
	Generate a client error message and notify callbacks.
void	clientError (const char *msg=0, int code=0)
virtual UCallbackAction	setConnectionID (const UMessage &msg)
	A callback, installed by setVersion, that computes connectionID_.
Protected Attributes
bool	closed_
libport::Lockable	listLock
std::string	host_
	Host name.
unsigned	port_
	Urbi Port.
bool	server_
	Server mode.
size_t	sendBufSize
	Buffer sizes.
size_t	recvBufSize
error_type	rc
	System calls return value storage.
char *	recvBuffer
	Reception buffer.
size_t	recvBufferPosition
	Current position in reception buffer.
char *	sendBuffer
	Temporary buffer for send data.
std::string	connectionID_
bool	init_
	Client fully created.
Private Types
typedef std::list< UCallbackInfo >	callbacks_type
Private Member Functions
bool	process_recv_buffer_binary_ ()
	New binary data is available.
bool	process_recv_buffer_text_ ()
	New text data is available.
void	bins_clear ()
	Empty bins.
Private Attributes
binaries_type	bins
	Bin object for this command.
void *	binaryBuffer
	Temporary storage of binary data.
size_t	binaryBufferPosition
	Current position in binaryBuffer.
size_t	binaryBufferLength
	Size of binaryBuffer.
size_t	parsePosition
	Position of parse in recvBuffer.
bool	inString
	True if preparsing is in a string.
size_t	nBracket
	Current depth of bracket.
char *	currentCommand
	Start of command, after [ts:tag] header.
bool	binaryMode
	Currently parsing binary.
bool	system
	Parsing a system message.
size_t	endOfHeaderPosition
	Position of end of header.
char	currentTag [URBI_MAX_TAG_LENGTH]
int	currentTimestamp
callbacks_type	callbacks_
unsigned int	counter_
	A counter, used to generate unique (tag) identifiers.
std::ostream *	stream_
	Ourself as a stream.
Friends
class	UClientStreambuf
Kernel Version.
std::string	kernelVersion_
	The full kernel version as answered by the server.
int	kernelMajor_
	The major version. -1 if not yet available.
int	kernelMinor_
	The minor version. -1 if not yet available.
const std::string &	kernelVersion () const
	Kernel version string.
int	kernelMajor () const
	Major kernel version. Dies if unknown yet.
int	kernelMinor () const
	Minor kernel version. Dies if unknown yet.
virtual void	waitForKernelVersion () const =0
	Block until kernel version is available or an error occurrs.
virtual UCallbackAction	setVersion (const UMessage &msg)
	A callback, installed by onConnection(), that reads an answer from the server to know if it's k1 or k2.

Detailed Description

Interface for an Urbi wrapper object.

Implementations of this interface are wrappers around the Urbi protocol. It handles Urbi messages parsing, callback registration and various formatting functions. Implementations of this interface should:

Redefine errorNotify() as a function able to notify the user of eventual errors.
Redfine the four mutual exclusion functions.
Redefine effectiveSend().
Fill recvBuffer, update recvBufferPosition and call processRecvBuffer() when new data is available.
Provide an execute() function in the namespace urbi, that never returns, and that will be called after initialization.
Call onConnection when the connection is established.

See the liburbi-cpp documentation for more informations on how to use this class.

Definition at line 120 of file uabstractclient.hh.

Member Typedef Documentation

typedef std::list<UCallbackInfo> urbi::UAbstractClient::callbacks_type [private]

Definition at line 508 of file uabstractclient.hh.

typedef int urbi::UAbstractClient::error_type

Error code.

0 iff no error. Other values are unspecified.

Reimplemented in urbi::USyncClient.

Definition at line 133 of file uabstractclient.hh.

Member Enumeration Documentation

anonymous enum

Connection Buffer size.

Enumerator:

URBI_BUFLEN

Definition at line 124 of file uabstractclient.hh.

anonymous enum

Standard port of Urbi server.

Enumerator:

URBI_PORT

Definition at line 126 of file uabstractclient.hh.

Constructor & Destructor Documentation

urbi::UAbstractClient::UAbstractClient	(	const std::string &	host = `default_host()`,
		unsigned	port = `URBI_PORT`,
		size_t	buflen = `URBI_BUFLEN`,
		bool	server = `false`
	)

Create a new instance and connect to the Urbi server.

Initialize sendBuffer and recvBuffer, and copy host and port.

Parameters:

host	IP address or name of the robot to connect to.
port	TCP port to connect to.
buflen	size of send and receive buffers.
server	whether accepts incoming connections. Implementations should establish the connection in their constructor.

Definition at line 180 of file uabstractclient.cc.

References recvBuffer, and sendBuffer.

urbi::UAbstractClient::~UAbstractClient ( ) [virtual]

Definition at line 216 of file uabstractclient.cc.

References urbi::getDefaultClient(), recvBuffer, sendBuffer, and urbi::setDefaultClient().

Member Function Documentation

UCallbackID urbi::UAbstractClient::addCallback	(	const char *	tag,
		UCallbackWrapper &	w
	)		`[protected]`

Add a callback to the list.

Definition at line 959 of file uabstractclient.cc.

References callbacks_, urbi::UCallbackInfo::id, listLock, urbi::nextId, urbi::UCallbackInfo::tag, and urbi::URBI_MAX_TAG_LENGTH.

Referenced by setCallback(), setClientErrorCallback(), setErrorCallback(), and setWildcardCallback().

void urbi::UAbstractClient::bins_clear ( ) [private]

Empty bins.

Definition at line 139 of file uabstractclient.cc.

References bins.

Referenced by process_recv_buffer_binary_(), and process_recv_buffer_text_().

void urbi::UAbstractClient::clientError	(	std::string	msg,
		int	code = `0`
	)		`[protected]`

Generate a client error message and notify callbacks.

Parameters:

msg	an optional string describing the error. The possible prefix "!!! " is skipped if present.
code	an optional system error code on which strerror is called

Definition at line 973 of file uabstractclient.cc.

References CLIENTERROR_TAG, urbi::UMessage::message, urbi::MESSAGE_ERROR, notifyCallbacks(), urbi::UMessage::rawMessage, urbi::UMessage::tag, urbi::UMessage::timestamp, and urbi::UMessage::type.

Referenced by clientError(), urbi::UClient::onError(), and urbi::UClient::pongTimeout().

void urbi::UAbstractClient::clientError	(	const char *	msg = `0`,
		int	code = `0`
	)		`[protected]`

Definition at line 997 of file uabstractclient.cc.

References clientError().

const std::string & urbi::UAbstractClient::connectionID ( ) const

Definition at line 1093 of file uabstractclient.cc.

References connectionID_, and urbi::LockableOstream::sendBufferLock.

Referenced by urbi::getClientConnectionID().

const char * urbi::UAbstractClient::default_host ( ) [inline, static]

Default host.

Definition at line 52 of file uabstractclient.hxx.

Referenced by urbi::main(), and urbi::usage().

int urbi::UAbstractClient::deleteCallback ( UCallbackID id )

Delete a callback.

Returns:: 0 if no callback with this id was found, 1 otherwise.

Definition at line 616 of file uabstractclient.cc.

References callbacks_, and listLock.

Referenced by sendCommand(), and sendSound().

UAbstractClient::error_type urbi::UAbstractClient::effective_send	(	const void *	buffer,
		size_t	size
	)		`[inline, protected]`

Direct forward the call to effectiveSend.

Allows to insert debugging information.

Definition at line 69 of file uabstractclient.hxx.

References effectiveSend(), and GD_CATEGORY().

Referenced by effective_send(), endPack(), send(), sendBin(), sendBinary(), urbi::USyncClient::syncGet_(), and urbi::USyncClient::syncSend().

UAbstractClient::error_type urbi::UAbstractClient::effective_send ( const char * buffer ) [inline, protected]

Bounce to effective_send() using strlen.

Definition at line 87 of file uabstractclient.hxx.

References effective_send().

UAbstractClient::error_type urbi::UAbstractClient::effective_send ( const std::string & buffer ) [inline, protected]

Bounce to effective_send() using c_str().

Definition at line 80 of file uabstractclient.hxx.

References effective_send().

virtual error_type urbi::UAbstractClient::effectiveSend	(	const void *	buffer,
		size_t	size
	)		`[protected, pure virtual]`

Queue data for sending, returns zero on success, nonzero on failure.

Implemented in urbi::UClient.

Referenced by effective_send().

UAbstractClient::error_type urbi::UAbstractClient::error ( ) const [inline]

Return current error status, or zero if no error occurred.

Definition at line 94 of file uabstractclient.hxx.

References rc.

Referenced by connect_plugin(), urbi::USyncClient::USyncClient(), urbi::UClient::waitForKernelVersion(), and urbi::USyncClient::waitForKernelVersion().

std::string urbi::UAbstractClient::fresh ( )

Return a identifier, for tags for instance.

Definition at line 701 of file uabstractclient.cc.

References counter_.

Referenced by makeUniqueTag(), sendCommand(), and sendSound().

int urbi::UAbstractClient::getAssociatedTag	(	UCallbackID	id,
		char *	tag
	)

Get the tag associated with a registered callback.

Returns:: 1 and fill tag on success, 0 on failure.

Definition at line 599 of file uabstractclient.cc.

References callbacks_, and listLock.

virtual unsigned int urbi::UAbstractClient::getCurrentTime ( ) const [pure virtual]

Get time in milliseconds since an unspecified but constant reference time.

Implemented in urbi::UClient.

int urbi::UAbstractClient::getCurrentTimestamp ( ) const

Definition at line 1087 of file uabstractclient.cc.

References currentTimestamp.

const std::string & urbi::UAbstractClient::getServerName ( ) const [inline]

Return the server name or IP address.

Definition at line 101 of file uabstractclient.hxx.

References host_.

unsigned urbi::UAbstractClient::getServerPort ( ) const [inline]

Return the server port.

Definition at line 109 of file uabstractclient.hxx.

References port_.

bool urbi::UAbstractClient::init ( ) const [inline]

Definition at line 62 of file uabstractclient.hxx.

References init_.

int urbi::UAbstractClient::kernelMajor ( ) const [inline]

Major kernel version. Dies if unknown yet.

Definition at line 116 of file uabstractclient.hxx.

References kernelMajor_, urbi::LockableOstream::sendBufferLock, and waitForKernelVersion().

Referenced by urbi::kernelMajor(), urbi::impl::RemoteUContextImpl::kernelVersion(), sendBinary(), setVersion(), and urbi::USyncClient::syncGet_().

int urbi::UAbstractClient::kernelMinor ( ) const [inline]

Minor kernel version. Dies if unknown yet.

Definition at line 125 of file uabstractclient.hxx.

References kernelMinor_, urbi::LockableOstream::sendBufferLock, and waitForKernelVersion().

Referenced by urbi::kernelMinor(), and urbi::impl::RemoteUContextImpl::kernelVersion().

const std::string & urbi::UAbstractClient::kernelVersion ( ) const [inline]

Kernel version string.

Call waitForKernelVersion to make sure it is defined (beware that there are two signatures, one for UAbstractClient, another for USyncClient).

Definition at line 134 of file uabstractclient.hxx.

References kernelVersion_, urbi::LockableOstream::sendBufferLock, and waitForKernelVersion().

Referenced by urbi::kernelVersion().

void urbi::UAbstractClient::makeUniqueTag ( char * tag )

Fill tag with a unique tag for this client.

Obsolete, use fresh() instead.

Definition at line 708 of file uabstractclient.cc.

References fresh().

void urbi::UAbstractClient::notifyCallbacks ( const UMessage & msg ) [virtual]

Pass the given UMessage to all registered callbacks with the corresponding tag, as if it were comming from the Urbi server.

Reimplemented in urbi::USyncClient.

Definition at line 161 of file uabstractclient.cc.

References callbacks_, listLock, urbi::matching_tag(), urbi::UMessage::tag, and urbi::URBI_REMOVE.

Referenced by clientError(), urbi::initialize(), urbi::UClient::onError(), urbi::UClient::pongTimeout(), process_recv_buffer_binary_(), process_recv_buffer_text_(), and transmitRemoteWrite().

UAbstractClient::error_type urbi::UAbstractClient::onClose ( ) [inline, protected, virtual]

Executed when closing connection.

Reimplemented in urbi::USyncClient, and urbi::UClient.

Definition at line 150 of file uabstractclient.hxx.

References closed_.

void urbi::UAbstractClient::onConnection ( ) [protected]

Lock on send buffer.

Can be locked by the user when performing an atomic operation in multiple calls. Must be called by subclasses when the connection is established.

Definition at line 1003 of file uabstractclient.cc.

References send(), setCallback(), setVersion(), SYNCLINE_WRAP, and VERSION_TAG.

Referenced by urbi::UClient::onConnect().

virtual void urbi::UAbstractClient::printf	(	const char *	format,
			...
	)		`[pure virtual]`

Notify of an error.

Implemented in urbi::UClient.

bool urbi::UAbstractClient::process_recv_buffer_binary_ ( ) [private]

New binary data is available.

Returns:: true if there is still data to process.

Definition at line 714 of file uabstractclient.cc.

References binaryBuffer, binaryBufferLength, binaryBufferPosition, binaryMode, bins, bins_clear(), currentCommand, currentTag, currentTimestamp, urbi::BinaryData::data, endOfHeaderPosition, nBracket, notifyCallbacks(), parsePosition, recvBuffer, recvBufferPosition, and urbi::BinaryData::size.

Referenced by processRecvBuffer().

bool urbi::UAbstractClient::process_recv_buffer_text_ ( ) [private]

New text data is available.

Returns:: true if there is still data to process.

Definition at line 779 of file uabstractclient.cc.

References binaryBuffer, binaryBufferLength, binaryBufferPosition, binaryMode, bins, bins_clear(), currentCommand, currentTag, currentTimestamp, endOfHeaderPosition, inString, nBracket, notifyCallbacks(), parsePosition, recvBuffer, recvBufferPosition, system, and urbi::tag_error.

Referenced by processRecvBuffer().

void urbi::UAbstractClient::processRecvBuffer ( )

Called each time new data is available in recvBuffer.

As long as this function has not returned, neither recvBuffer nor recvBufferPos may be modified.

Definition at line 925 of file uabstractclient.cc.

References binaryMode, process_recv_buffer_binary_(), and process_recv_buffer_text_().

Referenced by urbi::UClient::onRead().

UCallbackID urbi::UAbstractClient::setCallback	(	UCallbackWrapper &	callback,
		const char *	tag
	)

Associate a callback function with a tag. New style.

Parameters:

callback	a callback function wrapper, generated by callback()
tag	the tag to associate the callback with

Definition at line 952 of file uabstractclient.cc.

References addCallback().

Referenced by connect_plugin(), urbi::impl::RemoteUContextImpl::makeRTPLink(), onConnection(), urbi::impl::RemoteUContextImpl::RemoteUContextImpl(), sendCommand(), sendSound(), and setVersion().

UCallbackID urbi::UAbstractClient::setCallback	(	UCallback	cb,
		const char *	tag
	)

OLD-style callbacks.

Definition at line 584 of file uabstractclient.cc.

References addCallback().

UCallbackID urbi::UAbstractClient::setCallback	(	UCustomCallback	cb,
		void *	callbackData,
		const char *	tag
	)

Associate a callback function with a tag, specifiing a callback custom value that will be passed back to the callback function.

Definition at line 590 of file uabstractclient.cc.

References addCallback().

template<class C >

UCallbackID urbi::UAbstractClient::setCallback	(	C &	ref,
		UCallbackAction(C::*)(const UMessage &)	func,
		const char *	tag
	)

Deprecated:: { Callback to class member functions(old-style).}

Definition at line 726 of file uabstractclient.hh.

template<class C , class P1 >

UCallbackID urbi::UAbstractClient::setCallback	(	C &	ref,
		UCallbackAction(C::*)(P1, const UMessage &)	func,
		P1	p1,
		const char *	tag
	)

Definition at line 735 of file uabstractclient.hh.

template<class C , class P1 , class P2 >

UCallbackID urbi::UAbstractClient::setCallback	(	C &	ref,
		UCallbackAction(C::*)(P1, P2, const UMessage &)	func,
		P1	p1,
		P2	p2,
		const char *	tag
	)

Definition at line 744 of file uabstractclient.hh.

template<class C , class P1 , class P2 , class P3 >

UCallbackID urbi::UAbstractClient::setCallback	(	C &	ref,
		UCallbackAction(C::*)(P1, P2, P3, const UMessage &)	func,
		P1	p1,
		P2	p2,
		P3	p3,
		const char *	tag
	)

Definition at line 754 of file uabstractclient.hh.

template<class C , class P1 , class P2 , class P3 , class P4 >

UCallbackID urbi::UAbstractClient::setCallback	(	C &	ref,
		UCallbackAction(C::*)(P1, P2, P3, P4, const UMessage &)	func,
		P1	p1,
		P2	p2,
		P3	p3,
		P4	p4,
		const char *	tag
	)

Definition at line 764 of file uabstractclient.hh.

UCallbackID urbi::UAbstractClient::setClientErrorCallback ( UCallbackWrapper & callback )

Associate a callback with local connection errors.

Definition at line 946 of file uabstractclient.cc.

References addCallback(), and CLIENTERROR_TAG.

Referenced by urbi::initialize(), and urbi::impl::RemoteUContextImpl::RemoteUContextImpl().

UCallbackAction urbi::UAbstractClient::setConnectionID ( const UMessage & msg ) [protected, virtual]

A callback, installed by setVersion, that computes connectionID_.

Definition at line 1025 of file uabstractclient.cc.

References connectionID_, urbi::MESSAGE_DATA, urbi::LockableOstream::sendBufferLock, urbi::UMessage::type, urbi::URBI_CONTINUE, urbi::URBI_REMOVE, and urbi::UMessage::value.

Referenced by setVersion().

UCallbackID urbi::UAbstractClient::setErrorCallback ( UCallbackWrapper & callback )

Associate a callback function with all error messages from the server.

Definition at line 940 of file uabstractclient.cc.

References addCallback(), and urbi::tag_error.

Referenced by connect_plugin(), and urbi::initialize().

virtual void urbi::UAbstractClient::setKeepAliveCheck	(	unsigned	pingInterval,
		unsigned	pongTimeout
	)		`[pure virtual]`

Active KeepAlive functionality Sends an Urbi message at specified interval, if no anwser is received close the connection and notify 'URBI_ERROR_CONNECTION_TIMEOUT'.

Parameters: