connection
[Easydbus Library API]

Collaboration diagram for connection:

---

Detailed Description

Module for manage connection to DBus bus.

This module contains functions for manage connections to DBus bus. In particular, for now it is only supported connection to normal DBus system or session, no TCP or other solutions.

Connection Meta Information

Contact:

Daniele Rondina aka Ge@@ru <geaaru@gmail.com>

Status:

EasyDbus Core Library

License:

GPL

Contributor(s):

• Daniele Rondina aka Ge@@ru <geaaru@gmail.com>

Data Structures
struct	EasyDbus_conn
	EasyDbus_conn object Struct used for. More...
Functions
int	easydbus_conn_add_match_rule (EasyDbus_conn *data, enum event_type type, char *sender, char *interface, char *member, char *path, char *destination)
	easydbus includes
EasyDbus_conn *	easydbus_conn_create (void)
	Create and init EasyDbus_conn object.
int	easydbus_conn_destroy (EasyDbus_conn *conn)
	Deinitialize EasyDbus_conn object, close connection to Dbus and remove registered objects.
int	easydbus_conn_disable_filters (EasyDbus_conn *conn)
	Disable filters for objects.
int	easydbus_conn_enable_filters (EasyDbus_conn *conn)
	Enable filters for objects. In particular, this function MUST be called for manage Disconnected signal, reply message on service and for manage external signal object.
int	easydbus_conn_get_address (EasyDbus_conn *conn, char *serviceName, enum easydbus_bus bus, int flags)
	Acquire source address.
int	easydbus_conn_get_fd (EasyDbus_conn *data)
	Get connection file descriptor of connection.
int	easydbus_conn_get_n_object (EasyDbus_conn *conn)
	Get number of objects of EasyDbus_conn connection.
EasyDbus_object *	easydbus_conn_get_object (EasyDbus_conn *conn, unsigned int n)
	Get n-EasyDbus_object of connection.
const char *	easydbus_conn_get_service_name (const EasyDbus_conn *conn)
	Get service name.
int	easydbus_conn_get_system_service_address (EasyDbus_conn *data, char *serviceName)
	Acquire source address from environment variable.
int	easydbus_conn_remove_match_rule (EasyDbus_conn *data, enum event_type type, char *sender, char *interface, char *member, char *path, char *destination)
	Remove match rule on dbus.
int	easydbus_conn_set_error_cb (EasyDbus_conn *conn, easydbus_error_cb_f cb, void *user_closure)
	Set user callback for handle error on Dbus connection.
int	easydbus_conn_set_error_message_cb (EasyDbus_conn *conn, easydbus_error_message_cb_f e_cb, void *user_closure)
	Set user callback for handle error message not connected to a pending message.
int	easydbus_conn_set_reply_async_cb (EasyDbus_conn *conn, easydbus_reply_async_cb_f r_cb, void *user_closure)
	Set user callback for handle reply to asynchronous method call on easydbus_main_loop or through watcher.
int	easydbus_conn_set_reply_message_cb (EasyDbus_conn *conn, easydbus_reply_message_cb_f r_cb)
	Set user callback for handle reply message connected to a pending message.

---

Function Documentation

int easydbus_conn_add_match_rule	(	EasyDbus_conn *	data,
		enum event_type	type,
		char *	sender,
		char *	interface,
		char *	member,
		char *	path,
		char *	destination
	)			[inline]

easydbus includes

Add match to dbus

Todo:

manage args on rule.

Parameters:

	data	EasyDbus_conn object pointer
	type	enum event_type that identify message
	sender	sender of message. (can be equal to NULL)
	interface	interface of message (can be equal to NULL)
	member	member of message (can be equal to NULL)
	path	path of message (can be equal to NULL)
	destination	destination of message (can be equal to NULL)

Returns:

0 ok

-1 error

Definition at line 61 of file match_rules.c.

References EasyDbus_core::conn, EasyDbusDebug, and prepare_match_string().

{
   DBusError err;

   dbus_error_init (&err);

   struct EasyDbus_core *core = (struct EasyDbus_core *) data;
   char *buffer = NULL;

   buffer = prepare_match_string (type, sender,
                                  interface, member, path,
                                  destination);
   if (buffer == NULL)
      return -1;

   EasyDbusDebug ("MATCH_RULE = %s\n", buffer);

   dbus_bus_add_match (core->conn, buffer, &err);
   dbus_connection_flush (core->conn);

   if (dbus_error_is_set (&err)) {
      EasyDbusDebug ("Matched error (%s)\n", err.message);
      free (buffer);
      dbus_error_free (&err);
      return -1;
   }

   dbus_error_free (&err);
   free (buffer);
   return 0;
}

Here is the call graph for this function:

EasyDbus_conn* easydbus_conn_create

(

void

)

Create and init EasyDbus_conn object.

Returns:

NULL on error

pointer to EasyDbus_conn object

Todo:

create a dedicated group for this function.

Definition at line 335 of file acquire.c.

References EasyDbus_conn::bus, EasyDbus_core::conn, EASYDBUS_INVALID, EasyDbus_conn::error_cb, EasyDbus_conn::error_closure, EasyDbus_conn::error_message_cb, EasyDbus_conn::error_message_closure, EasyDbus_conn::flags, EasyDbus_core::handled_ext_signals, EasyDbus_core::objects, EasyDbus_core::pending_msgs, EasyDbus_conn::reply_async_cb, EasyDbus_conn::reply_message_cb, EasyDbus_core::service_name, EasyDbus_core::user_data, and EasyDbus_core::watcher.

{
   struct EasyDbus_core *conn =
      (struct EasyDbus_core *)
      malloc (sizeof (struct EasyDbus_core));

   if (!conn)
      return NULL;

   memset (conn, 0, sizeof (struct EasyDbus_core));

   conn->objects = NULL;
   conn->conn = NULL;
   conn->service_name = NULL;
   conn->watcher = NULL;
   conn->handled_ext_signals = NULL;
   conn->user_data.error_cb = NULL;
   conn->user_data.error_closure = NULL;
   conn->user_data.flags = 0;
   conn->user_data.bus = EASYDBUS_INVALID;
   conn->pending_msgs = NULL;
   conn->user_data.reply_async_cb = NULL;
   conn->user_data.error_message_cb = NULL;
   conn->user_data.error_message_closure = NULL;
   conn->user_data.reply_message_cb = NULL;

   return (EasyDbus_conn *) conn;
}

int easydbus_conn_destroy

(

EasyDbus_conn *

conn

)

Deinitialize EasyDbus_conn object, close connection to Dbus and remove registered objects.

Todo:

• see why enter on loop if call dbus_bus_release_name
• create a dedicated group for this function.
• see how manage closing of watchers.

Note:

At moment, DBus connection leave a reference count to 1 on libdbus-1 until exit from application. So it is possible, receive message still if you have destroyed connection. For this reason, i prefer call callback for remove watcher also in user space and drop message that arrive through connection.

Parameters:

conn

EasyDbus_conn object pointer

Returns:

0 ok

-1 error

Definition at line 403 of file acquire.c.

References EasyDbus_core::conn, EasyDbus_object_box::core, easydbus_ext_signal_free_skeleton(), easydbus_object_free_skeleton(), easydbus_object_unregister(), easydbus_pending_destroy(), EasyDbusDebug, EasyDbus_core::handled_ext_signals, EasyDbus_core::n_objs, EasyDbus_watcher::next, EasyDbus_Pending::next, EasyDbus_ext_signal::next, EasyDbus_object_box::next, EasyDbus_core::objects, EasyDbus_core::pending_msgs, EasyDbus_conn::registered_ondbus, EasyDbus_core::service_name, EasyDbus_ext_signal::signal, EasyDbus_watcher::watch, EasyDbus_core::watcher, EasyDbus_conn::watcher_add_cb, EasyDbus_conn::watcher_closure, and EasyDbus_conn::watcher_remove_cb.

{
   struct EasyDbus_core *core =
      (struct EasyDbus_core *) conn;
   struct EasyDbus_object_box *object = NULL;
   struct EasyDbus_watcher *watch = NULL;
   struct EasyDbus_Pending *p = NULL;
   struct EasyDbus_ext_signal *signal = NULL;
   DBusError err;
   int ret_val = 0;
   int i;

   EasyDbusDebug ("Destroy service %s...",
                  core->service_name ? core->
                  service_name : ".");

   dbus_error_init (&err);


   if (core->n_objs) {
      for (i = 0; i < core->n_objs; i++) {
         object = core->objects;
         core->objects = object->next;
         easydbus_object_unregister (conn, &object->core);
         easydbus_object_free_skeleton (&object->core);
      }
   }

   /* remove external signals */
   while (core->handled_ext_signals) {
      signal = core->handled_ext_signals;
      core->handled_ext_signals = signal->next;
      easydbus_ext_signal_free_skeleton (signal);
   }

   if (core->conn != NULL) {
      if (core->service_name != NULL) {
         if (conn->registered_ondbus)
            // dbus_bus_release_name (core->conn,
            //    core->service_name, &err);
            free (core->service_name);
         conn->registered_ondbus = 0;
      }
     
      for (p = core->pending_msgs; core->pending_msgs; 
           p = core->pending_msgs) {
         core->pending_msgs = p->next;
         easydbus_pending_destroy(p);
      }

      while (core->watcher != NULL) {
         watch = core->watcher;
         if (conn->watcher_remove_cb && 
             dbus_watch_get_enabled (core->watcher->watch))
           conn->watcher_remove_cb(core->watcher, 
                                   conn->watcher_closure);
         core->watcher = core->watcher->next;
         free (watch);
      }
      // use watcher_remove_cb field for detect
      // if was watcher.
      if (conn->watcher_remove_cb) {
         conn->watcher_remove_cb = NULL;
         conn->watcher_add_cb = NULL;
         // remove watch callbacks. Workaround for resolve problem
         // on call of callback when data are invalid.
         // (An another solution could be check connection data)
         dbus_connection_set_watch_functions (core->conn,
                                              NULL, NULL, NULL,
                                              NULL, NULL);
      } 

      // dbus_connection_remove_filter (core->conn,
      //    easydbus_core_filter_func, core);
      dbus_connection_unref (core->conn);
   }

   free (core);
   dbus_error_free (&err);

   return ret_val;
}

Here is the call graph for this function:

int easydbus_conn_disable_filters

(

EasyDbus_conn *

conn

)

Disable filters for objects.

Parameters:

conn

EasyDbus_conn object pointer

Returns:

-1 on error

0 ok

Definition at line 164 of file register_obj.c.

References EasyDbus_core::conn, easydbus_core_filter_func(), easydbus_filter_func(), easydbus_introspect_filter_func(), EasyDbusDebug, and EasyDbus_core::handled_introspect.

{
   struct EasyDbus_core *core = (struct EasyDbus_core *) conn;

   if (!conn)
      return -1;

   dbus_connection_remove_filter (core->conn,
                                  easydbus_core_filter_func, core);

   dbus_connection_remove_filter (core->conn,
                                  easydbus_filter_func, core);

   if (core->handled_introspect)
      dbus_connection_remove_filter (core->conn,
                                     easydbus_introspect_filter_func,
                                     core);

   EasyDbusDebug ("Filters Removed");
   return 0;
}

Here is the call graph for this function:

int easydbus_conn_enable_filters

(

EasyDbus_conn *

conn

)

Enable filters for objects. In particular, this function MUST be called for manage Disconnected signal, reply message on service and for manage external signal object.

Note:

Can be used also without define objects (if its are used EasyDbus_watchers) but MUST be called only one time still there are more on one registered objects. Still, MUST be called after that are been called introspectable functions.

Parameters:

conn

EasyDbus_conn object pointer.

Returns:

-1 error

0 ok

add core filter

Definition at line 201 of file register_obj.c.

References EasyDbus_core::conn, easydbus_core_filter_func(), easydbus_filter_func(), easydbus_introspect_filter_func(), EasyDbusDebug, and EasyDbus_core::handled_introspect.

Referenced by easydbus_conn_reconnect().

{
   struct EasyDbus_core *core = (struct EasyDbus_core *) conn;

   if (!conn)
      return -1;

   // This solution works only for register object
   // not for simple client. See for an another solution.
   if (!dbus_connection_add_filter (core->conn,
                                    easydbus_core_filter_func, core,
                                    NULL)) {
      EasyDbusDebug ("Error on add core filter");
      return -1;
   }

   if (core->handled_introspect)
      if (!dbus_connection_add_filter (core->conn,
                                       easydbus_introspect_filter_func,
                                       core, NULL)) {
         EasyDbusDebug ("Error on add filter");
         return -1;
      }

   if (!dbus_connection_add_filter (core->conn,
                                    easydbus_filter_func, core,
                                    NULL)) {
      EasyDbusDebug ("Error on add filter");
      return -1;
   }

   EasyDbusDebug ("Filters activated");

   return 0;
}

Here is the call graph for this function:

int easydbus_conn_get_address	(	EasyDbus_conn *	conn,
		char *	serviceName,
		enum easydbus_bus	bus,
		int	flags
	)

Acquire source address.

Parameters:

	serviceName	Name of service that must be acquired.
	bus	bus type. see enum easydbus_bus for more informations.
	conn	pointer to EasyDbus_conn object.
	flags	easydbus connection flags.

See also:

enum easydbus_connection_flags.

Returns:

-1 error

EASYDBUS_CONN_NAME_SERVICE_EXISTS name service exists.

EASYDBUS_CONN_NAME_SERVICE_IN_QUEUE name service in queue.

EASYDBUS_CONN_NAME_SERVICE_PRIMARY name service is primary name.

EASYDBUS_CONN_NAME_SERVICE_RENAMED name service is been renamed.

Definition at line 66 of file acquire.c.

References EasyDbus_conn::bus, easydbus_get_address_onsession(), easydbus_get_address_onsystem(), easydbus_get_address_serverSession(), EASYDBUS_SESSION, EASYDBUS_SESSION_SERVER, EASYDBUS_SYSTEM, and EasyDbus_conn::flags.

{
   if (serviceName == NULL || conn == NULL)
      return -1;

   conn->flags = flags;
   conn->bus = bus;
   switch (bus) {
      case EASYDBUS_SESSION:
         return 
            easydbus_get_address_onsession (conn, serviceName);
         break;
      case EASYDBUS_SYSTEM:
         return 
            easydbus_get_address_onsystem (conn, serviceName);
         break;
      case EASYDBUS_SESSION_SERVER:
         return 
            easydbus_get_address_serverSession (conn, serviceName);
         break;
      default:
         break;
   }

   return -1;
}

Here is the call graph for this function:

int easydbus_conn_get_fd

(

EasyDbus_conn *

data

)

Get connection file descriptor of connection.

Note:

Work only on linux/unix systems. It is advised use easydbus_enable_watcher function and easydbus_watcher_get_fd_list function for recover a file descriptor and manage events.

Parameters:

data

EasyDbus_conn object pointer

Returns:

file descriptor of connection with dbus.

-1 error

Definition at line 600 of file acquire.c.

References EasyDbus_core::conn.

{
   struct EasyDbus_core *core = (struct EasyDbus_core *) data;
   int fd;

   if (data)
      //if (dbus_connection_get_fd (core->conn, &fd))
      if (dbus_connection_get_unix_fd (core->conn, &fd))
         return fd;

   return -1;
}

int easydbus_conn_get_n_object

(

EasyDbus_conn *

conn

)

[inline]

Get number of objects of EasyDbus_conn connection.

Parameters:

conn

EasyDbus_conn object pointer.

Returns:

-1 on error

number of objects managed of service connection.

Definition at line 238 of file acquire.c.

References EasyDbus_core::n_objs.

{
   return (conn ? 
           ((struct EasyDbus_core *) conn)->n_objs : -1);
}

EasyDbus_object* easydbus_conn_get_object	(	EasyDbus_conn *	conn,
		unsigned int	n
	)

Get n-EasyDbus_object of connection.

Precondition:

• data != NULL
• n <= number of objects of object.

Parameters:

	conn	pointer to EasyDbus_conn object.
	n	number of the object to get.

Returns:

NULL on error

pointer to EasyDbus_object.

Definition at line 255 of file acquire.c.

References EasyDbus_core::n_objs, EasyDbus_object_box::next, and EasyDbus_core::objects.

{
   int i;
   struct EasyDbus_core *core = 
      (struct EasyDbus_core *) conn;
   struct EasyDbus_object_box *ans = NULL;

   if (conn && (((int) n) <= core->n_objs))
      for (i = 0, ans = core->objects;
           i < core->n_objs;
           i++, ans = ans->next);

   return (EasyDbus_object *) ans;
}

const char* easydbus_conn_get_service_name

(

const EasyDbus_conn *

conn

)

Get service name.

Parameters:

conn

EasyDbus_conn object pointer.

Returns:

current service name.

Definition at line 584 of file acquire.c.

References EasyDbus_core::service_name.

{
   return conn ? (const char *)
      ((struct EasyDbus_core *)conn)->service_name : NULL;
}

int easydbus_conn_get_system_service_address	(	EasyDbus_conn *	data,
		char *	serviceName
	)			[inline]

Acquire source address from environment variable.

Used for dbus service started by dbus daemon.

Todo:

• manage use of easydbus_connection_flags.

Parameters:

	data	EasyDbus_conn object pointer
	serviceName	name of service that must be acquired.

Returns:

0 ok

-1 error

Definition at line 499 of file acquire.c.

References EasyDbus_core::conn, easydbus_save_serviceName(), EasyDbusDebug, and EasyDbus_conn::registered_ondbus.

{
   struct EasyDbus_core *core = (struct EasyDbus_core *) data;
   char *dbus_starter_address = NULL;
   DBusError err;

   dbus_error_init (&err);

   /* recover DBUS_STARTER_ADDRESS environment variable */
   dbus_starter_address = getenv ("DBUS_STARTER_ADDRESS");

   if (dbus_starter_address == NULL) {
      EasyDbusDebug ("Error on recover dbus_starter_address");
      return -1;
   }

   core->conn = dbus_connection_open (dbus_starter_address, &err);

   if (!core->conn) {
      EasyDbusDebug ("Error %s from "
                     "dbus_connection_open: %s",
                     err.name, err.message);
      return -1;
   }

   /* do not allw libdbus to exit on connection failure ( This
    * may around random exit () on SIGPIPE errors) */
   dbus_connection_set_exit_on_disconnect (core->conn, FALSE);

   dbus_bus_register (core->conn, &err);

   if (dbus_error_is_set (&err)) {
      EasyDbusDebug ("Error %s from "
                     "dbus_bus_register: %s", err.name, err.message);
      goto error_acquire;
   }

   /* TODO: manage return values correctly */
   /* request for set service name */
   dbus_bus_request_name (core->conn, serviceName, 0, &err);


   if (dbus_error_is_set (&err)) {
      EasyDbusDebug ("Error %s from "
                     "dbus_bus_request_name: %s",
                     err.name, err.message);
      goto error_acquire;
   }

   /* see if this is correct and what it do. */
   //if (set_unique_nameID (core, serviceName)) {
   // EasyDbusDebug ("Error on set unique nameID");
   // goto error_acquire;
   //}

   data->registered_ondbus = 1;

   if (easydbus_save_serviceName (core, serviceName)) {
      EasyDbusDebug ("Error on set unique nameID");
      goto error_acquire;
   }

   dbus_error_free (&err);

   return 0;

 error_acquire:
   if (data->registered_ondbus)
      dbus_bus_release_name (core->conn, serviceName, &err);

   if (core->conn != NULL)
      dbus_connection_unref (core->conn);

   dbus_error_free (&err);

   return -1;
}

Here is the call graph for this function:

int easydbus_conn_remove_match_rule	(	EasyDbus_conn *	data,
		enum event_type	type,
		char *	sender,
		char *	interface,
		char *	member,
		char *	path,
		char *	destination
	)			[inline]

Remove match rule on dbus.

Todo:

manage args on rule.

Parameters:

	data	EasyDbus_conn object pointer
	type	enum event_type that identify message
	sender	sender of message. (can be equal to NULL)
	interface	interface of message (can be equal to NULL)
	member	member of message (can be equal to NULL)
	path	path of message (can be equal to NULL)
	destination	destination of message (can be equal to NULL)

Returns:

0 ok

-1 error

Definition at line 110 of file match_rules.c.

References EasyDbus_core::conn, EasyDbusDebug, and prepare_match_string().

{
   DBusError err;

   struct EasyDbus_core *core = (struct EasyDbus_core *) data;
   char *buffer = NULL;

   dbus_error_init (&err);

   buffer = prepare_match_string (type, sender,
                                  interface, member, path,
                                  destination);
   if (buffer == NULL)
      return -1;

   EasyDbusDebug ("Remove MATCH_RULE = %s\n", buffer);

   dbus_bus_remove_match (core->conn, buffer, &err);
   dbus_connection_flush (core->conn);

   if (dbus_error_is_set (&err)) {
      EasyDbusDebug ("Remove match error (%s)\n", err.message);
      dbus_error_free (&err);
      free (buffer);
      return -1;
   }

   dbus_error_free (&err);
   free (buffer);
   return 0;
}

Here is the call graph for this function:

int easydbus_conn_set_error_cb	(	EasyDbus_conn *	conn,
		easydbus_error_cb_f	cb,
		void *	user_closure
	)

Set user callback for handle error on Dbus connection.

Returns:

-1 on error

0 ok

Definition at line 218 of file acquire.c.

References EasyDbus_conn::error_cb, and EasyDbus_conn::error_closure.

{
  if (!conn || !cb) 
     return -1; 

  conn->error_cb = cb;
  conn->error_closure = user_closure;

  return 0;
}

int easydbus_conn_set_error_message_cb	(	EasyDbus_conn *	conn,
		easydbus_error_message_cb_f	e_cb,
		void *	user_closure
	)

Set user callback for handle error message not connected to a pending message.

Returns:

-1 on error

0 ok

Definition at line 298 of file acquire.c.

References EasyDbus_conn::error_message_cb, and EasyDbus_conn::error_message_closure.

{
   if (!conn || !e_cb)
      return -1;
   conn->error_message_cb = e_cb;
   conn->error_message_closure = user_closure;

   return 0;
}

int easydbus_conn_set_reply_async_cb	(	EasyDbus_conn *	conn,
		easydbus_reply_async_cb_f	r_cb,
		void *	user_closure
	)

Set user callback for handle reply to asynchronous method call on easydbus_main_loop or through watcher.

Returns:

-1 on error

0 ok

Definition at line 279 of file acquire.c.

References EasyDbus_conn::reply_async_cb, and EasyDbus_conn::reply_async_closure.

{
   if (!conn || !r_cb)
      return -1;
   conn->reply_async_cb = r_cb;
   conn->reply_async_closure = user_closure;

   return 0;
}

int easydbus_conn_set_reply_message_cb	(	EasyDbus_conn *	conn,
		easydbus_reply_message_cb_f	r_cb
	)

Set user callback for handle reply message connected to a pending message.

Returns:

-1 on error

0 ok

Definition at line 317 of file acquire.c.

References EasyDbus_conn::reply_message_cb.

{
   if (!conn || !r_cb)
      return -1;
   conn->reply_message_cb = r_cb;

   return 0;
}

---