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 #ifndef __G_DBUS_CONNECTION_H__
  24 #define __G_DBUS_CONNECTION_H__
  25
  26 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
  27 #error "Only <gio/gio.h> can be included directly."
  28 #endif
  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_IS_DBUS_CONNECTION(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
  37
  38 GLIB_AVAILABLE_IN_ALL
  39 GType            g_dbus_connection_get_type                   (void) G_GNUC_CONST;
  40
  41 /* ---------------------------------------------------------------------------------------------------- */
  42
  43 GLIB_AVAILABLE_IN_ALL
  44 void              g_bus_get                    (GBusType             bus_type,
  45                                                 GCancellable        *cancellable,
  46                                                 GAsyncReadyCallback  callback,
  47                                                 gpointer             user_data);
  48 GLIB_AVAILABLE_IN_ALL
  49 GDBusConnection  *g_bus_get_finish             (GAsyncResult        *res,
  50                                                 GError             **error);
  51 GLIB_AVAILABLE_IN_ALL
  52 GDBusConnection  *g_bus_get_sync               (GBusType            bus_type,
  53                                                 GCancellable       *cancellable,
  54                                                 GError            **error);
  55
  56 /* ---------------------------------------------------------------------------------------------------- */
  57
  58 GLIB_AVAILABLE_IN_ALL
  59 void             g_dbus_connection_new                        (GIOStream              *stream,
  60                                                                const gchar            *guid,
  61                                                                GDBusConnectionFlags    flags,
  62                                                                GDBusAuthObserver      *observer,
  63                                                                GCancellable           *cancellable,
  64                                                                GAsyncReadyCallback     callback,
  65                                                                gpointer                user_data);
  66 GLIB_AVAILABLE_IN_ALL
  67 GDBusConnection *g_dbus_connection_new_finish                 (GAsyncResult           *res,
  68                                                                GError                **error);
  69 GLIB_AVAILABLE_IN_ALL
  70 GDBusConnection *g_dbus_connection_new_sync                   (GIOStream              *stream,
  71                                                                const gchar            *guid,
  72                                                                GDBusConnectionFlags    flags,
  73                                                                GDBusAuthObserver      *observer,
  74                                                                GCancellable           *cancellable,
  75                                                                GError                **error);
  76
  77 GLIB_AVAILABLE_IN_ALL
  78 void             g_dbus_connection_new_for_address            (const gchar            *address,
  79                                                                GDBusConnectionFlags    flags,
  80                                                                GDBusAuthObserver      *observer,
  81                                                                GCancellable           *cancellable,
  82                                                                GAsyncReadyCallback     callback,
  83                                                                gpointer                user_data);
  84 GLIB_AVAILABLE_IN_ALL
  85 GDBusConnection *g_dbus_connection_new_for_address_finish     (GAsyncResult           *res,
  86                                                                GError                **error);
  87 GLIB_AVAILABLE_IN_ALL
  88 GDBusConnection *g_dbus_connection_new_for_address_sync       (const gchar            *address,
  89                                                                GDBusConnectionFlags    flags,
  90                                                                GDBusAuthObserver      *observer,
  91                                                                GCancellable           *cancellable,
  92                                                                GError                **error);
  93
  94 /* ---------------------------------------------------------------------------------------------------- */
  95
  96 GLIB_AVAILABLE_IN_ALL
  97 void             g_dbus_connection_start_message_processing   (GDBusConnection    *connection);
  98 GLIB_AVAILABLE_IN_ALL
  99 gboolean         g_dbus_connection_is_closed                  (GDBusConnection    *connection);
 100 GLIB_AVAILABLE_IN_ALL
 101 GIOStream       *g_dbus_connection_get_stream                 (GDBusConnection    *connection);
 102 GLIB_AVAILABLE_IN_ALL
 103 const gchar     *g_dbus_connection_get_guid                   (GDBusConnection    *connection);
 104 GLIB_AVAILABLE_IN_ALL
 105 const gchar     *g_dbus_connection_get_unique_name            (GDBusConnection    *connection);
 106 GLIB_AVAILABLE_IN_ALL
 107 GCredentials    *g_dbus_connection_get_peer_credentials       (GDBusConnection    *connection);
 108
 109 GLIB_AVAILABLE_IN_2_34
 110 guint32          g_dbus_connection_get_last_serial            (GDBusConnection    *connection);
 111
 112 GLIB_AVAILABLE_IN_ALL
 113 gboolean         g_dbus_connection_get_exit_on_close          (GDBusConnection    *connection);
 114 GLIB_AVAILABLE_IN_ALL
 115 void             g_dbus_connection_set_exit_on_close          (GDBusConnection    *connection,
 116                                                                gboolean            exit_on_close);
 117 GLIB_AVAILABLE_IN_ALL
 118 GDBusCapabilityFlags  g_dbus_connection_get_capabilities      (GDBusConnection    *connection);
 119
 120 /* ---------------------------------------------------------------------------------------------------- */
 121
 122 GLIB_AVAILABLE_IN_ALL
 123 void             g_dbus_connection_close                          (GDBusConnection     *connection,
 124                                                                    GCancellable        *cancellable,
 125                                                                    GAsyncReadyCallback  callback,
 126                                                                    gpointer             user_data);
 127 GLIB_AVAILABLE_IN_ALL
 128 gboolean         g_dbus_connection_close_finish                   (GDBusConnection     *connection,
 129                                                                    GAsyncResult        *res,
 130                                                                    GError             **error);
 131 GLIB_AVAILABLE_IN_ALL
 132 gboolean         g_dbus_connection_close_sync                     (GDBusConnection     *connection,
 133                                                                    GCancellable        *cancellable,
 134                                                                    GError             **error);
 135
 136 /* ---------------------------------------------------------------------------------------------------- */
 137
 138 GLIB_AVAILABLE_IN_ALL
 139 void             g_dbus_connection_flush                          (GDBusConnection     *connection,
 140                                                                    GCancellable        *cancellable,
 141                                                                    GAsyncReadyCallback  callback,
 142                                                                    gpointer             user_data);
 143 GLIB_AVAILABLE_IN_ALL
 144 gboolean         g_dbus_connection_flush_finish                   (GDBusConnection     *connection,
 145                                                                    GAsyncResult        *res,
 146                                                                    GError             **error);
 147 GLIB_AVAILABLE_IN_ALL
 148 gboolean         g_dbus_connection_flush_sync                     (GDBusConnection     *connection,
 149                                                                    GCancellable        *cancellable,
 150                                                                    GError             **error);
 151
 152 /* ---------------------------------------------------------------------------------------------------- */
 153
 154 GLIB_AVAILABLE_IN_ALL
 155 gboolean         g_dbus_connection_send_message                   (GDBusConnection     *connection,
 156                                                                    GDBusMessage        *message,
 157                                                                    GDBusSendMessageFlags flags,
 158                                                                    volatile guint32    *out_serial,
 159                                                                    GError             **error);
 160 GLIB_AVAILABLE_IN_ALL
 161 void             g_dbus_connection_send_message_with_reply        (GDBusConnection     *connection,
 162                                                                    GDBusMessage        *message,
 163                                                                    GDBusSendMessageFlags flags,
 164                                                                    gint                 timeout_msec,
 165                                                                    volatile guint32    *out_serial,
 166                                                                    GCancellable        *cancellable,
 167                                                                    GAsyncReadyCallback  callback,
 168                                                                    gpointer             user_data);
 169 GLIB_AVAILABLE_IN_ALL
 170 GDBusMessage    *g_dbus_connection_send_message_with_reply_finish (GDBusConnection     *connection,
 171                                                                    GAsyncResult        *res,
 172                                                                    GError             **error);
 173 GLIB_AVAILABLE_IN_ALL
 174 GDBusMessage    *g_dbus_connection_send_message_with_reply_sync   (GDBusConnection     *connection,
 175                                                                    GDBusMessage        *message,
 176                                                                    GDBusSendMessageFlags flags,
 177                                                                    gint                 timeout_msec,
 178                                                                    volatile guint32    *out_serial,
 179                                                                    GCancellable        *cancellable,
 180                                                                    GError             **error);
 181
 182 /* ---------------------------------------------------------------------------------------------------- */
 183
 184 GLIB_AVAILABLE_IN_ALL
 185 gboolean  g_dbus_connection_emit_signal                       (GDBusConnection    *connection,
 186                                                                const gchar        *destination_bus_name,
 187                                                                const gchar        *object_path,
 188                                                                const gchar        *interface_name,
 189                                                                const gchar        *signal_name,
 190                                                                GVariant           *parameters,
 191                                                                GError            **error);
 192 GLIB_AVAILABLE_IN_ALL
 193 void      g_dbus_connection_call                              (GDBusConnection    *connection,
 194                                                                const gchar        *bus_name,
 195                                                                const gchar        *object_path,
 196                                                                const gchar        *interface_name,
 197                                                                const gchar        *method_name,
 198                                                                GVariant           *parameters,
 199                                                                const GVariantType *reply_type,
 200                                                                GDBusCallFlags      flags,
 201                                                                gint                timeout_msec,
 202                                                                GCancellable       *cancellable,
 203                                                                GAsyncReadyCallback callback,
 204                                                                gpointer            user_data);
 205 GLIB_AVAILABLE_IN_ALL
 206 GVariant *g_dbus_connection_call_finish                       (GDBusConnection    *connection,
 207                                                                GAsyncResult       *res,
 208                                                                GError            **error);
 209 GLIB_AVAILABLE_IN_ALL
 210 GVariant *g_dbus_connection_call_sync                         (GDBusConnection    *connection,
 211                                                                const gchar        *bus_name,
 212                                                                const gchar        *object_path,
 213                                                                const gchar        *interface_name,
 214                                                                const gchar        *method_name,
 215                                                                GVariant           *parameters,
 216                                                                const GVariantType *reply_type,
 217                                                                GDBusCallFlags      flags,
 218                                                                gint                timeout_msec,
 219                                                                GCancellable       *cancellable,
 220                                                                GError            **error);
 221 GLIB_AVAILABLE_IN_2_30
 222 void      g_dbus_connection_call_with_unix_fd_list            (GDBusConnection    *connection,
 223                                                                const gchar        *bus_name,
 224                                                                const gchar        *object_path,
 225                                                                const gchar        *interface_name,
 226                                                                const gchar        *method_name,
 227                                                                GVariant           *parameters,
 228                                                                const GVariantType *reply_type,
 229                                                                GDBusCallFlags      flags,
 230                                                                gint                timeout_msec,
 231                                                                GUnixFDList        *fd_list,
 232                                                                GCancellable       *cancellable,
 233                                                                GAsyncReadyCallback callback,
 234                                                                gpointer            user_data);
 235 GLIB_AVAILABLE_IN_2_30
 236 GVariant *g_dbus_connection_call_with_unix_fd_list_finish     (GDBusConnection    *connection,
 237                                                                GUnixFDList       **out_fd_list,
 238                                                                GAsyncResult       *res,
 239                                                                GError            **error);
 240 GLIB_AVAILABLE_IN_2_30
 241 GVariant *g_dbus_connection_call_with_unix_fd_list_sync       (GDBusConnection    *connection,
 242                                                                const gchar        *bus_name,
 243                                                                const gchar        *object_path,
 244                                                                const gchar        *interface_name,
 245                                                                const gchar        *method_name,
 246                                                                GVariant           *parameters,
 247                                                                const GVariantType *reply_type,
 248                                                                GDBusCallFlags      flags,
 249                                                                gint                timeout_msec,
 250                                                                GUnixFDList        *fd_list,
 251                                                                GUnixFDList       **out_fd_list,
 252                                                                GCancellable       *cancellable,
 253                                                                GError            **error);
 254
 255 /* ---------------------------------------------------------------------------------------------------- */
 256
 257
 258 /**
 259  * GDBusInterfaceMethodCallFunc:
 260  * @connection: A #GDBusConnection.
 261  * @sender: The unique bus name of the remote caller.
 262  * @object_path: The object path that the method was invoked on.
 263  * @interface_name: The D-Bus interface name the method was invoked on.
 264  * @method_name: The name of the method that was invoked.
 265  * @parameters: A #GVariant tuple with parameters.
 266  * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
 267  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 268  *
 269  * The type of the @method_call function in #GDBusInterfaceVTable.
 270  *
 271  * Since: 2.26
 272  */
 273 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection       *connection,
 274                                               const gchar           *sender,
 275                                               const gchar           *object_path,
 276                                               const gchar           *interface_name,
 277                                               const gchar           *method_name,
 278                                               GVariant              *parameters,
 279                                               GDBusMethodInvocation *invocation,
 280                                               gpointer               user_data);
 281
 282 /**
 283  * GDBusInterfaceGetPropertyFunc:
 284  * @connection: A #GDBusConnection.
 285  * @sender: The unique bus name of the remote caller.
 286  * @object_path: The object path that the method was invoked on.
 287  * @interface_name: The D-Bus interface name for the property.
 288  * @property_name: The name of the property to get the value of.
 289  * @error: Return location for error.
 290  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 291  *
 292  * The type of the @get_property function in #GDBusInterfaceVTable.
 293  *
 294  * Returns: A #GVariant with the value for @property_name or %NULL if
 295  *     @error is set. If the returned #GVariant is floating, it is
 296  *     consumed - otherwise its reference count is decreased by one.
 297  *
 298  * Since: 2.26
 299  */
 300 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection       *connection,
 301                                                     const gchar           *sender,
 302                                                     const gchar           *object_path,
 303                                                     const gchar           *interface_name,
 304                                                     const gchar           *property_name,
 305                                                     GError               **error,
 306                                                     gpointer               user_data);
 307
 308 /**
 309  * GDBusInterfaceSetPropertyFunc:
 310  * @connection: A #GDBusConnection.
 311  * @sender: The unique bus name of the remote caller.
 312  * @object_path: The object path that the method was invoked on.
 313  * @interface_name: The D-Bus interface name for the property.
 314  * @property_name: The name of the property to get the value of.
 315  * @value: The value to set the property to.
 316  * @error: Return location for error.
 317  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 318  *
 319  * The type of the @set_property function in #GDBusInterfaceVTable.
 320  *
 321  * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
 322  *
 323  * Since: 2.26
 324  */
 325 typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *connection,
 326                                                     const gchar           *sender,
 327                                                     const gchar           *object_path,
 328                                                     const gchar           *interface_name,
 329                                                     const gchar           *property_name,
 330                                                     GVariant              *value,
 331                                                     GError               **error,
 332                                                     gpointer               user_data);
 333
 334 /**
 335  * GDBusInterfaceVTable:
 336  * @method_call: Function for handling incoming method calls.
 337  * @get_property: Function for getting a property.
 338  * @set_property: Function for setting a property.
 339  *
 340  * Virtual table for handling properties and method calls for a D-Bus
 341  * interface.
 342  *
 343  * Since 2.38, if you want to handle getting/setting D-Bus properties
 344  * asynchronously, give %NULL as your get_property() or set_property()
 345  * function.  The D-Bus call will be directed to your @method_call
 346  * function, with the provided @interface_name set to
 347  * <literal>"org.freedesktop.DBus.Properties"</literal>.
 348  *
 349  * The usual checks on the validity of the calls is performed.  For
 350  * <literal>'Get'</literal> calls, an error is automatically returned if
 351  * the property does not exist or the permissions do not allow access.
 352  * The same checks are performed for <literal>'Set'</literal> calls, and
 353  * the provided value is also checked for being the correct type.
 354  *
 355  * For both <literal>'Get'</literal> and <literal>'Set'</literal> calls,
 356  * the #GDBusMethodInvocation passed to the method_call handler can be
 357  * queried with g_dbus_method_invocation_get_property_info() to get a
 358  * pointer to the #GDBusPropertyInfo of the property.
 359  *
 360  * If you have readable properties specified in your interface info, you
 361  * must ensure that you either provide a non-%NULL @get_property()
 362  * function or provide implementations of both the
 363  * <literal>'Get'</literal> and <literal>'GetAll'</literal> methods on
 364  * the <literal>'org.freedesktop.DBus.Properties'</literal> interface in
 365  * your @method_call function.  Note that the required return type of
 366  * the <literal>'Get'</literal> call is <literal>(v)</literal>, not the
 367  * type of the property.  <literal>'GetAll'</literal> expects a return
 368  * value of type <literal>a{sv}</literal>.
 369  *
 370  * If you have writable properties specified in your interface info, you
 371  * must ensure that you either provide a non-%NULL @set_property()
 372  * function or provide an implementation of the <literal>'Set'</literal>
 373  * call.  If implementing the call, you must return the value of type
 374  * %G_VARIANT_TYPE_UNIT.
 375  *
 376  * Since: 2.26
 377  */
 378 struct _GDBusInterfaceVTable
 379 {
 380   GDBusInterfaceMethodCallFunc  method_call;
 381   GDBusInterfaceGetPropertyFunc get_property;
 382   GDBusInterfaceSetPropertyFunc set_property;
 383
 384   /*< private >*/
 385   /* Padding for future expansion - also remember to update
 386    * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
 387    * changing this.
 388    */
 389   gpointer padding[8];
 390 };
 391
 392 GLIB_AVAILABLE_IN_ALL
 393 guint            g_dbus_connection_register_object            (GDBusConnection            *connection,
 394                                                                const gchar                *object_path,
 395                                                                GDBusInterfaceInfo         *interface_info,
 396                                                                const GDBusInterfaceVTable *vtable,
 397                                                                gpointer                    user_data,
 398                                                                GDestroyNotify              user_data_free_func,
 399                                                                GError                    **error);
 400 GLIB_AVAILABLE_IN_ALL
 401 gboolean         g_dbus_connection_unregister_object          (GDBusConnection            *connection,
 402                                                                guint                       registration_id);
 403
 404 /* ---------------------------------------------------------------------------------------------------- */
 405
 406 /**
 407  * GDBusSubtreeEnumerateFunc:
 408  * @connection: A #GDBusConnection.
 409  * @sender: The unique bus name of the remote caller.
 410  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 411  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 412  *
 413  * The type of the @enumerate function in #GDBusSubtreeVTable.
 414  *
 415  * This function is called when generating introspection data and also
 416  * when preparing to dispatch incoming messages in the event that the
 417  * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
 418  * specified (ie: to verify that the object path is valid).
 419  *
 420  * Hierarchies are not supported; the items that you return should not
 421  * contain the '/' character.
 422  *
 423  * The return value will be freed with g_strfreev().
 424  *
 425  * Returns: A newly allocated array of strings for node names that are children of @object_path.
 426  *
 427  * Since: 2.26
 428  */
 429 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection       *connection,
 430                                               const gchar           *sender,
 431                                               const gchar           *object_path,
 432                                               gpointer               user_data);
 433
 434 /**
 435  * GDBusSubtreeIntrospectFunc:
 436  * @connection: A #GDBusConnection.
 437  * @sender: The unique bus name of the remote caller.
 438  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 439  * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
 440  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 441  *
 442  * The type of the @introspect function in #GDBusSubtreeVTable.
 443  *
 444  * Subtrees are flat.  @node, if non-%NULL, is always exactly one
 445  * segment of the object path (ie: it never contains a slash).
 446  *
 447  * This function should return %NULL to indicate that there is no object
 448  * at this node.
 449  *
 450  * If this function returns non-%NULL, the return value is expected to
 451  * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
 452  * structures describing the interfaces implemented by @node.  This
 453  * array will have g_dbus_interface_info_unref() called on each item
 454  * before being freed with g_free().
 455  *
 456  * The difference between returning %NULL and an array containing zero
 457  * items is that the standard DBus interfaces will returned to the
 458  * remote introspector in the empty array case, but not in the %NULL
 459  * case.
 460  *
 461  * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
 462  *
 463  * Since: 2.26
 464  */
 465 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection       *connection,
 466                                                              const gchar           *sender,
 467                                                              const gchar           *object_path,
 468                                                              const gchar           *node,
 469                                                              gpointer               user_data);
 470
 471 /**
 472  * GDBusSubtreeDispatchFunc:
 473  * @connection: A #GDBusConnection.
 474  * @sender: The unique bus name of the remote caller.
 475  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 476  * @interface_name: The D-Bus interface name that the method call or property access is for.
 477  * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
 478  * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
 479  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 480  *
 481  * The type of the @dispatch function in #GDBusSubtreeVTable.
 482  *
 483  * Subtrees are flat.  @node, if non-%NULL, is always exactly one
 484  * segment of the object path (ie: it never contains a slash).
 485  *
 486  * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
 487  *
 488  * Since: 2.26
 489  */
 490 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection             *connection,
 491                                                                   const gchar                 *sender,
 492                                                                   const gchar                 *object_path,
 493                                                                   const gchar                 *interface_name,
 494                                                                   const gchar                 *node,
 495                                                                   gpointer                    *out_user_data,
 496                                                                   gpointer                     user_data);
 497
 498 /**
 499  * GDBusSubtreeVTable:
 500  * @enumerate: Function for enumerating child nodes.
 501  * @introspect: Function for introspecting a child node.
 502  * @dispatch: Function for dispatching a remote call on a child node.
 503  *
 504  * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
 505  *
 506  * Since: 2.26
 507  */
 508 struct _GDBusSubtreeVTable
 509 {
 510   GDBusSubtreeEnumerateFunc  enumerate;
 511   GDBusSubtreeIntrospectFunc introspect;
 512   GDBusSubtreeDispatchFunc   dispatch;
 513
 514   /*< private >*/
 515   /* Padding for future expansion - also remember to update
 516    * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
 517    * changing this.
 518    */
 519   gpointer padding[8];
 520 };
 521
 522 GLIB_AVAILABLE_IN_ALL
 523 guint            g_dbus_connection_register_subtree           (GDBusConnection            *connection,
 524                                                                const gchar                *object_path,
 525                                                                const GDBusSubtreeVTable   *vtable,
 526                                                                GDBusSubtreeFlags           flags,
 527                                                                gpointer                    user_data,
 528                                                                GDestroyNotify              user_data_free_func,
 529                                                                GError                    **error);
 530 GLIB_AVAILABLE_IN_ALL
 531 gboolean         g_dbus_connection_unregister_subtree         (GDBusConnection            *connection,
 532                                                                guint                       registration_id);
 533
 534 /* ---------------------------------------------------------------------------------------------------- */
 535
 536 /**
 537  * GDBusSignalCallback:
 538  * @connection: A #GDBusConnection.
 539  * @sender_name: The unique bus name of the sender of the signal.
 540  * @object_path: The object path that the signal was emitted on.
 541  * @interface_name: The name of the interface.
 542  * @signal_name: The name of the signal.
 543  * @parameters: A #GVariant tuple with parameters for the signal.
 544  * @user_data: User data passed when subscribing to the signal.
 545  *
 546  * Signature for callback function used in g_dbus_connection_signal_subscribe().
 547  *
 548  * Since: 2.26
 549  */
 550 typedef void (*GDBusSignalCallback) (GDBusConnection  *connection,
 551                                      const gchar      *sender_name,
 552                                      const gchar      *object_path,
 553                                      const gchar      *interface_name,
 554                                      const gchar      *signal_name,
 555                                      GVariant         *parameters,
 556                                      gpointer          user_data);
 557
 558 GLIB_AVAILABLE_IN_ALL
 559 guint            g_dbus_connection_signal_subscribe           (GDBusConnection     *connection,
 560                                                                const gchar         *sender,
 561                                                                const gchar         *interface_name,
 562                                                                const gchar         *member,
 563                                                                const gchar         *object_path,
 564                                                                const gchar         *arg0,
 565                                                                GDBusSignalFlags     flags,
 566                                                                GDBusSignalCallback  callback,
 567                                                                gpointer             user_data,
 568                                                                GDestroyNotify       user_data_free_func);
 569 GLIB_AVAILABLE_IN_ALL
 570 void             g_dbus_connection_signal_unsubscribe         (GDBusConnection     *connection,
 571                                                                guint                subscription_id);
 572
 573 /* ---------------------------------------------------------------------------------------------------- */
 574
 575 /**
 576  * GDBusMessageFilterFunction:
 577  * @connection: (transfer none): A #GDBusConnection.
 578  * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
 579  * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
 580  * a message to be sent to the other peer.
 581  * @user_data: User data passed when adding the filter.
 582  *
 583  * Signature for function used in g_dbus_connection_add_filter().
 584  *
 585  * A filter function is passed a #GDBusMessage and expected to return
 586  * a #GDBusMessage too. Passive filter functions that don't modify the
 587  * message can simply return the @message object:
 588  * |[
 589  * static GDBusMessage *
 590  * passive_filter (GDBusConnection *connection
 591  *                 GDBusMessage    *message,
 592  *                 gboolean         incoming,
 593  *                 gpointer         user_data)
 594  * {
 595  *   /<!-- -->* inspect @message *<!-- -->/
 596  *   return message;
 597  * }
 598  * ]|
 599  * Filter functions that wants to drop a message can simply return %NULL:
 600  * |[
 601  * static GDBusMessage *
 602  * drop_filter (GDBusConnection *connection
 603  *              GDBusMessage    *message,
 604  *              gboolean         incoming,
 605  *              gpointer         user_data)
 606  * {
 607  *   if (should_drop_message)
 608  *     {
 609  *       g_object_unref (message);
 610  *       message = NULL;
 611  *     }
 612  *   return message;
 613  * }
 614  * ]|
 615  * Finally, a filter function may modify a message by copying it:
 616  * |[
 617  * static GDBusMessage *
 618  * modifying_filter (GDBusConnection *connection
 619  *                   GDBusMessage    *message,
 620  *                   gboolean         incoming,
 621  *                   gpointer         user_data)
 622  * {
 623  *   GDBusMessage *copy;
 624  *   GError *error;
 625  *
 626  *   error = NULL;
 627  *   copy = g_dbus_message_copy (message, &error);
 628  *   /<!-- -->* handle @error being is set *<!-- -->/
 629  *   g_object_unref (message);
 630  *
 631  *   /<!-- -->* modify @copy *<!-- -->/
 632  *
 633  *   return copy;
 634  * }
 635  * ]|
 636  * If the returned #GDBusMessage is different from @message and cannot
 637  * be sent on @connection (it could use features, such as file
 638  * descriptors, not compatible with @connection), then a warning is
 639  * logged to <emphasis>standard error</emphasis>. Applications can
 640  * check this ahead of time using g_dbus_message_to_blob() passing a
 641  * #GDBusCapabilityFlags value obtained from @connection.
 642  *
 643  * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
 644  * g_object_unref() or %NULL to drop the message. Passive filter
 645  * functions can simply return the passed @message object.
 646  *
 647  * Since: 2.26
 648  */
 649 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
 650                                                      GDBusMessage    *message,
 651                                                      gboolean         incoming,
 652                                                      gpointer         user_data);
 653
 654 GLIB_AVAILABLE_IN_ALL
 655 guint g_dbus_connection_add_filter (GDBusConnection            *connection,
 656                                     GDBusMessageFilterFunction  filter_function,
 657                                     gpointer                    user_data,
 658                                     GDestroyNotify              user_data_free_func);
 659
 660 GLIB_AVAILABLE_IN_ALL
 661 void  g_dbus_connection_remove_filter (GDBusConnection    *connection,
 662                                        guint               filter_id);
 663
 664 /* ---------------------------------------------------------------------------------------------------- */
 665
 666
 667 G_END_DECLS
 668
 669 #endif /* __G_DBUS_CONNECTION_H__ */