gio/gdbusconnection.h

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