Abstract parent of classes that want to register themselves with CASA's DBus server. More...

#include <QtDBusXmlApp.qo.h>

Inheritance diagram for casa::QtDBusXmlApp:

Static Public Member Functions
static bool	dbusXmlCallNoRet (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, bool isAsync=false)
	Calls the given method on the object with the given name that is registered with CASA's DBus server, using the given parameters.
static bool	dbusXmlCall (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, bool &retValue, bool *retValueSet=NULL)
	Like dbusXmlCallNoRet(), except that if the remote method has a return value of the given type, then the value is set accordingly.
static bool	dbusXmlCall (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, int &retValue, bool *retValueSet=NULL)
static bool	dbusXmlCall (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, uInt &retValue, bool *retValueSet=NULL)
static bool	dbusXmlCall (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, double &retValue, bool *retValueSet=NULL)
static bool	dbusXmlCall (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, String &retValue, bool *retValueSet=NULL)
static bool	dbusXmlCall (const String &fromName, const String &objectName, const String &methodName, const Record &parameters, Record &retValue, bool *retValueSet=NULL)
Protected Member Functions
	QtDBusXmlApp ()

virtual	~QtDBusXmlApp ()
	Destructor.
virtual void	dbusRunXmlMethod (const String &methodName, const Record &parameters, Record &retValue, const String &callerName, bool isAsync)=0
	ABSTRACT METHODS //.
virtual void	dbusXmlReceived (const QtDBusXML &xml)
	VIRTUAL METHODS //.
bool	dbusRegisterSelf (const String &name="")
	IMPLEMENTED METHODS //.
void	dbusUnregisterSelf ()
	Unregisters this object with CASA's DBus server, if it is registered.
bool	dbusSelfIsRegistered () const
	Returns true if this object is currently registered with CASA's DBus server, false otherwise.
String	dbusSelfRegisteredName () const
	Returns the name that this object is registered with with CASA's DBus server, or an empty String if this application is not currently registered.
bool	dbusXmlCallNoRet (const String &objectName, const String &methodName, const Record &parameters, bool isAsync=false)
	Calls the static version of the method with this application's name.
bool	dbusXmlCall (const String &objectName, const String &methodName, const Record &parameters, bool &retValue, bool *retValueSet=NULL)
bool	dbusXmlCall (const String &objectName, const String &methodName, const Record &parameters, int &retValue, bool *retValueSet=NULL)
bool	dbusXmlCall (const String &objectName, const String &methodName, const Record &parameters, uInt &retValue, bool *retValueSet=NULL)
bool	dbusXmlCall (const String &objectName, const String &methodName, const Record &parameters, double &retValue, bool *retValueSet=NULL)
bool	dbusXmlCall (const String &objectName, const String &methodName, const Record &parameters, String &retValue, bool *retValueSet=NULL)
bool	dbusXmlCall (const String &objectName, const String &methodName, const Record &parameters, Record &retValue, bool *retValueSet=NULL)
Private Member Functions
void	dbusSlot (QtDBusXML &xml)
	Method for when one of the slots in the adaptor is activated.
Static Private Member Functions
static bool	dbusXmlCall (const String &from, const String &to, const String &methodName, bool methodIsAsync, const Record &parameters, Record *retValue)
	Private Static Methods //.
Private Attributes
bool	dbusRegistered_

QString	dbusName_
	Name that the application is registered with.
QtDBusXmlAppAdaptor *	dbusAdaptor_
	DBus adaptor.
Friends
class	QtDBusXmlAppAdaptor

Detailed Description

Abstract parent of classes that want to register themselves with CASA's DBus server.

The class also provides public static methods for other code to send DBus messages without needing to subclass and register. This class hides the details of how the DBus communication happens behind the scenes and presents an interface using CASA objects like Records. Applications that want to use this DBus communication layer need to know about the following for each method call: The object name. Each object that registers with CASA's DBus server must do so with a unique name. Outside objects then can send messages to that object by using its name. Names have some restrictions; see dbusRegisterSelf(). You can check if a certain name is currently registered using dbusNameIsRegistered(). The method name. Each object keeps track of what methods it supports, and this process happens dynamically on a per-message basis. Whether to call asynchronously or not. See dbusXmlCallNoRet(). The method parameters. The parameters are set using name/value pairs in a Record. Like the method name, this is on a dynamic, per-object basis. IMPORTANT: not all types are currently supported; see QtDBusXML documentation to see what is currently implemented. The method return value. IMPORTANT: not all types are currently supported; see QtDBusXML documentation to see what is currently implemented.

If a class wants to receive DBus communications, it must take the following steps: 1) Subclass QtDBusXmlApp. 2) Implement the dbusRunXmlMethod() method, which is called when a DBus method call is received. For a discussion of the parameters to this method, see above. 3) Call dbusRegisterSelf() with a unique name.

Classes that wish to send but not receive messages do NOT need to subclass QtDBusXmlApp and can just use the public static methods to call methods on DBus-registered objects. For a discussion of the parameters to these static methods, see above.

Definition at line 79 of file QtDBusXmlApp.qo.h.

Constructor & Destructor Documentation

casa::QtDBusXmlApp::QtDBusXmlApp ( ) [protected]

Constructor.

virtual casa::QtDBusXmlApp::~QtDBusXmlApp ( ) [protected, virtual]

Destructor.

Unregisters from the CASA DBus server if needed.

Member Function Documentation

bool casa::QtDBusXmlApp::dbusRegisterSelf ( const String & name = "" ) [protected]

IMPLEMENTED METHODS //.

Registers this object with CASA's DBus server, if it is not already, with the given name and returns whether or not the registration succeeded. If the name is blank, then the last set name is used, UNLESS this is the first time registering in which case the registration will fail. The registration name MUST contain only numbers, letters, and underscores, and MUST be unique for the DBus server; trying to register with a name that is already in use will result in registration failure. (Note, however, that the name needs ONLY to be unique within the CASA DBus application names rather than all system-wide DBus application names.) Trying to register when already registered (see dbusSelfIsRegistered()) will result in registration failure; to change names, you must unregister and then reregister with the new name.

virtual void casa::QtDBusXmlApp::dbusRunXmlMethod	(	const String &	methodName,
		const Record &	parameters,
		Record &	retValue,
		const String &	callerName,
		bool	isAsync
	)		`[protected, pure virtual]`

ABSTRACT METHODS //.

Runs the method with the specified name using the given parameters and placing the return value, if any, into the given retValue record. NOTE: when defining the return value, the name doesn't matter because the first entry is used. The caller name, and whether this is an asynchronous call or not, are also provided but do not need to be used. Note, however, that asynchronous method calls will NOT use a return value even if one is set.

Implemented in casa::PlotMSDBusApp.

bool casa::QtDBusXmlApp::dbusSelfIsRegistered ( ) const [protected]

Returns true if this object is currently registered with CASA's DBus server, false otherwise.

String casa::QtDBusXmlApp::dbusSelfRegisteredName ( ) const [protected]

Returns the name that this object is registered with with CASA's DBus server, or an empty String if this application is not currently registered.

Referenced by dbusXmlCall(), and dbusXmlCallNoRet().

void casa::QtDBusXmlApp::dbusSlot ( QtDBusXML & xml ) [private]

Method for when one of the slots in the adaptor is activated.

First sends to dbusXmlReceived(), then to dbusRunXmlMethod().

void casa::QtDBusXmlApp::dbusUnregisterSelf ( ) [protected]

Unregisters this object with CASA's DBus server, if it is registered.

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		bool &	retValue,
		bool *	retValueSet = `NULL`
	)		`[static]`

Like dbusXmlCallNoRet(), except that if the remote method has a return value of the given type, then the value is set accordingly.

If there is no return value or it is a different type, the value is not set. If retValueSet is given, it will be set to true if the return value was set and false otherwise.

Referenced by dbusXmlCall().

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		int &	retValue,
		bool *	retValueSet = `NULL`
	)		`[static]`

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		uInt &	retValue,
		bool *	retValueSet = `NULL`
	)		`[static]`

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		double &	retValue,
		bool *	retValueSet = `NULL`
	)		`[static]`

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		String &	retValue,
		bool *	retValueSet = `NULL`
	)		`[static]`

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		Record &	retValue,
		bool *	retValueSet = `NULL`
	)		`[static]`

bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		bool &	retValue,
		bool *	retValueSet = `NULL`
	)		`[inline, protected]`

Definition at line 197 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCall().

bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		int &	retValue,
		bool *	retValueSet = `NULL`
	)		`[inline, protected]`

Definition at line 202 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCall().

bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		uInt &	retValue,
		bool *	retValueSet = `NULL`
	)		`[inline, protected]`

Definition at line 207 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCall().

bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		double &	retValue,
		bool *	retValueSet = `NULL`
	)		`[inline, protected]`

Definition at line 212 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCall().

bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		String &	retValue,
		bool *	retValueSet = `NULL`
	)		`[inline, protected]`

Definition at line 217 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCall().

bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		Record &	retValue,
		bool *	retValueSet = `NULL`
	)		`[inline, protected]`

Definition at line 222 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCall().

static bool casa::QtDBusXmlApp::dbusXmlCall	(	const String &	from,
		const String &	to,
		const String &	methodName,
		bool	methodIsAsync,
		const Record &	parameters,
		Record *	retValue
	)		`[static, private]`

Private Static Methods //.

Helper method for calling remote methods.

static bool casa::QtDBusXmlApp::dbusXmlCallNoRet	(	const String &	fromName,
		const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		bool	isAsync = `false`
	)		`[static]`

Calls the given method on the object with the given name that is registered with CASA's DBus server, using the given parameters.

The given from name is sent to the remote object, but not used otherwise. If isAsync is true, then the remote method runs asynchronously, which means that control returns immediately after sending the message. This method does NOT give a return value, even if the remote method does. Returns true for success, false for failure. Will fail if the given object name is not registered with CASA's DBus server.

Referenced by dbusXmlCallNoRet().

bool casa::QtDBusXmlApp::dbusXmlCallNoRet	(	const String &	objectName,
		const String &	methodName,
		const Record &	parameters,
		bool	isAsync = `false`
	)		`[inline, protected]`

Calls the static version of the method with this application's name.

Definition at line 192 of file QtDBusXmlApp.qo.h.

References dbusSelfRegisteredName(), and dbusXmlCallNoRet().

virtual void casa::QtDBusXmlApp::dbusXmlReceived ( const QtDBusXML & xml ) [inline, protected, virtual]

VIRTUAL METHODS //.

Method that can be overridden if the subclass wants to be informed whenever ANY dbus message is received, even if this object is not the intended recipient. Note that most applications won't need to do this (and probably shouldn't) since dbusRunXmlMethod() will be called with the appropriate parameters if this object is the intended recipient.

Reimplemented in casa::PlotMSDBusApp.

Definition at line 159 of file QtDBusXmlApp.qo.h.