Back to home page

EIC code displayed by LXR
 
 

    

File indexing completed on 2025-01-18 09:59:55 

0001 /* GDBus - GLib D-Bus Library
0002  *
0003  * Copyright (C) 2008-2010 Red Hat, Inc.
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General
0018  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  *
0020  * Author: David Zeuthen <davidz@redhat.com>
0021  */
0022 
0023 #ifndef __G_DBUS_CONNECTION_H__
0024 #define __G_DBUS_CONNECTION_H__
0025 
0026 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
0027 #error "Only <gio/gio.h> can be included directly."
0028 #endif
0029 
0030 #include <gio/giotypes.h>
0031 
0032 G_BEGIN_DECLS
0033 
0034 #define G_TYPE_DBUS_CONNECTION         (g_dbus_connection_get_type ())
0035 #define G_DBUS_CONNECTION(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
0036 #define G_IS_DBUS_CONNECTION(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
0037 
0038 GIO_AVAILABLE_IN_ALL
0039 GType            g_dbus_connection_get_type                   (void) G_GNUC_CONST;
0040 
0041 /* ---------------------------------------------------------------------------------------------------- */
0042 
0043 GIO_AVAILABLE_IN_ALL
0044 void              g_bus_get                    (GBusType             bus_type,
0045                                                 GCancellable        *cancellable,
0046                                                 GAsyncReadyCallback  callback,
0047                                                 gpointer             user_data);
0048 GIO_AVAILABLE_IN_ALL
0049 GDBusConnection  *g_bus_get_finish             (GAsyncResult        *res,
0050                                                 GError             **error);
0051 GIO_AVAILABLE_IN_ALL
0052 GDBusConnection  *g_bus_get_sync               (GBusType            bus_type,
0053                                                 GCancellable       *cancellable,
0054                                                 GError            **error);
0055 
0056 /* ---------------------------------------------------------------------------------------------------- */
0057 
0058 GIO_AVAILABLE_IN_ALL
0059 void             g_dbus_connection_new                        (GIOStream              *stream,
0060                                                                const gchar            *guid,
0061                                                                GDBusConnectionFlags    flags,
0062                                                                GDBusAuthObserver      *observer,
0063                                                                GCancellable           *cancellable,
0064                                                                GAsyncReadyCallback     callback,
0065                                                                gpointer                user_data);
0066 GIO_AVAILABLE_IN_ALL
0067 GDBusConnection *g_dbus_connection_new_finish                 (GAsyncResult           *res,
0068                                                                GError                **error);
0069 GIO_AVAILABLE_IN_ALL
0070 GDBusConnection *g_dbus_connection_new_sync                   (GIOStream              *stream,
0071                                                                const gchar            *guid,
0072                                                                GDBusConnectionFlags    flags,
0073                                                                GDBusAuthObserver      *observer,
0074                                                                GCancellable           *cancellable,
0075                                                                GError                **error);
0076 
0077 GIO_AVAILABLE_IN_ALL
0078 void             g_dbus_connection_new_for_address            (const gchar            *address,
0079                                                                GDBusConnectionFlags    flags,
0080                                                                GDBusAuthObserver      *observer,
0081                                                                GCancellable           *cancellable,
0082                                                                GAsyncReadyCallback     callback,
0083                                                                gpointer                user_data);
0084 GIO_AVAILABLE_IN_ALL
0085 GDBusConnection *g_dbus_connection_new_for_address_finish     (GAsyncResult           *res,
0086                                                                GError                **error);
0087 GIO_AVAILABLE_IN_ALL
0088 GDBusConnection *g_dbus_connection_new_for_address_sync       (const gchar            *address,
0089                                                                GDBusConnectionFlags    flags,
0090                                                                GDBusAuthObserver      *observer,
0091                                                                GCancellable           *cancellable,
0092                                                                GError                **error);
0093 
0094 /* ---------------------------------------------------------------------------------------------------- */
0095 
0096 GIO_AVAILABLE_IN_ALL
0097 void             g_dbus_connection_start_message_processing   (GDBusConnection    *connection);
0098 GIO_AVAILABLE_IN_ALL
0099 gboolean         g_dbus_connection_is_closed                  (GDBusConnection    *connection);
0100 GIO_AVAILABLE_IN_ALL
0101 GIOStream       *g_dbus_connection_get_stream                 (GDBusConnection    *connection);
0102 GIO_AVAILABLE_IN_ALL
0103 const gchar     *g_dbus_connection_get_guid                   (GDBusConnection    *connection);
0104 GIO_AVAILABLE_IN_ALL
0105 const gchar     *g_dbus_connection_get_unique_name            (GDBusConnection    *connection);
0106 GIO_AVAILABLE_IN_ALL
0107 GCredentials    *g_dbus_connection_get_peer_credentials       (GDBusConnection    *connection);
0108 
0109 GIO_AVAILABLE_IN_2_34
0110 guint32          g_dbus_connection_get_last_serial            (GDBusConnection    *connection);
0111 
0112 GIO_AVAILABLE_IN_ALL
0113 gboolean         g_dbus_connection_get_exit_on_close          (GDBusConnection    *connection);
0114 GIO_AVAILABLE_IN_ALL
0115 void             g_dbus_connection_set_exit_on_close          (GDBusConnection    *connection,
0116                                                                gboolean            exit_on_close);
0117 GIO_AVAILABLE_IN_ALL
0118 GDBusCapabilityFlags  g_dbus_connection_get_capabilities      (GDBusConnection    *connection);
0119 GIO_AVAILABLE_IN_2_60
0120 GDBusConnectionFlags  g_dbus_connection_get_flags             (GDBusConnection    *connection);
0121 
0122 /* ---------------------------------------------------------------------------------------------------- */
0123 
0124 GIO_AVAILABLE_IN_ALL
0125 void             g_dbus_connection_close                          (GDBusConnection     *connection,
0126                                                                    GCancellable        *cancellable,
0127                                                                    GAsyncReadyCallback  callback,
0128                                                                    gpointer             user_data);
0129 GIO_AVAILABLE_IN_ALL
0130 gboolean         g_dbus_connection_close_finish                   (GDBusConnection     *connection,
0131                                                                    GAsyncResult        *res,
0132                                                                    GError             **error);
0133 GIO_AVAILABLE_IN_ALL
0134 gboolean         g_dbus_connection_close_sync                     (GDBusConnection     *connection,
0135                                                                    GCancellable        *cancellable,
0136                                                                    GError             **error);
0137 
0138 /* ---------------------------------------------------------------------------------------------------- */
0139 
0140 GIO_AVAILABLE_IN_ALL
0141 void             g_dbus_connection_flush                          (GDBusConnection     *connection,
0142                                                                    GCancellable        *cancellable,
0143                                                                    GAsyncReadyCallback  callback,
0144                                                                    gpointer             user_data);
0145 GIO_AVAILABLE_IN_ALL
0146 gboolean         g_dbus_connection_flush_finish                   (GDBusConnection     *connection,
0147                                                                    GAsyncResult        *res,
0148                                                                    GError             **error);
0149 GIO_AVAILABLE_IN_ALL
0150 gboolean         g_dbus_connection_flush_sync                     (GDBusConnection     *connection,
0151                                                                    GCancellable        *cancellable,
0152                                                                    GError             **error);
0153 
0154 /* ---------------------------------------------------------------------------------------------------- */
0155 
0156 GIO_AVAILABLE_IN_ALL
0157 gboolean         g_dbus_connection_send_message                   (GDBusConnection     *connection,
0158                                                                    GDBusMessage        *message,
0159                                                                    GDBusSendMessageFlags flags,
0160                                                                    volatile guint32    *out_serial,
0161                                                                    GError             **error);
0162 GIO_AVAILABLE_IN_ALL
0163 void             g_dbus_connection_send_message_with_reply        (GDBusConnection     *connection,
0164                                                                    GDBusMessage        *message,
0165                                                                    GDBusSendMessageFlags flags,
0166                                                                    gint                 timeout_msec,
0167                                                                    volatile guint32    *out_serial,
0168                                                                    GCancellable        *cancellable,
0169                                                                    GAsyncReadyCallback  callback,
0170                                                                    gpointer             user_data);
0171 GIO_AVAILABLE_IN_ALL
0172 GDBusMessage    *g_dbus_connection_send_message_with_reply_finish (GDBusConnection     *connection,
0173                                                                    GAsyncResult        *res,
0174                                                                    GError             **error);
0175 GIO_AVAILABLE_IN_ALL
0176 GDBusMessage    *g_dbus_connection_send_message_with_reply_sync   (GDBusConnection     *connection,
0177                                                                    GDBusMessage        *message,
0178                                                                    GDBusSendMessageFlags flags,
0179                                                                    gint                 timeout_msec,
0180                                                                    volatile guint32    *out_serial,
0181                                                                    GCancellable        *cancellable,
0182                                                                    GError             **error);
0183 
0184 /* ---------------------------------------------------------------------------------------------------- */
0185 
0186 GIO_AVAILABLE_IN_ALL
0187 gboolean  g_dbus_connection_emit_signal                       (GDBusConnection    *connection,
0188                                                                const gchar        *destination_bus_name,
0189                                                                const gchar        *object_path,
0190                                                                const gchar        *interface_name,
0191                                                                const gchar        *signal_name,
0192                                                                GVariant           *parameters,
0193                                                                GError            **error);
0194 GIO_AVAILABLE_IN_ALL
0195 void      g_dbus_connection_call                              (GDBusConnection    *connection,
0196                                                                const gchar        *bus_name,
0197                                                                const gchar        *object_path,
0198                                                                const gchar        *interface_name,
0199                                                                const gchar        *method_name,
0200                                                                GVariant           *parameters,
0201                                                                const GVariantType *reply_type,
0202                                                                GDBusCallFlags      flags,
0203                                                                gint                timeout_msec,
0204                                                                GCancellable       *cancellable,
0205                                                                GAsyncReadyCallback callback,
0206                                                                gpointer            user_data);
0207 GIO_AVAILABLE_IN_ALL
0208 GVariant *g_dbus_connection_call_finish                       (GDBusConnection    *connection,
0209                                                                GAsyncResult       *res,
0210                                                                GError            **error);
0211 GIO_AVAILABLE_IN_ALL
0212 GVariant *g_dbus_connection_call_sync                         (GDBusConnection    *connection,
0213                                                                const gchar        *bus_name,
0214                                                                const gchar        *object_path,
0215                                                                const gchar        *interface_name,
0216                                                                const gchar        *method_name,
0217                                                                GVariant           *parameters,
0218                                                                const GVariantType *reply_type,
0219                                                                GDBusCallFlags      flags,
0220                                                                gint                timeout_msec,
0221                                                                GCancellable       *cancellable,
0222                                                                GError            **error);
0223 
0224 #ifdef G_OS_UNIX
0225 
0226 GIO_AVAILABLE_IN_2_30
0227 void      g_dbus_connection_call_with_unix_fd_list            (GDBusConnection    *connection,
0228                                                                const gchar        *bus_name,
0229                                                                const gchar        *object_path,
0230                                                                const gchar        *interface_name,
0231                                                                const gchar        *method_name,
0232                                                                GVariant           *parameters,
0233                                                                const GVariantType *reply_type,
0234                                                                GDBusCallFlags      flags,
0235                                                                gint                timeout_msec,
0236                                                                GUnixFDList        *fd_list,
0237                                                                GCancellable       *cancellable,
0238                                                                GAsyncReadyCallback callback,
0239                                                                gpointer            user_data);
0240 GIO_AVAILABLE_IN_2_30
0241 GVariant *g_dbus_connection_call_with_unix_fd_list_finish     (GDBusConnection    *connection,
0242                                                                GUnixFDList       **out_fd_list,
0243                                                                GAsyncResult       *res,
0244                                                                GError            **error);
0245 GIO_AVAILABLE_IN_2_30
0246 GVariant *g_dbus_connection_call_with_unix_fd_list_sync       (GDBusConnection    *connection,
0247                                                                const gchar        *bus_name,
0248                                                                const gchar        *object_path,
0249                                                                const gchar        *interface_name,
0250                                                                const gchar        *method_name,
0251                                                                GVariant           *parameters,
0252                                                                const GVariantType *reply_type,
0253                                                                GDBusCallFlags      flags,
0254                                                                gint                timeout_msec,
0255                                                                GUnixFDList        *fd_list,
0256                                                                GUnixFDList       **out_fd_list,
0257                                                                GCancellable       *cancellable,
0258                                                                GError            **error);
0259 
0260 #endif /* G_OS_UNIX */
0261 
0262 /* ---------------------------------------------------------------------------------------------------- */
0263 
0264 
0265 /**
0266  * GDBusInterfaceMethodCallFunc:
0267  * @connection: A #GDBusConnection.
0268  * @sender: The unique bus name of the remote caller.
0269  * @object_path: The object path that the method was invoked on.
0270  * @interface_name: The D-Bus interface name the method was invoked on.
0271  * @method_name: The name of the method that was invoked.
0272  * @parameters: A #GVariant tuple with parameters.
0273  * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error.
0274  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
0275  *
0276  * The type of the @method_call function in #GDBusInterfaceVTable.
0277  *
0278  * Since: 2.26
0279  */
0280 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection       *connection,
0281                                               const gchar           *sender,
0282                                               const gchar           *object_path,
0283                                               const gchar           *interface_name,
0284                                               const gchar           *method_name,
0285                                               GVariant              *parameters,
0286                                               GDBusMethodInvocation *invocation,
0287                                               gpointer               user_data);
0288 
0289 /**
0290  * GDBusInterfaceGetPropertyFunc:
0291  * @connection: A #GDBusConnection.
0292  * @sender: The unique bus name of the remote caller.
0293  * @object_path: The object path that the method was invoked on.
0294  * @interface_name: The D-Bus interface name for the property.
0295  * @property_name: The name of the property to get the value of.
0296  * @error: Return location for error.
0297  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
0298  *
0299  * The type of the @get_property function in #GDBusInterfaceVTable.
0300  *
0301  * Returns: A #GVariant with the value for @property_name or %NULL if
0302  *     @error is set. If the returned #GVariant is floating, it is
0303  *     consumed - otherwise its reference count is decreased by one.
0304  *
0305  * Since: 2.26
0306  */
0307 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection       *connection,
0308                                                     const gchar           *sender,
0309                                                     const gchar           *object_path,
0310                                                     const gchar           *interface_name,
0311                                                     const gchar           *property_name,
0312                                                     GError               **error,
0313                                                     gpointer               user_data);
0314 
0315 /**
0316  * GDBusInterfaceSetPropertyFunc:
0317  * @connection: A #GDBusConnection.
0318  * @sender: The unique bus name of the remote caller.
0319  * @object_path: The object path that the method was invoked on.
0320  * @interface_name: The D-Bus interface name for the property.
0321  * @property_name: The name of the property to get the value of.
0322  * @value: The value to set the property to.
0323  * @error: Return location for error.
0324  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
0325  *
0326  * The type of the @set_property function in #GDBusInterfaceVTable.
0327  *
0328  * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
0329  *
0330  * Since: 2.26
0331  */
0332 typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *connection,
0333                                                     const gchar           *sender,
0334                                                     const gchar           *object_path,
0335                                                     const gchar           *interface_name,
0336                                                     const gchar           *property_name,
0337                                                     GVariant              *value,
0338                                                     GError               **error,
0339                                                     gpointer               user_data);
0340 
0341 /**
0342  * GDBusInterfaceVTable:
0343  * @method_call: Function for handling incoming method calls.
0344  * @get_property: Function for getting a property.
0345  * @set_property: Function for setting a property.
0346  *
0347  * Virtual table for handling properties and method calls for a D-Bus
0348  * interface.
0349  *
0350  * Since 2.38, if you want to handle getting/setting D-Bus properties
0351  * asynchronously, give %NULL as your get_property() or set_property()
0352  * function. The D-Bus call will be directed to your @method_call function,
0353  * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
0354  *
0355  * Ownership of the #GDBusMethodInvocation object passed to the
0356  * method_call() function is transferred to your handler; you must
0357  * call one of the methods of #GDBusMethodInvocation to return a reply
0358  * (possibly empty), or an error. These functions also take ownership
0359  * of the passed-in invocation object, so unless the invocation
0360  * object has otherwise been referenced, it will be then be freed.
0361  * Calling one of these functions may be done within your
0362  * method_call() implementation but it also can be done at a later
0363  * point to handle the method asynchronously.
0364  *
0365  * The usual checks on the validity of the calls is performed. For
0366  * `Get` calls, an error is automatically returned if the property does
0367  * not exist or the permissions do not allow access. The same checks are
0368  * performed for `Set` calls, and the provided value is also checked for
0369  * being the correct type.
0370  *
0371  * For both `Get` and `Set` calls, the #GDBusMethodInvocation
0372  * passed to the @method_call handler can be queried with
0373  * g_dbus_method_invocation_get_property_info() to get a pointer
0374  * to the #GDBusPropertyInfo of the property.
0375  *
0376  * If you have readable properties specified in your interface info,
0377  * you must ensure that you either provide a non-%NULL @get_property()
0378  * function or provide implementations of both the `Get` and `GetAll`
0379  * methods on org.freedesktop.DBus.Properties interface in your @method_call
0380  * function. Note that the required return type of the `Get` call is
0381  * `(v)`, not the type of the property. `GetAll` expects a return value
0382  * of type `a{sv}`.
0383  *
0384  * If you have writable properties specified in your interface info,
0385  * you must ensure that you either provide a non-%NULL @set_property()
0386  * function or provide an implementation of the `Set` call. If implementing
0387  * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
0388  *
0389  * Since: 2.26
0390  */
0391 struct _GDBusInterfaceVTable
0392 {
0393   GDBusInterfaceMethodCallFunc  method_call;
0394   GDBusInterfaceGetPropertyFunc get_property;
0395   GDBusInterfaceSetPropertyFunc set_property;
0396 
0397   /*< private >*/
0398   /* Padding for future expansion - also remember to update
0399    * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
0400    * changing this.
0401    */
0402   gpointer padding[8];
0403 };
0404 
0405 GIO_AVAILABLE_IN_ALL
0406 guint            g_dbus_connection_register_object            (GDBusConnection            *connection,
0407                                                                const gchar                *object_path,
0408                                                                GDBusInterfaceInfo         *interface_info,
0409                                                                const GDBusInterfaceVTable *vtable,
0410                                                                gpointer                    user_data,
0411                                                                GDestroyNotify              user_data_free_func,
0412                                                                GError                    **error);
0413 GIO_AVAILABLE_IN_2_46
0414 guint            g_dbus_connection_register_object_with_closures (GDBusConnection         *connection,
0415                                                                   const gchar             *object_path,
0416                                                                   GDBusInterfaceInfo      *interface_info,
0417                                                                   GClosure                *method_call_closure,
0418                                                                   GClosure                *get_property_closure,
0419                                                                   GClosure                *set_property_closure,
0420                                                                   GError                 **error);
0421 GIO_AVAILABLE_IN_ALL
0422 gboolean         g_dbus_connection_unregister_object          (GDBusConnection            *connection,
0423                                                                guint                       registration_id);
0424 
0425 /* ---------------------------------------------------------------------------------------------------- */
0426 
0427 /**
0428  * GDBusSubtreeEnumerateFunc:
0429  * @connection: A #GDBusConnection.
0430  * @sender: The unique bus name of the remote caller.
0431  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
0432  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
0433  *
0434  * The type of the @enumerate function in #GDBusSubtreeVTable.
0435  *
0436  * This function is called when generating introspection data and also
0437  * when preparing to dispatch incoming messages in the event that the
0438  * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
0439  * specified (ie: to verify that the object path is valid).
0440  *
0441  * Hierarchies are not supported; the items that you return should not
0442  * contain the `/` character.
0443  *
0444  * The return value will be freed with g_strfreev().
0445  *
0446  * Returns: (array zero-terminated=1) (transfer full): A newly allocated array of strings for node names that are children of @object_path.
0447  *
0448  * Since: 2.26
0449  */
0450 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection       *connection,
0451                                               const gchar           *sender,
0452                                               const gchar           *object_path,
0453                                               gpointer               user_data);
0454 
0455 /**
0456  * GDBusSubtreeIntrospectFunc:
0457  * @connection: A #GDBusConnection.
0458  * @sender: The unique bus name of the remote caller.
0459  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
0460  * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
0461  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
0462  *
0463  * The type of the @introspect function in #GDBusSubtreeVTable.
0464  *
0465  * Subtrees are flat.  @node, if non-%NULL, is always exactly one
0466  * segment of the object path (ie: it never contains a slash).
0467  *
0468  * This function should return %NULL to indicate that there is no object
0469  * at this node.
0470  *
0471  * If this function returns non-%NULL, the return value is expected to
0472  * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
0473  * structures describing the interfaces implemented by @node.  This
0474  * array will have g_dbus_interface_info_unref() called on each item
0475  * before being freed with g_free().
0476  *
0477  * The difference between returning %NULL and an array containing zero
0478  * items is that the standard DBus interfaces will returned to the
0479  * remote introspector in the empty array case, but not in the %NULL
0480  * case.
0481  *
0482  * Returns: (array zero-terminated=1) (nullable) (transfer full): A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
0483  *
0484  * Since: 2.26
0485  */
0486 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection       *connection,
0487                                                              const gchar           *sender,
0488                                                              const gchar           *object_path,
0489                                                              const gchar           *node,
0490                                                              gpointer               user_data);
0491 
0492 /**
0493  * GDBusSubtreeDispatchFunc:
0494  * @connection: A #GDBusConnection.
0495  * @sender: The unique bus name of the remote caller.
0496  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
0497  * @interface_name: The D-Bus interface name that the method call or property access is for.
0498  * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
0499  * @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable.
0500  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
0501  *
0502  * The type of the @dispatch function in #GDBusSubtreeVTable.
0503  *
0504  * Subtrees are flat.  @node, if non-%NULL, is always exactly one
0505  * segment of the object path (ie: it never contains a slash).
0506  *
0507  * Returns: (nullable): A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
0508  *
0509  * Since: 2.26
0510  */
0511 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection             *connection,
0512                                                                   const gchar                 *sender,
0513                                                                   const gchar                 *object_path,
0514                                                                   const gchar                 *interface_name,
0515                                                                   const gchar                 *node,
0516                                                                   gpointer                    *out_user_data,
0517                                                                   gpointer                     user_data);
0518 
0519 /**
0520  * GDBusSubtreeVTable:
0521  * @enumerate: Function for enumerating child nodes.
0522  * @introspect: Function for introspecting a child node.
0523  * @dispatch: Function for dispatching a remote call on a child node.
0524  *
0525  * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
0526  *
0527  * Since: 2.26
0528  */
0529 struct _GDBusSubtreeVTable
0530 {
0531   GDBusSubtreeEnumerateFunc  enumerate;
0532   GDBusSubtreeIntrospectFunc introspect;
0533   GDBusSubtreeDispatchFunc   dispatch;
0534 
0535   /*< private >*/
0536   /* Padding for future expansion - also remember to update
0537    * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
0538    * changing this.
0539    */
0540   gpointer padding[8];
0541 };
0542 
0543 GIO_AVAILABLE_IN_ALL
0544 guint            g_dbus_connection_register_subtree           (GDBusConnection            *connection,
0545                                                                const gchar                *object_path,
0546                                                                const GDBusSubtreeVTable   *vtable,
0547                                                                GDBusSubtreeFlags           flags,
0548                                                                gpointer                    user_data,
0549                                                                GDestroyNotify              user_data_free_func,
0550                                                                GError                    **error);
0551 GIO_AVAILABLE_IN_ALL
0552 gboolean         g_dbus_connection_unregister_subtree         (GDBusConnection            *connection,
0553                                                                guint                       registration_id);
0554 
0555 /* ---------------------------------------------------------------------------------------------------- */
0556 
0557 /**
0558  * GDBusSignalCallback:
0559  * @connection: A #GDBusConnection.
0560  * @sender_name: (nullable): The unique bus name of the sender of the signal,
0561    or %NULL on a peer-to-peer D-Bus connection.
0562  * @object_path: The object path that the signal was emitted on.
0563  * @interface_name: The name of the interface.
0564  * @signal_name: The name of the signal.
0565  * @parameters: A #GVariant tuple with parameters for the signal.
0566  * @user_data: User data passed when subscribing to the signal.
0567  *
0568  * Signature for callback function used in g_dbus_connection_signal_subscribe().
0569  *
0570  * Since: 2.26
0571  */
0572 typedef void (*GDBusSignalCallback) (GDBusConnection  *connection,
0573                                      const gchar      *sender_name,
0574                                      const gchar      *object_path,
0575                                      const gchar      *interface_name,
0576                                      const gchar      *signal_name,
0577                                      GVariant         *parameters,
0578                                      gpointer          user_data);
0579 
0580 GIO_AVAILABLE_IN_ALL
0581 guint            g_dbus_connection_signal_subscribe           (GDBusConnection     *connection,
0582                                                                const gchar         *sender,
0583                                                                const gchar         *interface_name,
0584                                                                const gchar         *member,
0585                                                                const gchar         *object_path,
0586                                                                const gchar         *arg0,
0587                                                                GDBusSignalFlags     flags,
0588                                                                GDBusSignalCallback  callback,
0589                                                                gpointer             user_data,
0590                                                                GDestroyNotify       user_data_free_func);
0591 GIO_AVAILABLE_IN_ALL
0592 void             g_dbus_connection_signal_unsubscribe         (GDBusConnection     *connection,
0593                                                                guint                subscription_id);
0594 
0595 /* ---------------------------------------------------------------------------------------------------- */
0596 
0597 /**
0598  * GDBusMessageFilterFunction:
0599  * @connection: (transfer none): A #GDBusConnection.
0600  * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
0601  * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
0602  * a message to be sent to the other peer.
0603  * @user_data: User data passed when adding the filter.
0604  *
0605  * Signature for function used in g_dbus_connection_add_filter().
0606  *
0607  * A filter function is passed a #GDBusMessage and expected to return
0608  * a #GDBusMessage too. Passive filter functions that don't modify the
0609  * message can simply return the @message object:
0610  * |[
0611  * static GDBusMessage *
0612  * passive_filter (GDBusConnection *connection
0613  *                 GDBusMessage    *message,
0614  *                 gboolean         incoming,
0615  *                 gpointer         user_data)
0616  * {
0617  *   // inspect @message
0618  *   return message;
0619  * }
0620  * ]|
0621  * Filter functions that wants to drop a message can simply return %NULL:
0622  * |[
0623  * static GDBusMessage *
0624  * drop_filter (GDBusConnection *connection
0625  *              GDBusMessage    *message,
0626  *              gboolean         incoming,
0627  *              gpointer         user_data)
0628  * {
0629  *   if (should_drop_message)
0630  *     {
0631  *       g_object_unref (message);
0632  *       message = NULL;
0633  *     }
0634  *   return message;
0635  * }
0636  * ]|
0637  * Finally, a filter function may modify a message by copying it:
0638  * |[
0639  * static GDBusMessage *
0640  * modifying_filter (GDBusConnection *connection
0641  *                   GDBusMessage    *message,
0642  *                   gboolean         incoming,
0643  *                   gpointer         user_data)
0644  * {
0645  *   GDBusMessage *copy;
0646  *   GError *error;
0647  *
0648  *   error = NULL;
0649  *   copy = g_dbus_message_copy (message, &error);
0650  *   // handle @error being set
0651  *   g_object_unref (message);
0652  *
0653  *   // modify @copy
0654  *
0655  *   return copy;
0656  * }
0657  * ]|
0658  * If the returned #GDBusMessage is different from @message and cannot
0659  * be sent on @connection (it could use features, such as file
0660  * descriptors, not compatible with @connection), then a warning is
0661  * logged to standard error. Applications can
0662  * check this ahead of time using g_dbus_message_to_blob() passing a
0663  * #GDBusCapabilityFlags value obtained from @connection.
0664  *
0665  * Returns: (transfer full) (nullable): A #GDBusMessage that will be freed with
0666  * g_object_unref() or %NULL to drop the message. Passive filter
0667  * functions can simply return the passed @message object.
0668  *
0669  * Since: 2.26
0670  */
0671 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
0672                                                      GDBusMessage    *message,
0673                                                      gboolean         incoming,
0674                                                      gpointer         user_data);
0675 
0676 GIO_AVAILABLE_IN_ALL
0677 guint g_dbus_connection_add_filter (GDBusConnection            *connection,
0678                                     GDBusMessageFilterFunction  filter_function,
0679                                     gpointer                    user_data,
0680                                     GDestroyNotify              user_data_free_func);
0681 
0682 GIO_AVAILABLE_IN_ALL
0683 void  g_dbus_connection_remove_filter (GDBusConnection    *connection,
0684                                        guint               filter_id);
0685 
0686 /* ---------------------------------------------------------------------------------------------------- */
0687 
0688 
0689 G_END_DECLS
0690 
0691 #endif /* __G_DBUS_CONNECTION_H__ */
[ Source navigation ] [ Diff markup ] [ Identifier search ] [ general search ]

This page was automatically generated by the 2.3.7 LXR engine.

The LXR team
Valid CSS 2.1! Valid HTML 4.01!