gio/gdbusconnection.h

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