edelib: EdbusConnection Class Reference

edelib 1.0

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

- Class List
- Class Hierarchy
- Class Members

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

D-Bus connection and data sender. More...

`#include <edelib/EdbusConnection.h>`

## Public Member Functions
| EdbusConnection ()
| ~EdbusConnection ()
bool | connect (EdbusConnectionType ctype)
void | disconnect (void)
bool | connected (void)
bool | send (const EdbusMessage &content)
bool | send_with_reply_and_block (const EdbusMessage &content, int timeout_ms, EdbusMessage &ret)
bool | request_name (const char *name, int mode=EDBUS_NAME_NO_REPLACE)
const char * | unique_name (void)
void | signal_callback (EdbusCallback cb, void *data)
void | method_callback (EdbusCallback cb, void *data)
void | add_signal_match (const char *path, const char *interface, const char *name)
void | add_method_match (const char *path, const char *interface, const char *name)
void | register_object (const char *path)
void | unregister_object (const char *path)
void | setup_listener (void)
void | setup_listener_with_fltk (void)
int | wait (int timeout_ms)
EdbusError * | error (void)

## Detailed Description

D-Bus connection and data sender.

This is the main class representing connection to the D-Bus daemon. Besides doing actual connection, this class is used also to send and receive messages.

EdbusConnection implements message loop; it will wait until message arrived or until message was send. Because of this, EdbusConnection implements two way of looping:

- ordinary loop
- loop via FLTK

Ordinary loop is recomended only in non-gui applications; it will block until connection was closed or object was destroyed in different way.

See also
  EdbusConnection::setup_listener()

Looping via FLTK (relying on Fl::run() or Fl::wait()) will be used for gui applications; gui components will receive own events and callbacks, but in the same time EdbusConnection will also be able to listen and send messages.

See also
  EdbusConnection::setup_listener_with_fltk()

To connect to the bus, connect() must be called first with one of EdbusConnectionType values. All messages will be sent to that bus type until disconnect() was called or object were destroyed.

In case you want to listen for calls, you would acquire name via EdbusConnection::request_name(), on what clients will connect. You would also register object via EdbusConnection::register_object().

With EdbusConnection you can send two types of messages:

- signals
- methods

Messages are recived via callbacks. Edbus splits callbacks on:

- signal callbacks (EdbusConnection::signal_callback())
- method callbacks (EdbusConnection::method_callback())

Here is the example of one application that will listen "Foo" signal:

int sig_cb(const EdbusMessage* m, void*) {
printf("Got signal: %s : %s : %s\n", m->path(), m->interface(), m->member());
// this means signal were processed so dbus can discard it
return 1;
}
int main() {
EdbusConnection conn;
if(!conn.connect(EDBUS_SESSION))
// fail
if(!conn.request_name("org.test.Server"))
// fail
srv.register_object("/org/test/Server/Foo");
srv.signal_callback(sig_cb, 0);
// looping stuff
srv.setup_listener()
while(srv.wait(1000))
;
return 0;
}

Here is application that will send "Foo" signal:

int main() {
EdbusConnection conn;
if(!conn.connect(EDBUS_SESSION))
// fail
// create empty signal message without any parameters
EdbusMessage msg;
msg.create_signal("/org/test/Server/Foo", "org.test.Signal", "Foo");
// send it
conn.send(msg);
return 0;
}

## Constructor & Destructor Documentation

EdbusConnection | ( |  | ) |

Creates empty object. You can't do anything usefull with it unless call connect() after.

~EdbusConnection | ( |  | ) |

Destroys object. Also disconnect from bus if connection is alive.

## Member Function Documentation

void add_method_match | ( | const char * | path,
|  | const char * | interface,
|  | const char * | name
| ) |  |

Install matcher for requested method calls. All method calls that matches to the given path, interface and name will be reported via method callback registered with method_callback().

This is not too much suitable as signal matchers since you definitely wants to listen all method requests that client sends directly to you.

You can install more matchers.

void add_signal_match | ( | const char * | path,
|  | const char * | interface,
|  | const char * | name
| ) |  |

Install matcher for received signals. All signals that matches to the given path, interface and name will be reported via signal callback registered with signal_callback().

You can install more matchers.

bool connect | ( | EdbusConnectionType | ctype | ) |

Connects to either session or system bus.

Returns
  true if connected, otherwise false and EdbusError object will be set

Parameters

  ctype | says what connection is requested

bool connected | ( | void |  | ) |

Return if this object is connected. This method will not only check the status of internal connection holder, like if connect() was called, but will also check if current connection is alive, consulting DBus API call.

Returns
  true if connected or false if not

void disconnect | ( | void |  | ) |

Disconnects from bus. Also clears internal watchers so you can issue connect() again.

EdbusError* error | ( | void |  | ) |

Return last error that happened; if error wasn't set, returned value will be NULL. Error can be invalid, so it must be checked too.

See also
  EdbusError::valid()

void method_callback | ( | EdbusCallback | cb,
|  | void * | data
| ) |  |

Register callback for method call. When peer requests a call from this connection, this function will be called. EdbusMessage parameter is arguments for method call.

Parameters

  cb | is callback
  data | is optional data that will be passed to the callback

void register_object | ( | const char * | path | ) |

Register objects this connection will server. A path must be valid D-Bus object path and this function will assert if otherwise. If object already registered, it will not be added any more.

You can register more that one object.

If you registered at least one object, data not send to it will be ignored. On other hand, if none object was added, other objects receiving data will be reported here too.

Note
  This function only stores pointer to the string, so make sure it is in static memory

bool request_name | ( | const char * | name,
|  | int | mode = `EDBUS_NAME_NO_REPLACE`
| ) |  |

Try to set readable name, e.g. org.equinoxproject.Listener. If EdbusConnection object wants to accept messages, clients will send them to this name.

This function also can be used to assure unique name in the bus; if you set EDBUS_NAME_NO_REPLACE every other call (from program itself or external program) for request with the same name will return false value. This does not mean you will not receive a bus messages; they would be queued and dispatched among listeners with the same name.

With other flags (EDBUS_NAME_REPLACE_EXISTING and EDBUS_NAME_NO_REPLACE) you can achieve smooth name replacement. For example, if you have program service1 that registered org.example.Service and (during runtime) want to replace it with upgraded or modified service2, simply setting in service2 EDBUS_NAME_REPLACE_EXISTING flag, and EDBUS_NAME_ALLOW_REPLACE service1 will do the job. Then, service1 will receive NameLost from org.freedesktop.DBus interface and can choose to quit or do something else.

mode flags can be OR-ed, so EDBUS_NAME_ALLOW_REPLACE | EDBUS_NAME_REPLACE_EXISTING can work in both programs (in given example), except NameLost will receive program that was started first, but request_name() will not return false. OR-ing with EDBUS_NAME_NO_REPLACE have no much sense, and if is detected, it is considered as plain EDBUS_NAME_NO_REPLACE.

Returns
  true if got requested name or false if not and EdbusError object (get via error()) will be set

Parameters

  name | is name to be requested
  mode | is what to do when requested name already exists

bool send | ( | const EdbusMessage & | content | ) |

Sends a message.

Returns
  true if succesfully got reply

Parameters

  content | is message to be send

Note
  if send() fails, EdbusError will not be set since D-BUS default send function does not set error

bool send_with_reply_and_block | ( | const EdbusMessage & | content,
|  | int | timeout_ms,
|  | EdbusMessage & | ret
| ) |  |

Call remote method and wait for reply. It will block untill reply is arrived or timer exceeded.

Returns
  true if succesfully got reply or false if not and EdbusError object (get via error()) will be set

Parameters

  content | is message to be send
  timeout_ms | is waiting time for arrival in milliseconds
  ret | will be filled with reply content if this function returns true

void setup_listener | ( | void |  | ) |

Setup listening stuff. After this, EdbusConnection object will be ready to accept requests.

Note
  You want to call wait() after this so listener can await requests in the loop.

void setup_listener_with_fltk | ( | void |  | ) |

The same as setup_listener() except it will be integrated in FLTK application without blocking FLTK event loops. After this you will call either Fl::run() of Fl::wait()

void signal_callback | ( | EdbusCallback | cb,
|  | void * | data
| ) |  |

Register callback for signal arrival. When signal is arrived, it will be passed to the callback as EdbusMessage where you can extract content via it's members.

Parameters

  cb | is callback
  data | is optional data that will be passed to the callback

const char* unique_name | ( | void |  | ) |

Get unique name for this connection. Returned value have sense only for D-BUS.

void unregister_object | ( | const char * | path | ) |

Unregister already registered object.

int wait | ( | int | timeout_ms | ) |

Run listener and wait clients connection or signals. This is blocking call and is assumed it will not be run inside GUI application. For FLTK GUI application, you should use setup_listener_with_fltk().

This function can be used similar to the Fl::wait(), like:

// init objects and etc.
conn.setup_listener();
while(conn.wait(1000))
;

Parameters

  timeout_ms | is time in milliseconds to wait for connections

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

- edelib/EdbusConnection.h