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 #include <gio/giotypes.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define G_TYPE_DBUS_CONNECTION         (g_dbus_connection_get_type ())
  31 #define G_DBUS_CONNECTION(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
  32 #define G_DBUS_CONNECTION_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST((k), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
  33 #define G_DBUS_CONNECTION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
  34 #define G_IS_DBUS_CONNECTION(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
  35 #define G_IS_DBUS_CONNECTION_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DBUS_CONNECTION))
  36
  37 typedef struct _GDBusConnectionClass   GDBusConnectionClass;
  38 typedef struct _GDBusConnectionPrivate GDBusConnectionPrivate;
  39
  40 /**
  41  * GDBusConnection:
  42  *
  43  * The #GDBusConnection structure contains only private data and
  44  * should only be accessed using the provided API.
  45  *
  46  * Since: 2.26
  47  */
  48 struct _GDBusConnection
  49 {
  50   /*< private >*/
  51   GObject parent_instance;
  52   GDBusConnectionPrivate *priv;
  53 };
  54
  55 /**
  56  * GDBusConnectionClass:
  57  * @closed: Signal class handler for the #GDBusConnection::closed signal.
  58  *
  59  * Class structure for #GDBusConnection.
  60  *
  61  * Since: 2.26
  62  */
  63 struct _GDBusConnectionClass
  64 {
  65   /*< private >*/
  66   GObjectClass parent_class;
  67
  68   /*< public >*/
  69   /* Signals */
  70   void (*closed) (GDBusConnection *connection,
  71                   gboolean         remote_peer_vanished,
  72                   GError          *error);
  73
  74   /*< private >*/
  75   /* Padding for future expansion */
  76   void (*_g_reserved1) (void);
  77   void (*_g_reserved2) (void);
  78   void (*_g_reserved3) (void);
  79   void (*_g_reserved4) (void);
  80   void (*_g_reserved5) (void);
  81   void (*_g_reserved6) (void);
  82   void (*_g_reserved7) (void);
  83   void (*_g_reserved8) (void);
  84 };
  85
  86 GType            g_dbus_connection_get_type                   (void) G_GNUC_CONST;
  87
  88 /* ---------------------------------------------------------------------------------------------------- */
  89
  90 void              g_bus_get                    (GBusType             bus_type,
  91                                                 GCancellable        *cancellable,
  92                                                 GAsyncReadyCallback  callback,
  93                                                 gpointer             user_data);
  94 GDBusConnection  *g_bus_get_finish             (GAsyncResult        *res,
  95                                                 GError             **error);
  96 GDBusConnection  *g_bus_get_sync               (GBusType            bus_type,
  97                                                 GCancellable       *cancellable,
  98                                                 GError            **error);
  99
 100 /* ---------------------------------------------------------------------------------------------------- */
 101
 102 void             g_dbus_connection_new                        (GIOStream              *stream,
 103                                                                const gchar            *guid,
 104                                                                GDBusConnectionFlags    flags,
 105                                                                GDBusAuthObserver      *observer,
 106                                                                GCancellable           *cancellable,
 107                                                                GAsyncReadyCallback     callback,
 108                                                                gpointer                user_data);
 109 GDBusConnection *g_dbus_connection_new_finish                 (GAsyncResult           *res,
 110                                                                GError                **error);
 111 GDBusConnection *g_dbus_connection_new_sync                   (GIOStream              *stream,
 112                                                                const gchar            *guid,
 113                                                                GDBusConnectionFlags    flags,
 114                                                                GDBusAuthObserver      *observer,
 115                                                                GCancellable           *cancellable,
 116                                                                GError                **error);
 117
 118 void             g_dbus_connection_new_for_address            (const gchar            *address,
 119                                                                GDBusConnectionFlags    flags,
 120                                                                GDBusAuthObserver      *observer,
 121                                                                GCancellable           *cancellable,
 122                                                                GAsyncReadyCallback     callback,
 123                                                                gpointer                user_data);
 124 GDBusConnection *g_dbus_connection_new_for_address_finish     (GAsyncResult           *res,
 125                                                                GError                **error);
 126 GDBusConnection *g_dbus_connection_new_for_address_sync       (const gchar            *address,
 127                                                                GDBusConnectionFlags    flags,
 128                                                                GDBusAuthObserver      *observer,
 129                                                                GCancellable           *cancellable,
 130                                                                GError                **error);
 131
 132 /* ---------------------------------------------------------------------------------------------------- */
 133
 134 gboolean         g_dbus_connection_is_closed                  (GDBusConnection    *connection);
 135 void             g_dbus_connection_close                      (GDBusConnection    *connection);
 136 GIOStream       *g_dbus_connection_get_stream                 (GDBusConnection    *connection);
 137 const gchar     *g_dbus_connection_get_guid                   (GDBusConnection    *connection);
 138 const gchar     *g_dbus_connection_get_unique_name            (GDBusConnection    *connection);
 139 GCredentials    *g_dbus_connection_get_peer_credentials       (GDBusConnection    *connection);
 140 gboolean         g_dbus_connection_get_exit_on_close          (GDBusConnection    *connection);
 141 void             g_dbus_connection_set_exit_on_close          (GDBusConnection    *connection,
 142                                                                gboolean            exit_on_close);
 143 GDBusCapabilityFlags  g_dbus_connection_get_capabilities      (GDBusConnection    *connection);
 144 /* ---------------------------------------------------------------------------------------------------- */
 145
 146 gboolean         g_dbus_connection_send_message                   (GDBusConnection     *connection,
 147                                                                    GDBusMessage        *message,
 148                                                                    volatile guint32    *out_serial,
 149                                                                    GError             **error);
 150 void             g_dbus_connection_send_message_with_reply        (GDBusConnection     *connection,
 151                                                                    GDBusMessage        *message,
 152                                                                    gint                 timeout_msec,
 153                                                                    volatile guint32    *out_serial,
 154                                                                    GCancellable        *cancellable,
 155                                                                    GAsyncReadyCallback  callback,
 156                                                                    gpointer             user_data);
 157 GDBusMessage    *g_dbus_connection_send_message_with_reply_finish (GDBusConnection     *connection,
 158                                                                    GAsyncResult        *res,
 159                                                                    GError             **error);
 160 GDBusMessage    *g_dbus_connection_send_message_with_reply_sync   (GDBusConnection     *connection,
 161                                                                    GDBusMessage        *message,
 162                                                                    gint                 timeout_msec,
 163                                                                    volatile guint32    *out_serial,
 164                                                                    GCancellable        *cancellable,
 165                                                                    GError             **error);
 166
 167 /* ---------------------------------------------------------------------------------------------------- */
 168
 169 gboolean  g_dbus_connection_emit_signal                       (GDBusConnection    *connection,
 170                                                                const gchar        *destination_bus_name,
 171                                                                const gchar        *object_path,
 172                                                                const gchar        *interface_name,
 173                                                                const gchar        *signal_name,
 174                                                                GVariant           *parameters,
 175                                                                GError            **error);
 176 void      g_dbus_connection_call                              (GDBusConnection    *connection,
 177                                                                const gchar        *bus_name,
 178                                                                const gchar        *object_path,
 179                                                                const gchar        *interface_name,
 180                                                                const gchar        *method_name,
 181                                                                GVariant           *parameters,
 182                                                                GDBusCallFlags      flags,
 183                                                                gint                timeout_msec,
 184                                                                GCancellable       *cancellable,
 185                                                                GAsyncReadyCallback callback,
 186                                                                gpointer            user_data);
 187 GVariant *g_dbus_connection_call_finish                       (GDBusConnection    *connection,
 188                                                                GAsyncResult       *res,
 189                                                                GError            **error);
 190 GVariant *g_dbus_connection_call_sync                         (GDBusConnection    *connection,
 191                                                                const gchar        *bus_name,
 192                                                                const gchar        *object_path,
 193                                                                const gchar        *interface_name,
 194                                                                const gchar        *method_name,
 195                                                                GVariant           *parameters,
 196                                                                GDBusCallFlags      flags,
 197                                                                gint                timeout_msec,
 198                                                                GCancellable       *cancellable,
 199                                                                GError            **error);
 200
 201 /* ---------------------------------------------------------------------------------------------------- */
 202
 203
 204 /**
 205  * GDBusInterfaceMethodCallFunc:
 206  * @connection: A #GDBusConnection.
 207  * @sender: The unique bus name of the remote caller.
 208  * @object_path: The object path that the method was invoked on.
 209  * @interface_name: The D-Bus interface name the method was invoked on.
 210  * @method_name: The name of the method that was invoked.
 211  * @parameters: A #GVariant tuple with parameters.
 212  * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
 213  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 214  *
 215  * The type of the @method_call function in #GDBusInterfaceVTable.
 216  *
 217  * Since: 2.26
 218  */
 219 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection       *connection,
 220                                               const gchar           *sender,
 221                                               const gchar           *object_path,
 222                                               const gchar           *interface_name,
 223                                               const gchar           *method_name,
 224                                               GVariant              *parameters,
 225                                               GDBusMethodInvocation *invocation,
 226                                               gpointer               user_data);
 227
 228 /**
 229  * GDBusInterfaceGetPropertyFunc:
 230  * @connection: A #GDBusConnection.
 231  * @sender: The unique bus name of the remote caller.
 232  * @object_path: The object path that the method was invoked on.
 233  * @interface_name: The D-Bus interface name for the property.
 234  * @property_name: The name of the property to get the value of.
 235  * @error: Return location for error.
 236  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 237  *
 238  * The type of the @get_property function in #GDBusInterfaceVTable.
 239  *
 240  * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
 241  *
 242  * Since: 2.26
 243  */
 244 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection       *connection,
 245                                                     const gchar           *sender,
 246                                                     const gchar           *object_path,
 247                                                     const gchar           *interface_name,
 248                                                     const gchar           *property_name,
 249                                                     GError               **error,
 250                                                     gpointer               user_data);
 251
 252 /**
 253  * GDBusInterfaceSetPropertyFunc:
 254  * @connection: A #GDBusConnection.
 255  * @sender: The unique bus name of the remote caller.
 256  * @object_path: The object path that the method was invoked on.
 257  * @interface_name: The D-Bus interface name for the property.
 258  * @property_name: The name of the property to get the value of.
 259  * @value: The value to set the property to.
 260  * @error: Return location for error.
 261  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 262  *
 263  * The type of the @set_property function in #GDBusInterfaceVTable.
 264  *
 265  * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
 266  *
 267  * Since: 2.26
 268  */
 269 typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *connection,
 270                                                     const gchar           *sender,
 271                                                     const gchar           *object_path,
 272                                                     const gchar           *interface_name,
 273                                                     const gchar           *property_name,
 274                                                     GVariant              *value,
 275                                                     GError               **error,
 276                                                     gpointer               user_data);
 277
 278 /**
 279  * GDBusInterfaceVTable:
 280  * @method_call: Function for handling incoming method calls.
 281  * @get_property: Function for getting a property.
 282  * @set_property: Function for setting a property.
 283  *
 284  * Virtual table for handling properties and method calls for a D-Bus
 285  * interface.
 286  *
 287  * If you want to handle getting/setting D-Bus properties asynchronously, simply
 288  * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
 289  * D-Bus interface using g_dbus_connection_register_object().
 290  *
 291  * Since: 2.26
 292  */
 293 struct _GDBusInterfaceVTable
 294 {
 295   GDBusInterfaceMethodCallFunc  method_call;
 296   GDBusInterfaceGetPropertyFunc get_property;
 297   GDBusInterfaceSetPropertyFunc set_property;
 298
 299   /*< private >*/
 300   /* Padding for future expansion */
 301   void (*_g_reserved1) (void);
 302   void (*_g_reserved2) (void);
 303   void (*_g_reserved3) (void);
 304   void (*_g_reserved4) (void);
 305   void (*_g_reserved5) (void);
 306   void (*_g_reserved6) (void);
 307   void (*_g_reserved7) (void);
 308   void (*_g_reserved8) (void);
 309 };
 310
 311 guint            g_dbus_connection_register_object            (GDBusConnection            *connection,
 312                                                                const gchar                *object_path,
 313                                                                const GDBusInterfaceInfo   *introspection_data,
 314                                                                const GDBusInterfaceVTable *vtable,
 315                                                                gpointer                    user_data,
 316                                                                GDestroyNotify              user_data_free_func,
 317                                                                GError                    **error);
 318 gboolean         g_dbus_connection_unregister_object          (GDBusConnection            *connection,
 319                                                                guint                       registration_id);
 320
 321 /* ---------------------------------------------------------------------------------------------------- */
 322
 323 /**
 324  * GDBusSubtreeEnumerateFunc:
 325  * @connection: A #GDBusConnection.
 326  * @sender: The unique bus name of the remote caller.
 327  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 328  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 329  *
 330  * The type of the @enumerate function in #GDBusSubtreeVTable.
 331  *
 332  * Returns: A newly allocated array of strings for node names that are children of @object_path.
 333  *
 334  * Since: 2.26
 335  */
 336 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection       *connection,
 337                                               const gchar           *sender,
 338                                               const gchar           *object_path,
 339                                               gpointer               user_data);
 340
 341 /**
 342  * GDBusSubtreeIntrospectFunc:
 343  * @connection: A #GDBusConnection.
 344  * @sender: The unique bus name of the remote caller.
 345  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 346  * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
 347  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 348  *
 349  * The type of the @introspect function in #GDBusSubtreeVTable.
 350  *
 351  * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
 352  * the interfaces implemented by @node.
 353  *
 354  * Since: 2.26
 355  */
 356 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection       *connection,
 357                                                   const gchar           *sender,
 358                                                   const gchar           *object_path,
 359                                                   const gchar           *node,
 360                                                   gpointer               user_data);
 361
 362 /**
 363  * GDBusSubtreeDispatchFunc:
 364  * @connection: A #GDBusConnection.
 365  * @sender: The unique bus name of the remote caller.
 366  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
 367  * @interface_name: The D-Bus interface name that the method call or property access is for.
 368  * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
 369  * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
 370  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
 371  *
 372  * The type of the @dispatch function in #GDBusSubtreeVTable.
 373  *
 374  * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
 375  *
 376  * Since: 2.26
 377  */
 378 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection             *connection,
 379                                                                   const gchar                 *sender,
 380                                                                   const gchar                 *object_path,
 381                                                                   const gchar                 *interface_name,
 382                                                                   const gchar                 *node,
 383                                                                   gpointer                    *out_user_data,
 384                                                                   gpointer                     user_data);
 385
 386 /**
 387  * GDBusSubtreeVTable:
 388  * @enumerate: Function for enumerating child nodes.
 389  * @introspect: Function for introspecting a child node.
 390  * @dispatch: Function for dispatching a remote call on a child node.
 391  *
 392  * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
 393  *
 394  * Since: 2.26
 395  */
 396 struct _GDBusSubtreeVTable
 397 {
 398   GDBusSubtreeEnumerateFunc  enumerate;
 399   GDBusSubtreeIntrospectFunc introspect;
 400   GDBusSubtreeDispatchFunc   dispatch;
 401
 402   /*< private >*/
 403   /* Padding for future expansion */
 404   void (*_g_reserved1) (void);
 405   void (*_g_reserved2) (void);
 406   void (*_g_reserved3) (void);
 407   void (*_g_reserved4) (void);
 408   void (*_g_reserved5) (void);
 409   void (*_g_reserved6) (void);
 410   void (*_g_reserved7) (void);
 411   void (*_g_reserved8) (void);
 412 };
 413
 414 guint            g_dbus_connection_register_subtree           (GDBusConnection            *connection,
 415                                                                const gchar                *object_path,
 416                                                                const GDBusSubtreeVTable   *vtable,
 417                                                                GDBusSubtreeFlags           flags,
 418                                                                gpointer                    user_data,
 419                                                                GDestroyNotify              user_data_free_func,
 420                                                                GError                    **error);
 421 gboolean         g_dbus_connection_unregister_subtree         (GDBusConnection            *connection,
 422                                                                guint                       registration_id);
 423
 424 /* ---------------------------------------------------------------------------------------------------- */
 425
 426 /**
 427  * GDBusSignalCallback:
 428  * @connection: A #GDBusConnection.
 429  * @sender_name: The unique bus name of the sender of the signal.
 430  * @object_path: The object path that the signal was emitted on.
 431  * @interface_name: The name of the signal.
 432  * @signal_name: The name of the signal.
 433  * @parameters: A #GVariant tuple with parameters for the signal.
 434  * @user_data: User data passed when subscribing to the signal.
 435  *
 436  * Signature for callback function used in g_dbus_connection_signal_subscribe().
 437  *
 438  * Since: 2.26
 439  */
 440 typedef void (*GDBusSignalCallback) (GDBusConnection  *connection,
 441                                      const gchar      *sender_name,
 442                                      const gchar      *object_path,
 443                                      const gchar      *interface_name,
 444                                      const gchar      *signal_name,
 445                                      GVariant         *parameters,
 446                                      gpointer          user_data);
 447
 448 guint            g_dbus_connection_signal_subscribe           (GDBusConnection     *connection,
 449                                                                const gchar         *sender,
 450                                                                const gchar         *interface_name,
 451                                                                const gchar         *member,
 452                                                                const gchar         *object_path,
 453                                                                const gchar         *arg0,
 454                                                                GDBusSignalCallback  callback,
 455                                                                gpointer             user_data,
 456                                                                GDestroyNotify       user_data_free_func);
 457 void             g_dbus_connection_signal_unsubscribe         (GDBusConnection     *connection,
 458                                                                guint                subscription_id);
 459
 460 /* ---------------------------------------------------------------------------------------------------- */
 461
 462 /**
 463  * GDBusMessageFilterFunction:
 464  * @connection: A #GDBusConnection.
 465  * @message: A #GDBusMessage.
 466  * @user_data: User data passed when adding the filter.
 467  *
 468  * Signature for function used in g_dbus_connection_add_filter().
 469  *
 470  * Returns: %TRUE if the filter handled @message, %FALSE to let other
 471  * handlers run.
 472  *
 473  * Since: 2.26
 474  */
 475 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
 476                                                 GDBusMessage    *message,
 477                                                 gpointer         user_data);
 478
 479 guint g_dbus_connection_add_filter (GDBusConnection            *connection,
 480                                     GDBusMessageFilterFunction  filter_function,
 481                                     gpointer                    user_data,
 482                                     GDestroyNotify              user_data_free_func);
 483
 484 void  g_dbus_connection_remove_filter (GDBusConnection    *connection,
 485                                        guint               filter_id);
 486
 487 /* ---------------------------------------------------------------------------------------------------- */
 488
 489
 490 G_END_DECLS
 491
 492 #endif /* __G_DBUS_CONNECTION_H__ */