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