gdbus/gdbus.h

   1 /*
   2  *
   3  *  D-Bus helper library
   4  *
   5  *  Copyright (C) 2004-2011  Marcel Holtmann <marcel@holtmann.org>
   6  *
   7  *
   8  *  This program is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License as published by
  10  *  the Free Software Foundation; either version 2 of the License, or
  11  *  (at your option) any later version.
  12  *
  13  *  This program is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with this program; if not, write to the Free Software
  20  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  21  *
  22  */
  23
  24 #ifndef __GDBUS_H
  25 #define __GDBUS_H
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 #include <dbus/dbus.h>
  32 #include <glib.h>
  33
  34 typedef enum GDBusMethodFlags GDBusMethodFlags;
  35 typedef enum GDBusSignalFlags GDBusSignalFlags;
  36 typedef enum GDBusPropertyFlags GDBusPropertyFlags;
  37 typedef enum GDBusSecurityFlags GDBusSecurityFlags;
  38
  39 typedef struct GDBusArgInfo GDBusArgInfo;
  40 typedef struct GDBusMethodTable GDBusMethodTable;
  41 typedef struct GDBusSignalTable GDBusSignalTable;
  42 typedef struct GDBusPropertyTable GDBusPropertyTable;
  43 typedef struct GDBusSecurityTable GDBusSecurityTable;
  44
  45 typedef void (* GDBusWatchFunction) (DBusConnection *connection,
  46                                                         void *user_data);
  47
  48 typedef void (* GDBusMessageFunction) (DBusConnection *connection,
  49                                          DBusMessage *message, void *user_data);
  50
  51 typedef gboolean (* GDBusSignalFunction) (DBusConnection *connection,
  52                                         DBusMessage *message, void *user_data);
  53
  54 DBusConnection *g_dbus_setup_bus(DBusBusType type, const char *name,
  55                                                         DBusError *error);
  56
  57 DBusConnection *g_dbus_setup_private(DBusBusType type, const char *name,
  58                                                         DBusError *error);
  59
  60 gboolean g_dbus_request_name(DBusConnection *connection, const char *name,
  61                                                         DBusError *error);
  62
  63 gboolean g_dbus_set_disconnect_function(DBusConnection *connection,
  64                                 GDBusWatchFunction function,
  65                                 void *user_data, DBusFreeFunction destroy);
  66
  67 typedef void (* GDBusDestroyFunction) (void *user_data);
  68
  69 typedef DBusMessage * (* GDBusMethodFunction) (DBusConnection *connection,
  70                                         DBusMessage *message, void *user_data);
  71
  72 typedef gboolean (*GDBusPropertyGetter)(const GDBusPropertyTable *property,
  73                                         DBusMessageIter *iter, void *data);
  74
  75 typedef guint32 GDBusPendingPropertySet;
  76
  77 typedef void (*GDBusPropertySetter)(const GDBusPropertyTable *property,
  78                         DBusMessageIter *value, GDBusPendingPropertySet id,
  79                         void *data);
  80
  81 typedef gboolean (*GDBusPropertyExists)(const GDBusPropertyTable *property,
  82                                                                 void *data);
  83
  84 typedef guint32 GDBusPendingReply;
  85
  86 typedef void (* GDBusSecurityFunction) (DBusConnection *connection,
  87                                                 const char *action,
  88                                                 gboolean interaction,
  89                                                 GDBusPendingReply pending);
  90
  91 enum GDBusFlags {
  92         G_DBUS_FLAG_ENABLE_EXPERIMENTAL = (1 << 0),
  93 };
  94
  95 enum GDBusMethodFlags {
  96         G_DBUS_METHOD_FLAG_DEPRECATED   = (1 << 0),
  97         G_DBUS_METHOD_FLAG_NOREPLY      = (1 << 1),
  98         G_DBUS_METHOD_FLAG_ASYNC        = (1 << 2),
  99         G_DBUS_METHOD_FLAG_EXPERIMENTAL = (1 << 3),
 100 };
 101
 102 enum GDBusSignalFlags {
 103         G_DBUS_SIGNAL_FLAG_DEPRECATED   = (1 << 0),
 104         G_DBUS_SIGNAL_FLAG_EXPERIMENTAL = (1 << 1),
 105 };
 106
 107 enum GDBusPropertyFlags {
 108         G_DBUS_PROPERTY_FLAG_DEPRECATED = (1 << 0),
 109 };
 110
 111 enum GDBusSecurityFlags {
 112         G_DBUS_SECURITY_FLAG_DEPRECATED        = (1 << 0),
 113         G_DBUS_SECURITY_FLAG_BUILTIN           = (1 << 1),
 114         G_DBUS_SECURITY_FLAG_ALLOW_INTERACTION = (1 << 2),
 115 };
 116
 117 struct GDBusArgInfo {
 118         const char *name;
 119         const char *signature;
 120 };
 121
 122 struct GDBusMethodTable {
 123         const char *name;
 124         GDBusMethodFunction function;
 125         GDBusMethodFlags flags;
 126         unsigned int privilege;
 127         const GDBusArgInfo *in_args;
 128         const GDBusArgInfo *out_args;
 129 };
 130
 131 struct GDBusSignalTable {
 132         const char *name;
 133         GDBusSignalFlags flags;
 134         const GDBusArgInfo *args;
 135 };
 136
 137 struct GDBusPropertyTable {
 138         const char *name;
 139         const char *type;
 140         GDBusPropertyGetter get;
 141         GDBusPropertySetter set;
 142         GDBusPropertyExists exists;
 143         GDBusPropertyFlags flags;
 144 };
 145
 146 struct GDBusSecurityTable {
 147         unsigned int privilege;
 148         const char *action;
 149         GDBusSecurityFlags flags;
 150         GDBusSecurityFunction function;
 151 };
 152
 153 #define GDBUS_ARGS(args...) (const GDBusArgInfo[]) { args, { } }
 154
 155 #define GDBUS_METHOD(_name, _in_args, _out_args, _function) \
 156         .name = _name, \
 157         .in_args = _in_args, \
 158         .out_args = _out_args, \
 159         .function = _function
 160
 161 #define GDBUS_ASYNC_METHOD(_name, _in_args, _out_args, _function) \
 162         .name = _name, \
 163         .in_args = _in_args, \
 164         .out_args = _out_args, \
 165         .function = _function, \
 166         .flags = G_DBUS_METHOD_FLAG_ASYNC
 167
 168 #define GDBUS_DEPRECATED_METHOD(_name, _in_args, _out_args, _function) \
 169         .name = _name, \
 170         .in_args = _in_args, \
 171         .out_args = _out_args, \
 172         .function = _function, \
 173         .flags = G_DBUS_METHOD_FLAG_DEPRECATED
 174
 175 #define GDBUS_DEPRECATED_ASYNC_METHOD(_name, _in_args, _out_args, _function) \
 176         .name = _name, \
 177         .in_args = _in_args, \
 178         .out_args = _out_args, \
 179         .function = _function, \
 180         .flags = G_DBUS_METHOD_FLAG_ASYNC | G_DBUS_METHOD_FLAG_DEPRECATED
 181
 182 #define GDBUS_EXPERIMENTAL_METHOD(_name, _in_args, _out_args, _function) \
 183         .name = _name, \
 184         .in_args = _in_args, \
 185         .out_args = _out_args, \
 186         .function = _function, \
 187         .flags = G_DBUS_METHOD_FLAG_EXPERIMENTAL
 188
 189 #define GDBUS_EXPERIMENTAL_ASYNC_METHOD(_name, _in_args, _out_args, _function) \
 190         .name = _name, \
 191         .in_args = _in_args, \
 192         .out_args = _out_args, \
 193         .function = _function, \
 194         .flags = G_DBUS_METHOD_FLAG_ASYNC | G_DBUS_METHOD_FLAG_EXPERIMENTAL
 195
 196 #define GDBUS_NOREPLY_METHOD(_name, _in_args, _out_args, _function) \
 197         .name = _name, \
 198         .in_args = _in_args, \
 199         .out_args = _out_args, \
 200         .function = _function, \
 201         .flags = G_DBUS_METHOD_FLAG_NOREPLY
 202
 203 #define GDBUS_SIGNAL(_name, _args) \
 204         .name = _name, \
 205         .args = _args
 206
 207 #define GDBUS_DEPRECATED_SIGNAL(_name, _args) \
 208         .name = _name, \
 209         .args = _args, \
 210         .flags = G_DBUS_SIGNAL_FLAG_DEPRECATED
 211
 212 #define GDBUS_EXPERIMENTAL_SIGNAL(_name, _args) \
 213         .name = _name, \
 214         .args = _args, \
 215         .flags = G_DBUS_SIGNAL_FLAG_EXPERIMENTAL
 216
 217 void g_dbus_set_flags(int flags);
 218
 219 gboolean g_dbus_register_interface(DBusConnection *connection,
 220                                         const char *path, const char *name,
 221                                         const GDBusMethodTable *methods,
 222                                         const GDBusSignalTable *signals,
 223                                         const GDBusPropertyTable *properties,
 224                                         void *user_data,
 225                                         GDBusDestroyFunction destroy);
 226 gboolean g_dbus_unregister_interface(DBusConnection *connection,
 227                                         const char *path, const char *name);
 228
 229 gboolean g_dbus_register_security(const GDBusSecurityTable *security);
 230 gboolean g_dbus_unregister_security(const GDBusSecurityTable *security);
 231
 232 void g_dbus_pending_success(DBusConnection *connection,
 233                                         GDBusPendingReply pending);
 234 void g_dbus_pending_error(DBusConnection *connection,
 235                                 GDBusPendingReply pending,
 236                                 const char *name, const char *format, ...)
 237                                         __attribute__((format(printf, 4, 5)));
 238 void g_dbus_pending_error_valist(DBusConnection *connection,
 239                                 GDBusPendingReply pending, const char *name,
 240                                         const char *format, va_list args);
 241
 242 DBusMessage *g_dbus_create_error(DBusMessage *message, const char *name,
 243                                                 const char *format, ...)
 244                                         __attribute__((format(printf, 3, 4)));
 245 DBusMessage *g_dbus_create_error_valist(DBusMessage *message, const char *name,
 246                                         const char *format, va_list args);
 247 DBusMessage *g_dbus_create_reply(DBusMessage *message, int type, ...);
 248 DBusMessage *g_dbus_create_reply_valist(DBusMessage *message,
 249                                                 int type, va_list args);
 250
 251 gboolean g_dbus_send_message(DBusConnection *connection, DBusMessage *message);
 252 gboolean g_dbus_send_error(DBusConnection *connection, DBusMessage *message,
 253                                 const char *name, const char *format, ...)
 254                                          __attribute__((format(printf, 4, 5)));
 255 gboolean g_dbus_send_error_valist(DBusConnection *connection,
 256                                         DBusMessage *message, const char *name,
 257                                         const char *format, va_list args);
 258 gboolean g_dbus_send_reply(DBusConnection *connection,
 259                                 DBusMessage *message, int type, ...);
 260 gboolean g_dbus_send_reply_valist(DBusConnection *connection,
 261                                 DBusMessage *message, int type, va_list args);
 262
 263 gboolean g_dbus_emit_signal(DBusConnection *connection,
 264                                 const char *path, const char *interface,
 265                                 const char *name, int type, ...);
 266 gboolean g_dbus_emit_signal_valist(DBusConnection *connection,
 267                                 const char *path, const char *interface,
 268                                 const char *name, int type, va_list args);
 269
 270 guint g_dbus_add_service_watch(DBusConnection *connection, const char *name,
 271                                 GDBusWatchFunction connect,
 272                                 GDBusWatchFunction disconnect,
 273                                 void *user_data, GDBusDestroyFunction destroy);
 274 guint g_dbus_add_disconnect_watch(DBusConnection *connection, const char *name,
 275                                 GDBusWatchFunction function,
 276                                 void *user_data, GDBusDestroyFunction destroy);
 277 guint g_dbus_add_signal_watch(DBusConnection *connection,
 278                                 const char *sender, const char *path,
 279                                 const char *interface, const char *member,
 280                                 GDBusSignalFunction function, void *user_data,
 281                                 GDBusDestroyFunction destroy);
 282 guint g_dbus_add_properties_watch(DBusConnection *connection,
 283                                 const char *sender, const char *path,
 284                                 const char *interface,
 285                                 GDBusSignalFunction function, void *user_data,
 286                                 GDBusDestroyFunction destroy);
 287 gboolean g_dbus_remove_watch(DBusConnection *connection, guint tag);
 288 void g_dbus_remove_all_watches(DBusConnection *connection);
 289
 290 void g_dbus_pending_property_success(GDBusPendingPropertySet id);
 291 void g_dbus_pending_property_error_valist(GDBusPendingReply id,
 292                         const char *name, const char *format, va_list args);
 293 void g_dbus_pending_property_error(GDBusPendingReply id, const char *name,
 294                                                 const char *format, ...);
 295 void g_dbus_emit_property_changed(DBusConnection *connection,
 296                                 const char *path, const char *interface,
 297                                 const char *name);
 298 gboolean g_dbus_get_properties(DBusConnection *connection, const char *path,
 299                                 const char *interface, DBusMessageIter *iter);
 300
 301 gboolean g_dbus_attach_object_manager(DBusConnection *connection);
 302 gboolean g_dbus_detach_object_manager(DBusConnection *connection);
 303
 304 typedef struct GDBusClient GDBusClient;
 305 typedef struct GDBusProxy GDBusProxy;
 306
 307 GDBusProxy *g_dbus_proxy_new(GDBusClient *client, const char *path,
 308                                                         const char *interface);
 309
 310 GDBusProxy *g_dbus_proxy_ref(GDBusProxy *proxy);
 311 void g_dbus_proxy_unref(GDBusProxy *proxy);
 312
 313 const char *g_dbus_proxy_get_path(GDBusProxy *proxy);
 314 const char *g_dbus_proxy_get_interface(GDBusProxy *proxy);
 315
 316 gboolean g_dbus_proxy_get_property(GDBusProxy *proxy, const char *name,
 317                                                         DBusMessageIter *iter);
 318
 319 gboolean g_dbus_proxy_refresh_property(GDBusProxy *proxy, const char *name);
 320
 321 typedef void (* GDBusResultFunction) (const DBusError *error, void *user_data);
 322
 323 gboolean g_dbus_proxy_set_property_basic(GDBusProxy *proxy,
 324                                 const char *name, int type, const void *value,
 325                                 GDBusResultFunction function, void *user_data,
 326                                 GDBusDestroyFunction destroy);
 327
 328 typedef void (* GDBusSetupFunction) (DBusMessageIter *iter, void *user_data);
 329 typedef void (* GDBusReturnFunction) (DBusMessage *message, void *user_data);
 330
 331 gboolean g_dbus_proxy_method_call(GDBusProxy *proxy, const char *method,
 332                                 GDBusSetupFunction setup,
 333                                 GDBusReturnFunction function, void *user_data,
 334                                 GDBusDestroyFunction destroy);
 335
 336 typedef void (* GDBusProxyFunction) (GDBusProxy *proxy, void *user_data);
 337 typedef void (* GDBusPropertyFunction) (GDBusProxy *proxy, const char *name,
 338                                         DBusMessageIter *iter, void *user_data);
 339
 340 gboolean g_dbus_proxy_set_property_watch(GDBusProxy *proxy,
 341                         GDBusPropertyFunction function, void *user_data);
 342
 343 GDBusClient *g_dbus_client_new(DBusConnection *connection,
 344                                         const char *service, const char *path);
 345
 346 GDBusClient *g_dbus_client_ref(GDBusClient *client);
 347 void g_dbus_client_unref(GDBusClient *client);
 348
 349 gboolean g_dbus_client_set_connect_watch(GDBusClient *client,
 350                                 GDBusWatchFunction function, void *user_data);
 351 gboolean g_dbus_client_set_disconnect_watch(GDBusClient *client,
 352                                 GDBusWatchFunction function, void *user_data);
 353 gboolean g_dbus_client_set_signal_watch(GDBusClient *client,
 354                                 GDBusMessageFunction function, void *user_data);
 355
 356 gboolean g_dbus_client_set_proxy_handlers(GDBusClient *client,
 357                                         GDBusProxyFunction proxy_added,
 358                                         GDBusProxyFunction proxy_removed,
 359                                         GDBusPropertyFunction property_changed,
 360                                         void *user_data);
 361
 362 #ifdef __cplusplus
 363 }
 364 #endif
 365
 366 #endif /* __GDBUS_H */