Back to home page

EIC code displayed by LXR
 
 

    

File indexing completed on 2026-09-09 09:10:43 

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: (nullable): The unique bus name of the remote caller, or `NULL` if
0269  *     not specified by the caller, e.g. on peer-to-peer connections.
0270  * @object_path: The object path that the method was invoked on.
0271  * @interface_name: (nullable): The D-Bus interface name the method was invoked on,
0272  *     or `NULL` if not specified by the sender.
0273  * @method_name: The name of the method that was invoked.
0274  * @parameters: A #GVariant tuple with parameters.
0275  * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error.
0276  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
0277  *
0278  * The type of the @method_call function in #GDBusInterfaceVTable.
0279  *
0280  * @interface_name may be `NULL` if not specified by the sender, although it’s
0281  * encouraged for the sender to set it. If unset, and the object has only one
0282  * method (across all interfaces) matching @method_name, that method is invoked.
0283  * Otherwise, behaviour is implementation defined. See the
0284  * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method).
0285  * It is recommended to return [error@Gio.DBusError.UNKNOWN_METHOD].
0286  *
0287  * Since: 2.26
0288  */
0289 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection       *connection,
0290                                               const gchar           *sender,
0291                                               const gchar           *object_path,
0292                                               const gchar           *interface_name,
0293                                               const gchar           *method_name,
0294                                               GVariant              *parameters,
0295                                               GDBusMethodInvocation *invocation,
0296                                               gpointer               user_data);
0297 
0298 /**
0299  * GDBusInterfaceGetPropertyFunc:
0300  * @connection: A #GDBusConnection.
0301  * @sender: (nullable): The unique bus name of the remote caller or %NULL if
0302  *     not specified by the caller, e.g. on peer-to-peer connections.
0303  * @object_path: The object path that the method was invoked on.
0304  * @interface_name: The D-Bus interface name for the property.
0305  * @property_name: The name of the property to get the value of.
0306  * @error: Return location for error.
0307  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
0308  *
0309  * The type of the @get_property function in #GDBusInterfaceVTable.
0310  *
0311  * Returns: A #GVariant with the value for @property_name or %NULL if
0312  *     @error is set. If the returned #GVariant is floating, it is
0313  *     consumed - otherwise its reference count is decreased by one.
0314  *
0315  * Since: 2.26
0316  */
0317 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection       *connection,
0318                                                     const gchar           *sender,
0319                                                     const gchar           *object_path,
0320                                                     const gchar           *interface_name,
0321                                                     const gchar           *property_name,
0322                                                     GError               **error,
0323                                                     gpointer               user_data);
0324 
0325 /**
0326  * GDBusInterfaceSetPropertyFunc:
0327  * @connection: A #GDBusConnection.
0328  * @sender: (nullable): The unique bus name of the remote caller or %NULL if
0329  *     not specified by the caller, e.g. on peer-to-peer connections.
0330  * @object_path: The object path that the method was invoked on.
0331  * @interface_name: The D-Bus interface name for the property.
0332  * @property_name: The name of the property to get the value of.
0333  * @value: The value to set the property to.
0334  * @error: Return location for error.
0335  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
0336  *
0337  * The type of the @set_property function in #GDBusInterfaceVTable.
0338  *
0339  * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
0340  *
0341  * Since: 2.26
0342  */
0343 typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *connection,
0344                                                     const gchar           *sender,
0345                                                     const gchar           *object_path,
0346                                                     const gchar           *interface_name,
0347                                                     const gchar           *property_name,
0348                                                     GVariant              *value,
0349                                                     GError               **error,
0350                                                     gpointer               user_data);
0351 
0352 /**
0353  * GDBusInterfaceVTable:
0354  * @method_call: Function for handling incoming method calls.
0355  * @get_property: Function for getting a property.
0356  * @set_property: Function for setting a property.
0357  *
0358  * Virtual table for handling properties and method calls for a D-Bus
0359  * interface.
0360  *
0361  * Since 2.38, if you want to handle getting/setting D-Bus properties
0362  * asynchronously, give %NULL as your get_property() or set_property()
0363  * function. The D-Bus call will be directed to your @method_call function,
0364  * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
0365  *
0366  * Ownership of the #GDBusMethodInvocation object passed to the
0367  * method_call() function is transferred to your handler; you must
0368  * call one of the methods of #GDBusMethodInvocation to return a reply
0369  * (possibly empty), or an error. These functions also take ownership
0370  * of the passed-in invocation object, so unless the invocation
0371  * object has otherwise been referenced, it will be then be freed.
0372  * Calling one of these functions may be done within your
0373  * method_call() implementation but it also can be done at a later
0374  * point to handle the method asynchronously.
0375  *
0376  * The usual checks on the validity of the calls is performed. For
0377  * `Get` calls, an error is automatically returned if the property does
0378  * not exist or the permissions do not allow access. The same checks are
0379  * performed for `Set` calls, and the provided value is also checked for
0380  * being the correct type.
0381  *
0382  * For both `Get` and `Set` calls, the #GDBusMethodInvocation
0383  * passed to the @method_call handler can be queried with
0384  * g_dbus_method_invocation_get_property_info() to get a pointer
0385  * to the #GDBusPropertyInfo of the property.
0386  *
0387  * If you have readable properties specified in your interface info,
0388  * you must ensure that you either provide a non-%NULL @get_property()
0389  * function or provide implementations of both the `Get` and `GetAll`
0390  * methods on org.freedesktop.DBus.Properties interface in your @method_call
0391  * function. Note that the required return type of the `Get` call is
0392  * `(v)`, not the type of the property. `GetAll` expects a return value
0393  * of type `a{sv}`.
0394  *
0395  * If you have writable properties specified in your interface info,
0396  * you must ensure that you either provide a non-%NULL @set_property()
0397  * function or provide an implementation of the `Set` call. If implementing
0398  * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
0399  *
0400  * Since: 2.26
0401  */
0402 struct _GDBusInterfaceVTable
0403 {
0404   GDBusInterfaceMethodCallFunc  method_call;
0405   GDBusInterfaceGetPropertyFunc get_property;
0406   GDBusInterfaceSetPropertyFunc set_property;
0407 
0408   /*< private >*/
0409   /* Padding for future expansion - also remember to update
0410    * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
0411    * changing this.
0412    */
0413   gpointer padding[8];
0414 };
0415 
0416 GIO_AVAILABLE_IN_ALL
0417 guint            g_dbus_connection_register_object            (GDBusConnection            *connection,
0418                                                                const gchar                *object_path,
0419                                                                GDBusInterfaceInfo         *interface_info,
0420                                                                const GDBusInterfaceVTable *vtable,
0421                                                                gpointer                    user_data,
0422                                                                GDestroyNotify              user_data_free_func,
0423                                                                GError                    **error);
0424 GIO_DEPRECATED_IN_2_84_FOR(g_dbus_connection_register_object_with_closures2)
0425 guint            g_dbus_connection_register_object_with_closures (GDBusConnection         *connection,
0426                                                                   const gchar             *object_path,
0427                                                                   GDBusInterfaceInfo      *interface_info,
0428                                                                   GClosure                *method_call_closure,
0429                                                                   GClosure                *get_property_closure,
0430                                                                   GClosure                *set_property_closure,
0431                                                                   GError                 **error);
0432 GIO_AVAILABLE_IN_2_84
0433 guint            g_dbus_connection_register_object_with_closures2 (GDBusConnection         *connection,
0434                                                                    const gchar             *object_path,
0435                                                                    GDBusInterfaceInfo      *interface_info,
0436                                                                    GClosure                *method_call_closure,
0437                                                                    GClosure                *get_property_closure,
0438                                                                    GClosure                *set_property_closure,
0439                                                                    GError                 **error);
0440 GIO_AVAILABLE_IN_ALL
0441 gboolean         g_dbus_connection_unregister_object          (GDBusConnection            *connection,
0442                                                                guint                       registration_id);
0443 
0444 /* ---------------------------------------------------------------------------------------------------- */
0445 
0446 /**
0447  * GDBusSubtreeEnumerateFunc:
0448  * @connection: A #GDBusConnection.
0449  * @sender: The unique bus name of the remote caller.
0450  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
0451  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
0452  *
0453  * The type of the @enumerate function in #GDBusSubtreeVTable.
0454  *
0455  * This function is called when generating introspection data and also
0456  * when preparing to dispatch incoming messages in the event that the
0457  * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
0458  * specified (ie: to verify that the object path is valid).
0459  *
0460  * Hierarchies are not supported; the items that you return should not
0461  * contain the `/` character.
0462  *
0463  * The return value will be freed with g_strfreev().
0464  *
0465  * Returns: (array zero-terminated=1) (transfer full): A newly allocated array of strings for node names that are children of @object_path.
0466  *
0467  * Since: 2.26
0468  */
0469 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection       *connection,
0470                                               const gchar           *sender,
0471                                               const gchar           *object_path,
0472                                               gpointer               user_data);
0473 
0474 /**
0475  * GDBusSubtreeIntrospectFunc:
0476  * @connection: A #GDBusConnection.
0477  * @sender: The unique bus name of the remote caller.
0478  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
0479  * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
0480  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
0481  *
0482  * The type of the @introspect function in #GDBusSubtreeVTable.
0483  *
0484  * Subtrees are flat.  @node, if non-%NULL, is always exactly one
0485  * segment of the object path (ie: it never contains a slash).
0486  *
0487  * This function should return %NULL to indicate that there is no object
0488  * at this node.
0489  *
0490  * If this function returns non-%NULL, the return value is expected to
0491  * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
0492  * structures describing the interfaces implemented by @node.  This
0493  * array will have g_dbus_interface_info_unref() called on each item
0494  * before being freed with g_free().
0495  *
0496  * The difference between returning %NULL and an array containing zero
0497  * items is that the standard DBus interfaces will returned to the
0498  * remote introspector in the empty array case, but not in the %NULL
0499  * case.
0500  *
0501  * Returns: (array zero-terminated=1) (nullable) (transfer full): A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
0502  *
0503  * Since: 2.26
0504  */
0505 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection       *connection,
0506                                                              const gchar           *sender,
0507                                                              const gchar           *object_path,
0508                                                              const gchar           *node,
0509                                                              gpointer               user_data);
0510 
0511 /**
0512  * GDBusSubtreeDispatchFunc:
0513  * @connection: A #GDBusConnection.
0514  * @sender: The unique bus name of the remote caller.
0515  * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
0516  * @interface_name: The D-Bus interface name that the method call or property access is for.
0517  * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
0518  * @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable.
0519  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
0520  *
0521  * The type of the @dispatch function in #GDBusSubtreeVTable.
0522  *
0523  * Subtrees are flat.  @node, if non-%NULL, is always exactly one
0524  * segment of the object path (ie: it never contains a slash).
0525  *
0526  * Returns: (nullable): A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
0527  *
0528  * Since: 2.26
0529  */
0530 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection             *connection,
0531                                                                   const gchar                 *sender,
0532                                                                   const gchar                 *object_path,
0533                                                                   const gchar                 *interface_name,
0534                                                                   const gchar                 *node,
0535                                                                   gpointer                    *out_user_data,
0536                                                                   gpointer                     user_data);
0537 
0538 /**
0539  * GDBusSubtreeVTable:
0540  * @enumerate: Function for enumerating child nodes.
0541  * @introspect: Function for introspecting a child node.
0542  * @dispatch: Function for dispatching a remote call on a child node.
0543  *
0544  * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
0545  *
0546  * Since: 2.26
0547  */
0548 struct _GDBusSubtreeVTable
0549 {
0550   GDBusSubtreeEnumerateFunc  enumerate;
0551   GDBusSubtreeIntrospectFunc introspect;
0552   GDBusSubtreeDispatchFunc   dispatch;
0553 
0554   /*< private >*/
0555   /* Padding for future expansion - also remember to update
0556    * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
0557    * changing this.
0558    */
0559   gpointer padding[8];
0560 };
0561 
0562 GIO_AVAILABLE_IN_ALL
0563 guint            g_dbus_connection_register_subtree           (GDBusConnection            *connection,
0564                                                                const gchar                *object_path,
0565                                                                const GDBusSubtreeVTable   *vtable,
0566                                                                GDBusSubtreeFlags           flags,
0567                                                                gpointer                    user_data,
0568                                                                GDestroyNotify              user_data_free_func,
0569                                                                GError                    **error);
0570 GIO_AVAILABLE_IN_ALL
0571 gboolean         g_dbus_connection_unregister_subtree         (GDBusConnection            *connection,
0572                                                                guint                       registration_id);
0573 
0574 /* ---------------------------------------------------------------------------------------------------- */
0575 
0576 /**
0577  * GDBusSignalCallback:
0578  * @connection: A #GDBusConnection.
0579  * @sender_name: (nullable): The unique bus name of the sender of the signal,
0580    or %NULL on a peer-to-peer D-Bus connection.
0581  * @object_path: The object path that the signal was emitted on.
0582  * @interface_name: The name of the interface.
0583  * @signal_name: The name of the signal.
0584  * @parameters: A #GVariant tuple with parameters for the signal.
0585  * @user_data: User data passed when subscribing to the signal.
0586  *
0587  * Signature for callback function used in g_dbus_connection_signal_subscribe().
0588  *
0589  * Since: 2.26
0590  */
0591 typedef void (*GDBusSignalCallback) (GDBusConnection  *connection,
0592                                      const gchar      *sender_name,
0593                                      const gchar      *object_path,
0594                                      const gchar      *interface_name,
0595                                      const gchar      *signal_name,
0596                                      GVariant         *parameters,
0597                                      gpointer          user_data);
0598 
0599 GIO_AVAILABLE_IN_ALL
0600 guint            g_dbus_connection_signal_subscribe           (GDBusConnection     *connection,
0601                                                                const gchar         *sender,
0602                                                                const gchar         *interface_name,
0603                                                                const gchar         *member,
0604                                                                const gchar         *object_path,
0605                                                                const gchar         *arg0,
0606                                                                GDBusSignalFlags     flags,
0607                                                                GDBusSignalCallback  callback,
0608                                                                gpointer             user_data,
0609                                                                GDestroyNotify       user_data_free_func);
0610 GIO_AVAILABLE_IN_ALL
0611 void             g_dbus_connection_signal_unsubscribe         (GDBusConnection     *connection,
0612                                                                guint                subscription_id);
0613 
0614 /**
0615  * g_clear_dbus_signal_subscription: (skip)
0616  * @subscription_id_pointer: (not optional) (inout): A pointer to either a
0617  *    subscription ID obtained from [method@Gio.DBusConnection.signal_subscribe],
0618  *    or zero.
0619  * @connection: The connection from which the subscription ID was obtained.
0620  *    This pointer may be `NULL` or invalid, if the subscription ID is zero.
0621  *
0622  * If @subscription_id_pointer points to a nonzero subscription ID,
0623  * unsubscribe from that D-Bus signal subscription as if via
0624  * [method@Gio.DBusConnection.signal_unsubscribe].
0625  *
0626  * Also set the value pointed to by @subscription_id_pointer to zero,
0627  * which signifies it’s no longer a valid subscription ID.
0628  *
0629  * This convenience function for C code helps to ensure that each signal
0630  * subscription is unsubscribed exactly once, similar to
0631  * [func@GObject.clear_object] and [func@GObject.clear_signal_handler].
0632  *
0633  * Since: 2.84
0634  */
0635 GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
0636 static inline void g_clear_dbus_signal_subscription           (guint               *subscription_id_pointer,
0637                                                                GDBusConnection     *connection);
0638 
0639 GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
0640 static inline void
0641 g_clear_dbus_signal_subscription (guint           *subscription_id_pointer,
0642                                   GDBusConnection *connection)
0643 {
0644   guint subscription_id;
0645 
0646   /* Suppress "Not available before" warning */
0647   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0648   subscription_id = g_steal_handle_id (subscription_id_pointer);
0649   G_GNUC_END_IGNORE_DEPRECATIONS
0650 
0651   if (subscription_id > 0)
0652     g_dbus_connection_signal_unsubscribe (connection, subscription_id);
0653 }
0654 
0655 /* ---------------------------------------------------------------------------------------------------- */
0656 
0657 /**
0658  * GDBusMessageFilterFunction:
0659  * @connection: (transfer none): A #GDBusConnection.
0660  * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
0661  * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
0662  * a message to be sent to the other peer.
0663  * @user_data: User data passed when adding the filter.
0664  *
0665  * Signature for function used in g_dbus_connection_add_filter().
0666  *
0667  * A filter function is passed a #GDBusMessage and expected to return
0668  * a #GDBusMessage too. Passive filter functions that don't modify the
0669  * message can simply return the @message object:
0670  * |[
0671  * static GDBusMessage *
0672  * passive_filter (GDBusConnection *connection
0673  *                 GDBusMessage    *message,
0674  *                 gboolean         incoming,
0675  *                 gpointer         user_data)
0676  * {
0677  *   // inspect @message
0678  *   return message;
0679  * }
0680  * ]|
0681  * Filter functions that wants to drop a message can simply return %NULL:
0682  * |[
0683  * static GDBusMessage *
0684  * drop_filter (GDBusConnection *connection
0685  *              GDBusMessage    *message,
0686  *              gboolean         incoming,
0687  *              gpointer         user_data)
0688  * {
0689  *   if (should_drop_message)
0690  *     {
0691  *       g_object_unref (message);
0692  *       message = NULL;
0693  *     }
0694  *   return message;
0695  * }
0696  * ]|
0697  * Finally, a filter function may modify a message by copying it:
0698  * |[
0699  * static GDBusMessage *
0700  * modifying_filter (GDBusConnection *connection
0701  *                   GDBusMessage    *message,
0702  *                   gboolean         incoming,
0703  *                   gpointer         user_data)
0704  * {
0705  *   GDBusMessage *copy;
0706  *   GError *error;
0707  *
0708  *   error = NULL;
0709  *   copy = g_dbus_message_copy (message, &error);
0710  *   // handle @error being set
0711  *   g_object_unref (message);
0712  *
0713  *   // modify @copy
0714  *
0715  *   return copy;
0716  * }
0717  * ]|
0718  * If the returned #GDBusMessage is different from @message and cannot
0719  * be sent on @connection (it could use features, such as file
0720  * descriptors, not compatible with @connection), then a warning is
0721  * logged to standard error. Applications can
0722  * check this ahead of time using g_dbus_message_to_blob() passing a
0723  * #GDBusCapabilityFlags value obtained from @connection.
0724  *
0725  * Returns: (transfer full) (nullable): A #GDBusMessage that will be freed with
0726  * g_object_unref() or %NULL to drop the message. Passive filter
0727  * functions can simply return the passed @message object.
0728  *
0729  * Since: 2.26
0730  */
0731 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
0732                                                      GDBusMessage    *message,
0733                                                      gboolean         incoming,
0734                                                      gpointer         user_data);
0735 
0736 GIO_AVAILABLE_IN_ALL
0737 guint g_dbus_connection_add_filter (GDBusConnection            *connection,
0738                                     GDBusMessageFilterFunction  filter_function,
0739                                     gpointer                    user_data,
0740                                     GDestroyNotify              user_data_free_func);
0741 
0742 GIO_AVAILABLE_IN_ALL
0743 void  g_dbus_connection_remove_filter (GDBusConnection    *connection,
0744                                        guint               filter_id);
0745 
0746 /* ---------------------------------------------------------------------------------------------------- */
0747 
0748 
0749 G_END_DECLS
0750 
0751 #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!