Data transporter for D-Bus. More...

#include <edelib/EdbusMessage.h>

Public Types
typedef list< EdbusData >::iterator	iterator

typedef list< EdbusData > ::const_iterator	const_iterator

Public Member Functions
	EdbusMessage ()

	EdbusMessage (DBusMessage *msg)

	~EdbusMessage ()

void	create_signal (const char path, const char interface, const char *name)

void	create_method_call (const char service, const char path, const char interface, const char method)

void	create_reply (const EdbusMessage &replying_to)

void	create_error_reply (const EdbusMessage &replying_to, const char *errmsg)

void	clear_all (void)

bool	is_signal (void)

bool	is_method_call (void)

bool	is_error_reply (const char *errmsg)

void	path (const char *np)

const char *	path (void) const

void	interface (const char *ni)

const char *	interface (void) const

void	destination (const char *nd)

const char *	destination (void) const

void	member (const char *nm)

const char *	member (void) const

void	sender (const char *ns)

const char *	sender (void) const

const char *	signature (void) const

void	append (const EdbusData &data)

iterator	begin (void)

const_iterator	begin (void) const

iterator	end (void)

const_iterator	end (void) const

unsigned int	size (void) const

Friends
class	EdbusConnection

Detailed Description

Data transporter for D-Bus.

EdbusMessage is essentially the way you send and receive a bunch of EdbusData objects. You can see it as e-mail message: EdbusData represents a content you wrote or read and EdbusMessage is that content plus headers with origin, destination and message type.

Knowing that, EdbusMessage can be:

signal, created with create_signal(); it represents D-Bus signal
method call, created with create_method_call(); calls a method on service objects
method reply, created with create_reply(); sends a reply on called method
error reply, created with create_error_reply(); sends a error reply on called method

As you will see from below, signals do not have destination; they are broadcasted over session or system bus and all clients (connected on session or system bus) that do not filter signals will receive it.

On other hand, methods (calls and replies) do have destination and they are sent directly to the client. This is the main difference between signals and methods.

Creating a specific EdbusMessage type you do via one of the create_ members. If you call them on already created EdbusMessage with some content, that content will be discarded and EdbusMessage will become appropriate type.

When you create a message, you wants to add some data. This is done via append() member like:

*   EdbusMessage m;
*   m.create_signal("/org/example/SignalObject", "org.example.Signal", "MySignal");
*   m.append(EdbusData::from_int32(34));
*   m.append(EdbusData::from_bool(true));
*   m.append(EdbusData::from_string("some string"));
* 

EdbusMessage have operator<<() that makes adding data much more... sexy ;-)

There is above sample via this opeartor:

*   EdbusMessage m;
*   m.create_signal("/org/example/SignalObject", "org.example.Signal", "MySignal");
*   m << EdbusData::from_int32(32) << EdbusData::from_bool(true) << EdbusData::from_string("some string");
* 

Getting data from message is done via iterator. Since iterator do not know what type it points to, you must check it manually before calling appropriate EdbusData function to fetch concrete data or bad things will happen (assertion will be upon you).

Let say you received above message and wants to get a content from it. You will do it like:

*   EdbusMessage::const_iterator it = m.begin(), it_end = m.end();
*
*   for(; it != it_end; ++it) {
*     if((*it).is_int32())
*       printf("Got int with: %i\n", (*it).to_int32());
*
*     if((*it).is_bool())
*       printf("Got bool with: %i\n", (*it).to_bool());
*
*     if((*it).is_string())
*       printf("Got string with: %s\n", (*it).to_string());
*   }
* 

Changing (or removing) already present data inside EdbusMessage is done via iterator. With this you can e.g. modify received message and send it again.

Member Typedef Documentation

typedef list<EdbusData>::const_iterator const_iterator

Declare EdbusMessage const iterator.

typedef list<EdbusData>::iterator iterator

Declare EdbusMessage iterator.

Constructor & Destructor Documentation

EdbusMessage ( )

inline

Create an empty EdbusMessage object. Nothing will be allocated until you call one of the create_ members. Until that, message is marked as invalid and EdbusConnection will refuse to send it.

EdbusMessage ( DBusMessage * msg )

Create an EdbusMessage from DBusMessage. This is used to simplify internals and you should not use it directly.

~EdbusMessage ( )

Clears internal data

Member Function Documentation

void append ( const EdbusData & data )

inline

Append EdbusData object in message

Referenced by edelib::operator<<().

iterator begin ( void )

inline

Returns iterator at the message start. It points to the first element

const_iterator begin ( void ) const

inline

Returns const iterator at the message start. It points to the first element

void clear_all ( void )

Clears all EdbusMessage data (including message headers with destination, type and etc.) and marks it as invalid. If you want to send this object again, make sure to re-create it again with one of create_ members.

This is since DBus internally queues messages after they are sent (if there is need to re-send them again) there is no way to clear message content without destroying headers

void create_error_reply	(	const EdbusMessage &	replying_to,
		const char *	errmsg
	)

Create error reply

Parameters

replying_to	is a message to be replyed
errmsg	is error string to be sent

void create_method_call	(	const char *	service,
		const char *	path,
		const char *	interface,
		const char *	method
	)

Create a method call

Parameters

service	is destination service name
path	is destination object path
interface	is destination interface name
method	is method to be called

void create_reply ( const EdbusMessage & replying_to )

Create a reply for method

Parameters

replying_to is a message to be replyed

void create_signal	(	const char *	path,
		const char *	interface,
		const char *	name
	)

Create a signal message

Parameters

path	is destination object path
interface	is destination interface name
name	is signal name

void destination ( const char * nd )

Sets the message's destination.

The destination is the name of another connection on the bus and may be either the unique name assigned by the bus to each connection, or a well-known name specified in advance

It will do nothing if one of the create_ members are not called before

const char* destination ( void ) const

Get a message destination It will return NULL if one of the create_ members are not called before

iterator end ( void )

inline

Returns iterator at the message end. It does not points to the last element, but element after the last, and you must not dereferce it

const_iterator end ( void ) const

inline

Returns const iterator at the message end. It does not points to the last element, but element after the last, and you must not dereferce it

void interface ( const char * ni )

Set interface name for destination. It will do nothing if one of the create_ members are not called before

const char* interface ( void ) const

Get interface name for destination It will return NULL if one of the create_ members are not called before

bool is_error_reply ( const char * errmsg )

Returns true if current message is error reply type

bool is_method_call ( void )

Returns true if current message is method call type

bool is_signal ( void )

Returns true if current message is signal type

void member ( const char * nm )

Set method name to be called.

Note: This function can be used to set signal name too

It will do nothing if one of the create_ members are not called before

const char* member ( void ) const

Get method or signal name from message It will return NULL if one of the create_ members are not called before

void path ( const char * np )

Set object path for destination It will do nothing if one of the create_ members are called before

const char* path ( void ) const

Get object path for destination It will return NULL if one of the create_ members are not called before

void sender ( const char * ns )

Sets the message sender.

The sender must be a valid bus name as defined in the D-Bus specification

It will do nothing if one of the create_ members are not called before

const char* sender ( void ) const

Gets the unique name of the connection which originated this message, or NULL if unknown or inapplicable.

The sender is filled in by the message bus.

It will return NULL if one of the create_ members are not called before

const char* signature ( void ) const

Returns the signature of this message. You will not need this unless you know what returned value means.

A signature will contain only reasonable content when you receive message via one of the callbacks set inside EdbusConnection.

It will return NULL if one of the create_ members are not called before

unsigned int size ( void ) const

inline

Returns the size of EdbusMessage content

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

edelib/EdbusMessage.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation