edelib: EdbusMessage Class Reference

edelib 1.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Friends | List of all members
EdbusMessage Class Reference
D-Bus classes and functions

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

References list< T >::push_back().

Referenced by edelib::operator<<().

iterator begin | ( | void |  | ) |
| inline

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

References list< T >::begin().

const_iterator begin | ( | void |  | ) | const
| inline

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

References list< T >::begin().

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

References list< T >::end().

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

References list< T >::end().

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

References list< T >::size().

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

- edelib/EdbusMessage.h