gio/gdbusconnection.h

   1 /* GDBus - GLib D-Bus Library
   2  *
   3  * Copyright (C) 2008-2010 Red Hat, Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: David Zeuthen <davidz@redhat.com>
  21  */
  22
  23 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
  24 #error "Only <gio/gio.h> can be included directly."
  25 #endif
  26
  27 #ifndef __G_DBUS_CONNECTION_H__
  28 #define __G_DBUS_CONNECTION_H__
  29
  30 #include <gio/giotypes.h>
  31
  32 G_BEGIN_DECLS
  33
  34 #define G_TYPE_DBUS_CONNECTION         (g_dbus_connection_get_type ())
  35 #define G_DBUS_CONNECTION(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
  36 #define G_DBUS_CONNECTION_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST((k), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
  37 #define G_DBUS_CONNECTION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
  38 #define G_IS_DBUS_CONNECTION(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
  39 #define G_IS_DBUS_CONNECTION_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DBUS_CONNECTION))
  40
  41 typedef struct _GDBusConnectionClass   GDBusConnectionClass;
  42 typedef struct _GDBusConnectionPrivate GDBusConnectionPrivate;
  43
  44 /**
  45  * GDBusConnection:
  46  *
  47  * The #GDBusConnection structure contains only private data and
  48  * should only be accessed using the provided API.
  49  *
  50  * Since: 2.26
  51  */
  52 struct _GDBusConnection
  53 {
  54   /*< private >*/
  55   GObject parent_instance;
  56   GDBusConnectionPrivate *priv;
  57 };
  58
  59 /**
  60  * GDBusConnectionClass:
  61  * @closed: Signal class handler for the #GDBusConnection::closed signal.
  62  *
  63  * Class structure for #GDBusConnection.
  64  *
  65  * Since: 2.26
  66  */
  67 struct _GDBusConnectionClass
  68 {
  69   /*< private >*/
  70   GObjectClass parent_class;
  71
  72   /*< public >*/
  73   /* Signals */
  74   void (*closed) (GDBusConnection *connection,
  75                   gboolean         remote_peer_vanished,
  76                   GError          *error);
  77
  78   /*< private >*/
  79   /* Padding for future expansion */
  80   gpointer padding[64];
  81 };
  82
  83 GType            g_dbus_connection_get_type                   (void) G_GNUC_CONST;
  84
  85 /* ---------------------------------------------------------------------------------------------------- */
  86
  87 void              g_bus_get                    (GBusType             bus_type,
  88                                                 GCancellable        *cancellable,
  89                                                 GAsyncReadyCallback  callback,
  90                                                 gpointer             user_data);
  91 GDBusConnection  *g_bus_get_finish             (GAsyncResult        *res,
  92                                                 GError             **error);
  93 GDBusConnection  *g_bus_get_sync               (GBusType            bus_type,
  94                                                 GCancellable       *cancellable,
  95                                                 GError            **error);
  96
  97 /* ---------------------------------------------------------------------------------------------------- */
  98
  99 void             g_dbus_connection_new                        (GIOStream              *stream,
 100                                                                const gchar            *guid,
 101                                                                GDBusConnectionFlags    flags,
 102                                                                GDBusAuthObserver      *observer,
 103                                                                GCancellable           *cancellable,
 104                                                                GAsyncReadyCallback     callback,
 105                                                                gpointer                user_data);
 106 GDBusConnection *g_dbus_connection_new_finish                 (GAsyncResult           *res,
 107                                                                GError                **error);
 108 GDBusConnection *g_dbus_connection_new_sync                   (GIOStream              *stream,
 109                                                                const gchar            *guid,
 110                                                                GDBusConnectionFlags    flags,
 111                                                                GDBusAuthObserver      *observer,
 112                                                                GCancellable           *cancellable,
 113                                                                GError                **error);
 114
 115 void             g_dbus_connection_new_for_address            (const gchar            *address,
 116                                                                GDBusConnectionFlags    flags,
 117                                                                GDBusAuthObserver      *observer,
 118                                                                GCancellable           *cancellable,
 119                                                                GAsyncReadyCallback     callback,
 120                                                                gpointer                user_data);
 121 GDBusConnection *g_dbus_connection_new_for_address_finish     (GAsyncResult           *res,
 122                                                                GError                **error);
 123 GDBusConnection *g_dbus_connection_new_for_address_sync       (const gchar            *address,
 124                                                                GDBusConnectionFlags    flags,
 125                                                                GDBusAuthObserver      *observer,
 126                                                                GCancellable           *cancellable,
 127                                                                GError                **error);
 128
 129 /* ---------------------------------------------------------------------------------------------------- */
 130
 131 void             g_dbus_connection_start_message_processing   (GDBusConnection    *connection);
 132 gboolean         g_dbus_connection_is_closed                  (GDBusConnection    *connection);
 133 void             g_dbus_connection_close                      (GDBusConnection    *connection);
 134 GIOStream       *g_dbus_connection_get_stream                 (GDBusConnection    *connection);
 135 const gchar     *g_dbus_connection_get_guid                   (GDBusConnection    *connection);
 136 const gchar     *g_dbus_connection_get_unique_name            (GDBusConnection    *connection);
 137 GCredentials    *g_dbus_connection_get_peer_credentials       (GDBusConnection    *connection);
 138 gboolean         g_dbus_connection_get_exit_on_close          (GDBusConnection    *connection);
 139 void             g_dbus_connection_set_exit_on_close          (GDBusConnection    *connection,
 140                                                                gboolean            exit_on_close);
 141 GDBusCapabilityFlags  g_dbus_connection_get_capabilities      (GDBusConnection    *connection);
 142
 143 /* ---------------------------------------------------------------------------------------------------- */
 144
 145 void             g_dbus_connection_flush                          (GDBusConnection     *connection,
 146                                                                    GCancellable        *cancellable,
 147                                                                    GAsyncReadyCallback  callback,
 148                                                                    gpointer             user_data);
 149 gboolean         g_dbus_connection_flush_finish                   (GDBusConnection     *connection,
 150                                                                    GAsyncResult        *res,
 151                                                                    GError             **error);
 152 gboolean         g_dbus_connection_flush_sync                     (GDBusConnection     *connection,
 153                                                                    GCancellable        *cancellable,
 154                                                                    GError             **error);
 155
 156 /* ---------------------------------------------------------------------------------------------------- */
 157
 158 gboolean         g_dbus_connection_send_message                   (GDBusConnection     *connection,
 159                                                                    GDBusMessage        *message,
 160                                                                    volatile guint32    *out_serial,
 161                                                                    GError             **error);
 162 void             g_dbus_connection_send_message_with_reply        (GDBusConnection     *connection,
 163                                                                    GDBusMessage        *message,
 164                                                                    gint                 timeout_msec,
 165                                                                    volatile guint32    *out_serial,
 166                                                                    GCancellable        *cancellable,
 167                                                                    GAsyncReadyCallback  callback,
 168                                                                    gpointer             user_data);
 169 GDBusMessage    *g_dbus_connection_send_message_with_reply_finish (GDBusConnection     *connection,
 170                                                                    GAsyncResult        *res,
 171                                                                    GError             **error);
 172 GDBusMessage    *g_dbus_connection_send_message_with_reply_sync   (GDBusConnection     *connection,
 173                                                                    GDBusMessage        *message,
 174                                                                    gint                 timeout_msec,
 175                                                                    volatile guint32    *out_serial,
 176                                                                    GCancellable        *cancellable,
 177                                                                    GError             **error);
 178
 179 /* ---------------------------------------------------------------------------------------------------- */
 180
 181 gboolean  g_dbus_connection_emit_signal                       (GDBusConnection    *connection,
 182                                                                const gchar        *destination_bus_name,
 183                                                                const gchar        *object_path,
 184                                                                const gchar        *interface_name,
 185                                                                const gchar        *signal_name,
 186                                                                GVariant           *parameters,
 187                                                                GError            **error);
 188 void      g_dbus_connection_call                              (GDBusConnection    *connection,
 189                                                                const gchar        *bus_name,
 190                                                                const gchar        *object_path,
 191                                                                const gchar        *interface_name,
 192                                                                const gchar        *method_name,
 193                                                                GVariant           *parameters,
 194                                                                const GVariantType *reply_type,
 195                                                                GDBusCallFlags      flags,
 196                                                                gint                timeout_msec,
 197                                                                GCancellable       *cancellable,
 198                                                                GAsyncReadyCallback callback,
 199                                                                gpointer            user_data);
 200 GVariant *g_dbus_connection_call_finish                       (GDBusConnection    *connection,
 201                                                                GAsyncResult       *res,
 202                                                                GError            **error);
 203 GVariant *g_dbus_connection_call_sync                         (GDBusConnection    *connection,
 204                                                                const gchar        *bus_name,
 205                                                                const gchar        *object_path,
 206                                                                const gchar        *interface_name,
 207                                                                const gchar        *method_name,
 208                                                                GVariant           *parameters,
 209                                                                const GVariantType *reply_type,
 210                                                                GDBusCallFlags      flags,
 211                                                                gint                timeout_msec,
 212                                                                GCancellable       *cancellable,
 213                                                                GError            **error);
 214
 215 /* ---------------------------------------------------------------------------------------------------- */
 216
 217
 218 /**
 219  * GDBusInterfaceMethodCallFunc:
 220  * @connection: A #GDBusConnection.
 221  * @sender: The unique bus name of the remote caller.
 222  * @object_path: The object path that the method was invoked on.
 223  * @interface_name: The D-Bus interface name the method was invoked on.
 224  * @method_name: The name of the method that was invoked.
 225  * @parameters: A #GVariant tuple with parameters.
 226  * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
 227  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 228  *
 229  * The type of the @method_call function in #GDBusInterfaceVTable.
 230  *
 231  * Since: 2.26
 232  */
 233 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection       *connection,
 234                                               const gchar           *sender,
 235                                               const gchar           *object_path,
 236                                               const gchar           *interface_name,
 237                                               const gchar           *method_name,
 238                                               GVariant              *parameters,
 239                                               GDBusMethodInvocation *invocation,
 240                                               gpointer               user_data);
 241
 242 /**
 243  * GDBusInterfaceGetPropertyFunc:
 244  * @connection: A #GDBusConnection.
 245  * @sender: The unique bus name of the remote caller.
 246  * @object_path: The object path that the method was invoked on.
 247  * @interface_name: The D-Bus interface name for the property.
 248  * @property_name: The name of the property to get the value of.
 249  * @error: Return location for error.
 250  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 251  *
 252  * The type of the @get_property function in #GDBusInterfaceVTable.
 253  *
 254  * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
 255  *
 256  * Since: 2.26
 257  */
 258 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection       *connection,
 259                                                     const gchar           *sender,
 260                                                     const gchar           *object_path,
 261                                                     const gchar           *interface_name,
 262                                                     const gchar           *property_name,
 263                                                     GError               **error,
 264                                                     gpointer               user_data);
 265
 266 /**
 267  * GDBusInterfaceSetPropertyFunc:
 268  * @connection: A #GDBusConnection.
 269  * @sender: The unique bus name of the remote caller.
 270  * @object_path: The object path that the method was invoked on.
 271  * @interface_name: The D-Bus interface name for the property.
 272  * @property_name: The name of the property to get the value of.
 273  * @value: The value to set the property to.
 274  * @error: Return location for error.
 275  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 276  *
 277  * The type of the @set_property function in #GDBusInterfaceVTable.
 278  *
 279  * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
 280  *
 281  * Since: 2.26
 282  */
 283 typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *connection,
 284                                                     const gchar           *sender,
 285                                                     const gchar           *object_path,
 286                                                     const gchar           *interface_name,
 287                                                     const gchar           *property_name,
 288                                                     GVariant              *value,
 289                                                     GError               **error,
 290                                                     gpointer               user_data);
 291
 292 /**
 293  * GDBusInterfaceVTable:
 294  * @method_call: Function for handling incoming method calls.
 295  * @get_property: Function for getting a property.
 296  * @set_property: Function for setting a property.
 297  *
 298  * Virtual table for handling properties and method calls for a D-Bus
 299  * interface.
 300  *
 301  * If you want to handle getting/setting D-Bus properties asynchronously, simply
 302  * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
 303  * D-Bus interface using g_dbus_connection_register_object().
 304  *
 305  * Since: 2.26
 306  */
 307 struct _GDBusInterfaceVTable
 308 {
 309   GDBusInterfaceMethodCallFunc  method_call;
 310   GDBusInterfaceGetPropertyFunc get_property;
 311   GDBusInterfaceSetPropertyFunc set_property;
 312
 313   /*< private >*/
 314   /* Padding for future expansion */
 315   gpointer padding[8];
 316 };
 317
 318 guint            g_dbus_connection_register_object            (GDBusConnection            *connection,
 319                                                                const gchar                *object_path,
 320                                                                const GDBusInterfaceInfo   *interface_info,
 321                                                                const GDBusInterfaceVTable *vtable,
 322                                                                gpointer                    user_data,
 323                                                                GDestroyNotify              user_data_free_func,
 324                                                                GError                    **error);
 325 gboolean         g_dbus_connection_unregister_object          (GDBusConnection            *connection,
 326                                                                guint                       registration_id);
 327
 328 /* ---------------------------------------------------------------------------------------------------- */
 329
 330 /**
 331  * GDBusSubtreeEnumerateFunc:
 332  * @connection: A #GDBusConnection.
 333  * @sender: The unique bus name of the remote caller.
 334  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 335  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 336  *
 337  * The type of the @enumerate function in #GDBusSubtreeVTable.
 338  *
 339  * Returns: A newly allocated array of strings for node names that are children of @object_path.
 340  *
 341  * Since: 2.26
 342  */
 343 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection       *connection,
 344                                               const gchar           *sender,
 345                                               const gchar           *object_path,
 346                                               gpointer               user_data);
 347
 348 /**
 349  * GDBusSubtreeIntrospectFunc:
 350  * @connection: A #GDBusConnection.
 351  * @sender: The unique bus name of the remote caller.
 352  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 353  * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
 354  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 355  *
 356  * The type of the @introspect function in #GDBusSubtreeVTable.
 357  *
 358  * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
 359  * the interfaces implemented by @node.
 360  *
 361  * Since: 2.26
 362  */
 363 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection       *connection,
 364                                                   const gchar           *sender,
 365                                                   const gchar           *object_path,
 366                                                   const gchar           *node,
 367                                                   gpointer               user_data);
 368
 369 /**
 370  * GDBusSubtreeDispatchFunc:
 371  * @connection: A #GDBusConnection.
 372  * @sender: The unique bus name of the remote caller.
 373  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 374  * @interface_name: The D-Bus interface name that the method call or property access is for.
 375  * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
 376  * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
 377  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 378  *
 379  * The type of the @dispatch function in #GDBusSubtreeVTable.
 380  *
 381  * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
 382  *
 383  * Since: 2.26
 384  */
 385 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection             *connection,
 386                                                                   const gchar                 *sender,
 387                                                                   const gchar                 *object_path,
 388                                                                   const gchar                 *interface_name,
 389                                                                   const gchar                 *node,
 390                                                                   gpointer                    *out_user_data,
 391                                                                   gpointer                     user_data);
 392
 393 /**
 394  * GDBusSubtreeVTable:
 395  * @enumerate: Function for enumerating child nodes.
 396  * @introspect: Function for introspecting a child node.
 397  * @dispatch: Function for dispatching a remote call on a child node.
 398  *
 399  * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
 400  *
 401  * Since: 2.26
 402  */
 403 struct _GDBusSubtreeVTable
 404 {
 405   GDBusSubtreeEnumerateFunc  enumerate;
 406   GDBusSubtreeIntrospectFunc introspect;
 407   GDBusSubtreeDispatchFunc   dispatch;
 408
 409   /*< private >*/
 410   /* Padding for future expansion */
 411   void (*_g_reserved1) (void);
 412   void (*_g_reserved2) (void);
 413   void (*_g_reserved3) (void);
 414   void (*_g_reserved4) (void);
 415   void (*_g_reserved5) (void);
 416   void (*_g_reserved6) (void);
 417   void (*_g_reserved7) (void);
 418   void (*_g_reserved8) (void);
 419 };
 420
 421 guint            g_dbus_connection_register_subtree           (GDBusConnection            *connection,
 422                                                                const gchar                *object_path,
 423                                                                const GDBusSubtreeVTable   *vtable,
 424                                                                GDBusSubtreeFlags           flags,
 425                                                                gpointer                    user_data,
 426                                                                GDestroyNotify              user_data_free_func,
 427                                                                GError                    **error);
 428 gboolean         g_dbus_connection_unregister_subtree         (GDBusConnection            *connection,
 429                                                                guint                       registration_id);
 430
 431 /* ---------------------------------------------------------------------------------------------------- */
 432
 433 /**
 434  * GDBusSignalCallback:
 435  * @connection: A #GDBusConnection.
 436  * @sender_name: The unique bus name of the sender of the signal.
 437  * @object_path: The object path that the signal was emitted on.
 438  * @interface_name: The name of the interface.
 439  * @signal_name: The name of the signal.
 440  * @parameters: A #GVariant tuple with parameters for the signal.
 441  * @user_data: User data passed when subscribing to the signal.
 442  *
 443  * Signature for callback function used in g_dbus_connection_signal_subscribe().
 444  *
 445  * Since: 2.26
 446  */
 447 typedef void (*GDBusSignalCallback) (GDBusConnection  *connection,
 448                                      const gchar      *sender_name,
 449                                      const gchar      *object_path,
 450                                      const gchar      *interface_name,
 451                                      const gchar      *signal_name,
 452                                      GVariant         *parameters,
 453                                      gpointer          user_data);
 454
 455 guint            g_dbus_connection_signal_subscribe           (GDBusConnection     *connection,
 456                                                                const gchar         *sender,
 457                                                                const gchar         *interface_name,
 458                                                                const gchar         *member,
 459                                                                const gchar         *object_path,
 460                                                                const gchar         *arg0,
 461                                                                GDBusSignalCallback  callback,
 462                                                                gpointer             user_data,
 463                                                                GDestroyNotify       user_data_free_func);
 464 void             g_dbus_connection_signal_unsubscribe         (GDBusConnection     *connection,
 465                                                                guint                subscription_id);
 466
 467 /* ---------------------------------------------------------------------------------------------------- */
 468
 469 /**
 470  * GDBusMessageFilterFunction:
 471  * @connection: A #GDBusConnection.
 472  * @message: A #GDBusMessage.
 473  * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
 474  * a message to be sent to the other peer.
 475  * @user_data: User data passed when adding the filter.
 476  *
 477  * Signature for function used in g_dbus_connection_add_filter().
 478  *
 479  * Returns: %TRUE if the filter handled @message, %FALSE to let other
 480  * handlers run.
 481  *
 482  * Since: 2.26
 483  */
 484 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
 485                                                 GDBusMessage    *message,
 486                                                 gboolean         incoming,
 487                                                 gpointer         user_data);
 488
 489 guint g_dbus_connection_add_filter (GDBusConnection            *connection,
 490                                     GDBusMessageFilterFunction  filter_function,
 491                                     gpointer                    user_data,
 492                                     GDestroyNotify              user_data_free_func);
 493
 494 void  g_dbus_connection_remove_filter (GDBusConnection    *connection,
 495                                        guint               filter_id);
 496
 497 /* ---------------------------------------------------------------------------------------------------- */
 498
 499
 500 G_END_DECLS
 501
 502 #endif /* __G_DBUS_CONNECTION_H__ */