src/dbus.h

   1 /*
   2  * Copyright © 2013 David Herrmann <dh.herrmann@gmail.com>
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and
   5  * its documentation for any purpose is hereby granted without fee, provided
   6  * that the above copyright notice appear in all copies and that both that
   7  * copyright notice and this permission notice appear in supporting
   8  * documentation, and that the name of the copyright holders not be used in
   9  * advertising or publicity pertaining to distribution of the software
  10  * without specific, written prior permission.  The copyright holders make
  11  * no representations about the suitability of this software for any
  12  * purpose.  It is provided "as is" without express or implied warranty.
  13  *
  14  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  15  * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  16  * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
  17  * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  18  * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
  19  * CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  20  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21  */
  22
  23 #ifndef _WESTON_DBUS_H_
  24 #define _WESTON_DBUS_H_
  25
  26 #include "config.h"
  27
  28 #include <errno.h>
  29 #include <wayland-server.h>
  30
  31 #include "compositor.h"
  32
  33 #ifdef HAVE_DBUS
  34
  35 #include <dbus/dbus.h>
  36
  37 /*
  38  * weston_dbus_open() - Open new dbus connection
  39  *
  40  * Opens a new dbus connection to the bus given as @bus. It automatically
  41  * integrates the new connection into the main-loop @loop. The connection
  42  * itself is returned in @out.
  43  * This also returns a context source used for dbus dispatching. It is
  44  * returned on success in @ctx_out and must be passed to weston_dbus_close()
  45  * unchanged. You must not access it from outside of a dbus helper!
  46  *
  47  * Returns 0 on success, negative error code on failure.
  48  */
  49 int weston_dbus_open(struct wl_event_loop *loop, DBusBusType bus,
  50                      DBusConnection **out, struct wl_event_source **ctx_out);
  51
  52 /*
  53  * weston_dbus_close() - Close dbus connection
  54  *
  55  * Closes a dbus connection that was previously opened via weston_dbus_open().
  56  * It unbinds the connection from the main-loop it was previously bound to,
  57  * closes the dbus connection and frees all resources. If you want to access
  58  * @c after this call returns, you must hold a dbus-reference to it. But
  59  * notice that the connection is closed after this returns so it cannot be
  60  * used to spawn new dbus requests.
  61  * You must pass the context source returns by weston_dbus_open() as @ctx.
  62  */
  63 void weston_dbus_close(DBusConnection *c, struct wl_event_source *ctx);
  64
  65 /*
  66  * weston_dbus_add_match() - Add dbus match
  67  *
  68  * Configure a dbus-match on the given dbus-connection. This match is saved
  69  * on the dbus-server as long as the connection is open. See dbus-manual
  70  * for information. Compared to the dbus_bus_add_match() this allows a
  71  * var-arg formatted match-string.
  72  */
  73 int weston_dbus_add_match(DBusConnection *c, const char *format, ...);
  74
  75 /*
  76  * weston_dbus_add_match_signal() - Add dbus signal match
  77  *
  78  * Same as weston_dbus_add_match() but does the dbus-match formatting for
  79  * signals internally.
  80  */
  81 int weston_dbus_add_match_signal(DBusConnection *c, const char *sender,
  82                                  const char *iface, const char *member,
  83                                  const char *path);
  84
  85 /*
  86  * weston_dbus_remove_match() - Remove dbus match
  87  *
  88  * Remove a previously configured dbus-match from the dbus server. There is
  89  * no need to remove dbus-matches if you close the connection, anyway.
  90  * Compared to dbus_bus_remove_match() this allows a var-arg formatted
  91  * match string.
  92  */
  93 void weston_dbus_remove_match(DBusConnection *c, const char *format, ...);
  94
  95 /*
  96  * weston_dbus_remove_match_signal() - Remove dbus signal match
  97  *
  98  * Same as weston_dbus_remove_match() but does the dbus-match formatting for
  99  * signals internally.
 100  */
 101 void weston_dbus_remove_match_signal(DBusConnection *c, const char *sender,
 102                                      const char *iface, const char *member,
 103                                      const char *path);
 104
 105 #endif /* HAVE_DBUS */
 106
 107 #endif // _WESTON_DBUS_H_