Driver Class Reference

#include <driver.h>

Inherited by Acoustics, Acts, AdaptiveMCL, AmtecPowerCube, Aodv, BumperSafe, Camera1394, CameraCompress, CameraUncompress, CameraUVC, CameraV4L, canonvcc4, ClodBuster, Cmucam2, CMVisionBF, Create, Dummy, ER, Erratic, FakeLocalize, Festival, FixedTones, FlockOfBirds_Device, GarciaDriver, GarminNMEA, ImageBase, ImageSeq, InertiaCube2, InsideM300, Iwspy, KartoLogger, Khepera, LaserBar, LaserBarcode, LaserFeature, LaserPoseInterp, LaserSafe, LaserTransform, LaserVisualBarcode, LaserVisualBW, LifoMCom, LinuxJoystick, LinuxWiFi, MapFile, MapTransform, Mica2, MicroStrain3DMG, Mixer, ND, Nomad, NomadPosition, NomadSonar, Obot, P2OS, PassThrough, PTU46_Device, RCore_XBridge, ReadLog, REB, Relay, RFLEX, Roomba, SegwayRMP, SickLMS200, SickNAV200, SickPLS, SickS3000, SkyetekM1, SonyEVID30, SphereDriver, Sphinx2, SrvAdv_MDNS, URGLaserDriver, VFH_Class, VMapFile, Waveaudio, Wavefront, wbr914, WriteLog, and Yarp_Image.

List of all members.

Detailed Description

Base class for all drivers.

This class manages driver subscriptions, threads, and data marshalling to/from device interfaces. All drivers inherit from this class, and most will overload the Setup(), Shutdown() and Main() methods.


Public Member Functions
virtual void	Lock (void)
	Lock access to driver internals.
virtual void	Unlock (void)
	Unlock access to driver internals.
void	Publish (player_devaddr_t addr, MessageQueue queue, uint8_t type, uint8_t subtype, void src=NULL, size_t len=0, double *timestamp=NULL)
	Publish a message via one of this driver's interfaces.
void	Publish (MessageQueue queue, player_msghdr_t hdr, void *src)
	Publish a message via one of this driver's interfaces.
	Driver (ConfigFile *cf, int section, bool overwrite_cmds, size_t queue_maxlen, int interf)
	Constructor for single-interface drivers.
	Driver (ConfigFile *cf, int section, bool overwrite_cmds=true, size_t queue_maxlen=PLAYER_MSGQUEUE_DEFAULT_MAXLEN)
	Constructor for multiple-interface drivers.
virtual	~Driver ()
	Destructor.
int	GetError ()
	Get last error value.
virtual int	Subscribe (player_devaddr_t addr)
	Subscribe to this driver.
virtual int	Unsubscribe (player_devaddr_t addr)
	Unsubscribe from this driver.
virtual int	Setup ()=0
	Initialize the driver.
virtual int	Shutdown ()=0
	Finalize the driver.
virtual void	Main (void)
	Main method for driver thread.
virtual void	MainQuit (void)
	Cleanup method for driver thread (called when main exits).
void	ProcessMessages (int maxmsgs)
	Process pending messages.
void	ProcessMessages (void)
	Process pending messages.
virtual int	ProcessMessage (MessageQueue resp_queue, player_msghdr hdr, void *data)
	Message handler.
virtual void	Update ()
	Update non-threaded drivers.
Public Attributes
pthread_t	driverthread
	The driver's thread.
MessageQueue *	ret_queue
	Last requester's queue.
player_devaddr_t	device_addr
	Default device address (single-interface drivers).
int	subscriptions
	Number of subscriptions to this driver.
int	entries
	Total number of entries in the device table using this driver.
bool	alwayson
	Always on flag.
MessageQueue *	InQueue
	Queue for all incoming messages for this driver.
Protected Member Functions
virtual void	StartThread (void)
virtual void	StopThread (void)
	Cancel (and wait for termination) of the driver thread.
int	AddInterface (player_devaddr_t addr)
	Add an interface.
void	SetError (int code)
	Set/reset error code.
void	Wait ()
	Wait for new data to arrive on the driver's queue.
Static Protected Member Functions
static void *	DummyMain (void *driver)
	Dummy main (just calls real main).
static void	DummyMainQuit (void *driver)
	Dummy main cleanup (just calls real main cleanup).

Constructor & Destructor Documentation

Driver::Driver	(	ConfigFile *	cf,
		int	section,
		bool	overwrite_cmds,
		size_t	queue_maxlen,
		int	interf
	)

Constructor for single-interface drivers.

Parameters:

	cf	Current configuration file
	section	Current section in configuration file
	overwrite_cmds	Do new commands overwrite old ones?
	queue_maxlen	How long can the incoming queue grow?
	interf	Player interface code; e.g., PLAYER_POSITION_CODE

Driver::Driver	(	ConfigFile *	cf,
		int	section,
		bool	overwrite_cmds = `true`,
		size_t	queue_maxlen = `PLAYER_MSGQUEUE_DEFAULT_MAXLEN`
	)

Constructor for multiple-interface drivers.

Use AddInterface() to specify individual interfaces.

Parameters:

	cf	Current configuration file
	section	Current section in configuration file
	overwrite_cmds	Do new commands overwrite old ones?
	queue_maxlen	How long can the incoming queue grow?

Member Function Documentation

int Driver::AddInterface ( player_devaddr_t addr ) [protected]

Add an interface.

Parameters:

addr

Player device address.

Returns:: 0 on success, non-zero otherwise.

static void* Driver::DummyMain ( void * driver ) [static, protected]

Dummy main (just calls real main).

This is used to simplify thread creation.

static void Driver::DummyMainQuit ( void * driver ) [static, protected]

Dummy main cleanup (just calls real main cleanup).

This is used to simplify thread termination.

int Driver::GetError ( ) [inline]

Get last error value.

Call this after the constructor to check whether anything went wrong.

virtual void Driver::Main ( void ) [virtual]

Main method for driver thread.

drivers have their own thread of execution, created using StartThread(); this is the entry point for the driver thread, and must be overloaded by all threaded drivers.

virtual void Driver::MainQuit ( void ) [virtual]

Cleanup method for driver thread (called when main exits).

Overload this method and to do additional cleanup when the driver thread exits.

virtual int Driver::ProcessMessage	(	MessageQueue *	resp_queue,
		player_msghdr *	hdr,
		void *	data
	)	`[virtual]`

Message handler.

This function is called once for each message in the incoming queue. Reimplement it to provide message handling. Return 0 if you handled the message and -1 otherwise

Parameters:

	resp_queue	The queue to which any response should go.
	hdr	The message header
	data	The message body

void Driver::ProcessMessages

(

void

)

Process pending messages.

Equivalent to ProcessMessages(0).

void Driver::ProcessMessages

(

int

maxmsgs

)

Process pending messages.

Call this to automatically process messages using registered handler, Driver::ProcessMessage.

Parameters:

maxmsgs

The maximum number of messages to process. If -1, then process until the queue is empty (this may result in an infinite loop if messages are being added to the queue faster than they are processed). If 0, then check the current length and process up to that many messages. If > 0, process up to the indicated number of messages.

void Driver::Publish	(	MessageQueue *	queue,
		player_msghdr_t *	hdr,
		void *	src
	)

Publish a message via one of this driver's interfaces.

Use this form of Publish if you already have the message header assembled.

Parameters:

	queue	If non-NULL, the target queue; if NULL, then the message is sent to all interested parties.
	hdr	The message header
	src	The message body

void Driver::Publish	(	player_devaddr_t	addr,
		MessageQueue *	queue,
		uint8_t	type,
		uint8_t	subtype,
		void *	src = `NULL`,
		size_t	len = `0`,
		double *	timestamp = `NULL`
	)

Publish a message via one of this driver's interfaces.

This form of Publish will assemble the message header for you.

Parameters:

	addr	The origin address
	queue	If non-NULL, the target queue; if NULL, then the message is sent to all interested parties.
	type	The message type
	subtype	The message subtype
	src	The message body
	len	Length of the message body
	timestamp	Timestamp for the message body (if NULL, then the current time will be filled in)

virtual int Driver::Setup ( ) [pure virtual]

Initialize the driver.

This function is called with the first client subscribes; it MUST be implemented by the driver.

Returns:: Returns 0 on success.

virtual int Driver::Shutdown ( ) [pure virtual]

Finalize the driver.

This function is called with the last client unsubscribes; it MUST be implemented by the driver.

Returns:: Returns 0 on success.

virtual void Driver::StopThread ( void ) [protected, virtual]

Cancel (and wait for termination) of the driver thread.

This method is usually called from the overloaded Shutdown() method to terminate the driver thread.

virtual int Driver::Subscribe ( player_devaddr_t addr ) [virtual]

Subscribe to this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.

Parameters:

addr

Address of the device to subscribe to (the driver may have more than one interface).

Returns:: Returns 0 on success.

virtual int Driver::Unsubscribe ( player_devaddr_t addr ) [virtual]

Unsubscribe from this driver.

The Subscribe() and Unsubscribe() methods are used to control subscriptions to the driver; a driver MAY override them, but usually won't.

Parameters:

addr

Address of the device to unsubscribe from (the driver may have more than one interface).

Returns:: Returns 0 on success.

void Driver::Wait ( ) [inline, protected]

Wait for new data to arrive on the driver's queue.

Call this method to block until a new message arrives on Driver::InQueue. This method will return immediately if at least one message is already waiting.

Member Data Documentation

bool Driver::alwayson

Always on flag.

If true, driver should be "always on", i.e., player will "subscribe" at startup, before any clients subscribe. The "alwayson" parameter in the config file can be used to turn this feature on as well (in which case this flag will be set to reflect that setting).

pthread_t Driver::driverthread

The driver's thread.

The driver's thread, when managed by StartThread() and StopThread().

int Driver::entries

Total number of entries in the device table using this driver.

This is updated and read by the Device class.

MessageQueue* Driver::ret_queue

Last requester's queue.

Pointer to a queue to which this driver owes a reply. Used mainly by non-threaded drivers to cache the return address for requests that get forwarded to other devices.

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

driver.h

Last updated 12 September 2005 21:38:45

Driver Class Reference

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation