gio/gdbusconnection.h

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