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