1/* GDBus - GLib D-Bus Library
2 *
3 * Copyright (C) 2008-2010 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 *
20 * Author: David Zeuthen <davidz@redhat.com>
21 */
22
23#ifndef __G_DBUS_CONNECTION_H__
24#define __G_DBUS_CONNECTION_H__
25
26#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
27#error "Only <gio/gio.h> can be included directly."
28#endif
29
30#include <gio/giotypes.h>
31
32G_BEGIN_DECLS
33
34#define G_TYPE_DBUS_CONNECTION (g_dbus_connection_get_type ())
35#define G_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
36#define G_IS_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
37
38GIO_AVAILABLE_IN_ALL
39GType g_dbus_connection_get_type (void) G_GNUC_CONST;
40
41/* ---------------------------------------------------------------------------------------------------- */
42
43GIO_AVAILABLE_IN_ALL
44void g_bus_get (GBusType bus_type,
45 GCancellable *cancellable,
46 GAsyncReadyCallback callback,
47 gpointer user_data);
48GIO_AVAILABLE_IN_ALL
49GDBusConnection *g_bus_get_finish (GAsyncResult *res,
50 GError **error);
51GIO_AVAILABLE_IN_ALL
52GDBusConnection *g_bus_get_sync (GBusType bus_type,
53 GCancellable *cancellable,
54 GError **error);
55
56/* ---------------------------------------------------------------------------------------------------- */
57
58GIO_AVAILABLE_IN_ALL
59void g_dbus_connection_new (GIOStream *stream,
60 const gchar *guid,
61 GDBusConnectionFlags flags,
62 GDBusAuthObserver *observer,
63 GCancellable *cancellable,
64 GAsyncReadyCallback callback,
65 gpointer user_data);
66GIO_AVAILABLE_IN_ALL
67GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
68 GError **error);
69GIO_AVAILABLE_IN_ALL
70GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
71 const gchar *guid,
72 GDBusConnectionFlags flags,
73 GDBusAuthObserver *observer,
74 GCancellable *cancellable,
75 GError **error);
76
77GIO_AVAILABLE_IN_ALL
78void g_dbus_connection_new_for_address (const gchar *address,
79 GDBusConnectionFlags flags,
80 GDBusAuthObserver *observer,
81 GCancellable *cancellable,
82 GAsyncReadyCallback callback,
83 gpointer user_data);
84GIO_AVAILABLE_IN_ALL
85GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
86 GError **error);
87GIO_AVAILABLE_IN_ALL
88GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
89 GDBusConnectionFlags flags,
90 GDBusAuthObserver *observer,
91 GCancellable *cancellable,
92 GError **error);
93
94/* ---------------------------------------------------------------------------------------------------- */
95
96GIO_AVAILABLE_IN_ALL
97void g_dbus_connection_start_message_processing (GDBusConnection *connection);
98GIO_AVAILABLE_IN_ALL
99gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
100GIO_AVAILABLE_IN_ALL
101GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
102GIO_AVAILABLE_IN_ALL
103const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
104GIO_AVAILABLE_IN_ALL
105const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
106GIO_AVAILABLE_IN_ALL
107GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
108
109GIO_AVAILABLE_IN_2_34
110guint32 g_dbus_connection_get_last_serial (GDBusConnection *connection);
111
112GIO_AVAILABLE_IN_ALL
113gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
114GIO_AVAILABLE_IN_ALL
115void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
116 gboolean exit_on_close);
117GIO_AVAILABLE_IN_ALL
118GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
119GIO_AVAILABLE_IN_2_60
120GDBusConnectionFlags g_dbus_connection_get_flags (GDBusConnection *connection);
121
122/* ---------------------------------------------------------------------------------------------------- */
123
124GIO_AVAILABLE_IN_ALL
125void g_dbus_connection_close (GDBusConnection *connection,
126 GCancellable *cancellable,
127 GAsyncReadyCallback callback,
128 gpointer user_data);
129GIO_AVAILABLE_IN_ALL
130gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
131 GAsyncResult *res,
132 GError **error);
133GIO_AVAILABLE_IN_ALL
134gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
135 GCancellable *cancellable,
136 GError **error);
137
138/* ---------------------------------------------------------------------------------------------------- */
139
140GIO_AVAILABLE_IN_ALL
141void g_dbus_connection_flush (GDBusConnection *connection,
142 GCancellable *cancellable,
143 GAsyncReadyCallback callback,
144 gpointer user_data);
145GIO_AVAILABLE_IN_ALL
146gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
147 GAsyncResult *res,
148 GError **error);
149GIO_AVAILABLE_IN_ALL
150gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
151 GCancellable *cancellable,
152 GError **error);
153
154/* ---------------------------------------------------------------------------------------------------- */
155
156GIO_AVAILABLE_IN_ALL
157gboolean g_dbus_connection_send_message (GDBusConnection *connection,
158 GDBusMessage *message,
159 GDBusSendMessageFlags flags,
160 volatile guint32 *out_serial,
161 GError **error);
162GIO_AVAILABLE_IN_ALL
163void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
164 GDBusMessage *message,
165 GDBusSendMessageFlags flags,
166 gint timeout_msec,
167 volatile guint32 *out_serial,
168 GCancellable *cancellable,
169 GAsyncReadyCallback callback,
170 gpointer user_data);
171GIO_AVAILABLE_IN_ALL
172GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
173 GAsyncResult *res,
174 GError **error);
175GIO_AVAILABLE_IN_ALL
176GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
177 GDBusMessage *message,
178 GDBusSendMessageFlags flags,
179 gint timeout_msec,
180 volatile guint32 *out_serial,
181 GCancellable *cancellable,
182 GError **error);
183
184/* ---------------------------------------------------------------------------------------------------- */
185
186GIO_AVAILABLE_IN_ALL
187gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
188 const gchar *destination_bus_name,
189 const gchar *object_path,
190 const gchar *interface_name,
191 const gchar *signal_name,
192 GVariant *parameters,
193 GError **error);
194GIO_AVAILABLE_IN_ALL
195void g_dbus_connection_call (GDBusConnection *connection,
196 const gchar *bus_name,
197 const gchar *object_path,
198 const gchar *interface_name,
199 const gchar *method_name,
200 GVariant *parameters,
201 const GVariantType *reply_type,
202 GDBusCallFlags flags,
203 gint timeout_msec,
204 GCancellable *cancellable,
205 GAsyncReadyCallback callback,
206 gpointer user_data);
207GIO_AVAILABLE_IN_ALL
208GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
209 GAsyncResult *res,
210 GError **error);
211GIO_AVAILABLE_IN_ALL
212GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
213 const gchar *bus_name,
214 const gchar *object_path,
215 const gchar *interface_name,
216 const gchar *method_name,
217 GVariant *parameters,
218 const GVariantType *reply_type,
219 GDBusCallFlags flags,
220 gint timeout_msec,
221 GCancellable *cancellable,
222 GError **error);
223
224#ifdef G_OS_UNIX
225
226GIO_AVAILABLE_IN_2_30
227void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection,
228 const gchar *bus_name,
229 const gchar *object_path,
230 const gchar *interface_name,
231 const gchar *method_name,
232 GVariant *parameters,
233 const GVariantType *reply_type,
234 GDBusCallFlags flags,
235 gint timeout_msec,
236 GUnixFDList *fd_list,
237 GCancellable *cancellable,
238 GAsyncReadyCallback callback,
239 gpointer user_data);
240GIO_AVAILABLE_IN_2_30
241GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
242 GUnixFDList **out_fd_list,
243 GAsyncResult *res,
244 GError **error);
245GIO_AVAILABLE_IN_2_30
246GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection,
247 const gchar *bus_name,
248 const gchar *object_path,
249 const gchar *interface_name,
250 const gchar *method_name,
251 GVariant *parameters,
252 const GVariantType *reply_type,
253 GDBusCallFlags flags,
254 gint timeout_msec,
255 GUnixFDList *fd_list,
256 GUnixFDList **out_fd_list,
257 GCancellable *cancellable,
258 GError **error);
259
260#endif /* G_OS_UNIX */
261
262/* ---------------------------------------------------------------------------------------------------- */
263
264
265/**
266 * GDBusInterfaceMethodCallFunc:
267 * @connection: A #GDBusConnection.
268 * @sender: (nullable): The unique bus name of the remote caller, or `NULL` if
269 * not specified by the caller, e.g. on peer-to-peer connections.
270 * @object_path: The object path that the method was invoked on.
271 * @interface_name: (nullable): The D-Bus interface name the method was invoked on,
272 * or `NULL` if not specified by the sender.
273 * @method_name: The name of the method that was invoked.
274 * @parameters: A #GVariant tuple with parameters.
275 * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error.
276 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
277 *
278 * The type of the @method_call function in #GDBusInterfaceVTable.
279 *
280 * @interface_name may be `NULL` if not specified by the sender, although it’s
281 * encouraged for the sender to set it. If unset, and the object has only one
282 * method (across all interfaces) matching @method_name, that method is invoked.
283 * Otherwise, behaviour is implementation defined. See the
284 * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method).
285 * It is recommended to return [error@Gio.DBusError.UNKNOWN_METHOD].
286 *
287 * Since: 2.26
288 */
289typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
290 const gchar *sender,
291 const gchar *object_path,
292 const gchar *interface_name,
293 const gchar *method_name,
294 GVariant *parameters,
295 GDBusMethodInvocation *invocation,
296 gpointer user_data);
297
298/**
299 * GDBusInterfaceGetPropertyFunc:
300 * @connection: A #GDBusConnection.
301 * @sender: (nullable): The unique bus name of the remote caller or %NULL if
302 * not specified by the caller, e.g. on peer-to-peer connections.
303 * @object_path: The object path that the method was invoked on.
304 * @interface_name: The D-Bus interface name for the property.
305 * @property_name: The name of the property to get the value of.
306 * @error: Return location for error.
307 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
308 *
309 * The type of the @get_property function in #GDBusInterfaceVTable.
310 *
311 * Returns: A #GVariant with the value for @property_name or %NULL if
312 * @error is set. If the returned #GVariant is floating, it is
313 * consumed - otherwise its reference count is decreased by one.
314 *
315 * Since: 2.26
316 */
317typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
318 const gchar *sender,
319 const gchar *object_path,
320 const gchar *interface_name,
321 const gchar *property_name,
322 GError **error,
323 gpointer user_data);
324
325/**
326 * GDBusInterfaceSetPropertyFunc:
327 * @connection: A #GDBusConnection.
328 * @sender: (nullable): The unique bus name of the remote caller or %NULL if
329 * not specified by the caller, e.g. on peer-to-peer connections.
330 * @object_path: The object path that the method was invoked on.
331 * @interface_name: The D-Bus interface name for the property.
332 * @property_name: The name of the property to get the value of.
333 * @value: The value to set the property to.
334 * @error: Return location for error.
335 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
336 *
337 * The type of the @set_property function in #GDBusInterfaceVTable.
338 *
339 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
340 *
341 * Since: 2.26
342 */
343typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
344 const gchar *sender,
345 const gchar *object_path,
346 const gchar *interface_name,
347 const gchar *property_name,
348 GVariant *value,
349 GError **error,
350 gpointer user_data);
351
352/**
353 * GDBusInterfaceVTable:
354 * @method_call: Function for handling incoming method calls.
355 * @get_property: Function for getting a property.
356 * @set_property: Function for setting a property.
357 *
358 * Virtual table for handling properties and method calls for a D-Bus
359 * interface.
360 *
361 * Since 2.38, if you want to handle getting/setting D-Bus properties
362 * asynchronously, give %NULL as your get_property() or set_property()
363 * function. The D-Bus call will be directed to your @method_call function,
364 * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
365 *
366 * Ownership of the #GDBusMethodInvocation object passed to the
367 * method_call() function is transferred to your handler; you must
368 * call one of the methods of #GDBusMethodInvocation to return a reply
369 * (possibly empty), or an error. These functions also take ownership
370 * of the passed-in invocation object, so unless the invocation
371 * object has otherwise been referenced, it will be then be freed.
372 * Calling one of these functions may be done within your
373 * method_call() implementation but it also can be done at a later
374 * point to handle the method asynchronously.
375 *
376 * The usual checks on the validity of the calls is performed. For
377 * `Get` calls, an error is automatically returned if the property does
378 * not exist or the permissions do not allow access. The same checks are
379 * performed for `Set` calls, and the provided value is also checked for
380 * being the correct type.
381 *
382 * For both `Get` and `Set` calls, the #GDBusMethodInvocation
383 * passed to the @method_call handler can be queried with
384 * g_dbus_method_invocation_get_property_info() to get a pointer
385 * to the #GDBusPropertyInfo of the property.
386 *
387 * If you have readable properties specified in your interface info,
388 * you must ensure that you either provide a non-%NULL @get_property()
389 * function or provide implementations of both the `Get` and `GetAll`
390 * methods on org.freedesktop.DBus.Properties interface in your @method_call
391 * function. Note that the required return type of the `Get` call is
392 * `(v)`, not the type of the property. `GetAll` expects a return value
393 * of type `a{sv}`.
394 *
395 * If you have writable properties specified in your interface info,
396 * you must ensure that you either provide a non-%NULL @set_property()
397 * function or provide an implementation of the `Set` call. If implementing
398 * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
399 *
400 * Since: 2.26
401 */
402struct _GDBusInterfaceVTable
403{
404 GDBusInterfaceMethodCallFunc method_call;
405 GDBusInterfaceGetPropertyFunc get_property;
406 GDBusInterfaceSetPropertyFunc set_property;
407
408 /*< private >*/
409 /* Padding for future expansion - also remember to update
410 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
411 * changing this.
412 */
413 gpointer padding[8];
414};
415
416GIO_AVAILABLE_IN_ALL
417guint g_dbus_connection_register_object (GDBusConnection *connection,
418 const gchar *object_path,
419 GDBusInterfaceInfo *interface_info,
420 const GDBusInterfaceVTable *vtable,
421 gpointer user_data,
422 GDestroyNotify user_data_free_func,
423 GError **error);
424GIO_DEPRECATED_IN_2_84_FOR(g_dbus_connection_register_object_with_closures2)
425guint g_dbus_connection_register_object_with_closures (GDBusConnection *connection,
426 const gchar *object_path,
427 GDBusInterfaceInfo *interface_info,
428 GClosure *method_call_closure,
429 GClosure *get_property_closure,
430 GClosure *set_property_closure,
431 GError **error);
432GIO_AVAILABLE_IN_2_84
433guint g_dbus_connection_register_object_with_closures2 (GDBusConnection *connection,
434 const gchar *object_path,
435 GDBusInterfaceInfo *interface_info,
436 GClosure *method_call_closure,
437 GClosure *get_property_closure,
438 GClosure *set_property_closure,
439 GError **error);
440GIO_AVAILABLE_IN_ALL
441gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
442 guint registration_id);
443
444/* ---------------------------------------------------------------------------------------------------- */
445
446/**
447 * GDBusSubtreeEnumerateFunc:
448 * @connection: A #GDBusConnection.
449 * @sender: The unique bus name of the remote caller.
450 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
451 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
452 *
453 * The type of the @enumerate function in #GDBusSubtreeVTable.
454 *
455 * This function is called when generating introspection data and also
456 * when preparing to dispatch incoming messages in the event that the
457 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
458 * specified (ie: to verify that the object path is valid).
459 *
460 * Hierarchies are not supported; the items that you return should not
461 * contain the `/` character.
462 *
463 * The return value will be freed with g_strfreev().
464 *
465 * Returns: (array zero-terminated=1) (transfer full): A newly allocated array of strings for node names that are children of @object_path.
466 *
467 * Since: 2.26
468 */
469typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
470 const gchar *sender,
471 const gchar *object_path,
472 gpointer user_data);
473
474/**
475 * GDBusSubtreeIntrospectFunc:
476 * @connection: A #GDBusConnection.
477 * @sender: The unique bus name of the remote caller.
478 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
479 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
480 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
481 *
482 * The type of the @introspect function in #GDBusSubtreeVTable.
483 *
484 * Subtrees are flat. @node, if non-%NULL, is always exactly one
485 * segment of the object path (ie: it never contains a slash).
486 *
487 * This function should return %NULL to indicate that there is no object
488 * at this node.
489 *
490 * If this function returns non-%NULL, the return value is expected to
491 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
492 * structures describing the interfaces implemented by @node. This
493 * array will have g_dbus_interface_info_unref() called on each item
494 * before being freed with g_free().
495 *
496 * The difference between returning %NULL and an array containing zero
497 * items is that the standard DBus interfaces will returned to the
498 * remote introspector in the empty array case, but not in the %NULL
499 * case.
500 *
501 * Returns: (array zero-terminated=1) (nullable) (transfer full): A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
502 *
503 * Since: 2.26
504 */
505typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
506 const gchar *sender,
507 const gchar *object_path,
508 const gchar *node,
509 gpointer user_data);
510
511/**
512 * GDBusSubtreeDispatchFunc:
513 * @connection: A #GDBusConnection.
514 * @sender: The unique bus name of the remote caller.
515 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
516 * @interface_name: The D-Bus interface name that the method call or property access is for.
517 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
518 * @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable.
519 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
520 *
521 * The type of the @dispatch function in #GDBusSubtreeVTable.
522 *
523 * Subtrees are flat. @node, if non-%NULL, is always exactly one
524 * segment of the object path (ie: it never contains a slash).
525 *
526 * Returns: (nullable): A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
527 *
528 * Since: 2.26
529 */
530typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
531 const gchar *sender,
532 const gchar *object_path,
533 const gchar *interface_name,
534 const gchar *node,
535 gpointer *out_user_data,
536 gpointer user_data);
537
538/**
539 * GDBusSubtreeVTable:
540 * @enumerate: Function for enumerating child nodes.
541 * @introspect: Function for introspecting a child node.
542 * @dispatch: Function for dispatching a remote call on a child node.
543 *
544 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
545 *
546 * Since: 2.26
547 */
548struct _GDBusSubtreeVTable
549{
550 GDBusSubtreeEnumerateFunc enumerate;
551 GDBusSubtreeIntrospectFunc introspect;
552 GDBusSubtreeDispatchFunc dispatch;
553
554 /*< private >*/
555 /* Padding for future expansion - also remember to update
556 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
557 * changing this.
558 */
559 gpointer padding[8];
560};
561
562GIO_AVAILABLE_IN_ALL
563guint g_dbus_connection_register_subtree (GDBusConnection *connection,
564 const gchar *object_path,
565 const GDBusSubtreeVTable *vtable,
566 GDBusSubtreeFlags flags,
567 gpointer user_data,
568 GDestroyNotify user_data_free_func,
569 GError **error);
570GIO_AVAILABLE_IN_ALL
571gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
572 guint registration_id);
573
574/* ---------------------------------------------------------------------------------------------------- */
575
576/**
577 * GDBusSignalCallback:
578 * @connection: A #GDBusConnection.
579 * @sender_name: (nullable): The unique bus name of the sender of the signal,
580 or %NULL on a peer-to-peer D-Bus connection.
581 * @object_path: The object path that the signal was emitted on.
582 * @interface_name: The name of the interface.
583 * @signal_name: The name of the signal.
584 * @parameters: A #GVariant tuple with parameters for the signal.
585 * @user_data: User data passed when subscribing to the signal.
586 *
587 * Signature for callback function used in g_dbus_connection_signal_subscribe().
588 *
589 * Since: 2.26
590 */
591typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
592 const gchar *sender_name,
593 const gchar *object_path,
594 const gchar *interface_name,
595 const gchar *signal_name,
596 GVariant *parameters,
597 gpointer user_data);
598
599GIO_AVAILABLE_IN_ALL
600guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
601 const gchar *sender,
602 const gchar *interface_name,
603 const gchar *member,
604 const gchar *object_path,
605 const gchar *arg0,
606 GDBusSignalFlags flags,
607 GDBusSignalCallback callback,
608 gpointer user_data,
609 GDestroyNotify user_data_free_func);
610GIO_AVAILABLE_IN_ALL
611void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
612 guint subscription_id);
613
614/**
615 * g_clear_dbus_signal_subscription: (skip)
616 * @subscription_id_pointer: (not optional) (inout): A pointer to either a
617 * subscription ID obtained from [method@Gio.DBusConnection.signal_subscribe],
618 * or zero.
619 * @connection: The connection from which the subscription ID was obtained.
620 * This pointer may be `NULL` or invalid, if the subscription ID is zero.
621 *
622 * If @subscription_id_pointer points to a nonzero subscription ID,
623 * unsubscribe from that D-Bus signal subscription as if via
624 * [method@Gio.DBusConnection.signal_unsubscribe].
625 *
626 * Also set the value pointed to by @subscription_id_pointer to zero,
627 * which signifies it’s no longer a valid subscription ID.
628 *
629 * This convenience function for C code helps to ensure that each signal
630 * subscription is unsubscribed exactly once, similar to
631 * [func@GObject.clear_object] and [func@GObject.clear_signal_handler].
632 *
633 * Since: 2.84
634 */
635GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
636static inline void g_clear_dbus_signal_subscription (guint *subscription_id_pointer,
637 GDBusConnection *connection);
638
639GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
640static inline void
641g_clear_dbus_signal_subscription (guint *subscription_id_pointer,
642 GDBusConnection *connection)
643{
644 guint subscription_id;
645
646 /* Suppress "Not available before" warning */
647 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
648 subscription_id = g_steal_handle_id (handle_pointer: subscription_id_pointer);
649 G_GNUC_END_IGNORE_DEPRECATIONS
650
651 if (subscription_id > 0)
652 g_dbus_connection_signal_unsubscribe (connection, subscription_id);
653}
654
655/* ---------------------------------------------------------------------------------------------------- */
656
657/**
658 * GDBusMessageFilterFunction:
659 * @connection: (transfer none): A #GDBusConnection.
660 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
661 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
662 * a message to be sent to the other peer.
663 * @user_data: User data passed when adding the filter.
664 *
665 * Signature for function used in g_dbus_connection_add_filter().
666 *
667 * A filter function is passed a #GDBusMessage and expected to return
668 * a #GDBusMessage too. Passive filter functions that don't modify the
669 * message can simply return the @message object:
670 * |[
671 * static GDBusMessage *
672 * passive_filter (GDBusConnection *connection
673 * GDBusMessage *message,
674 * gboolean incoming,
675 * gpointer user_data)
676 * {
677 * // inspect @message
678 * return message;
679 * }
680 * ]|
681 * Filter functions that wants to drop a message can simply return %NULL:
682 * |[
683 * static GDBusMessage *
684 * drop_filter (GDBusConnection *connection
685 * GDBusMessage *message,
686 * gboolean incoming,
687 * gpointer user_data)
688 * {
689 * if (should_drop_message)
690 * {
691 * g_object_unref (message);
692 * message = NULL;
693 * }
694 * return message;
695 * }
696 * ]|
697 * Finally, a filter function may modify a message by copying it:
698 * |[
699 * static GDBusMessage *
700 * modifying_filter (GDBusConnection *connection
701 * GDBusMessage *message,
702 * gboolean incoming,
703 * gpointer user_data)
704 * {
705 * GDBusMessage *copy;
706 * GError *error;
707 *
708 * error = NULL;
709 * copy = g_dbus_message_copy (message, &error);
710 * // handle @error being set
711 * g_object_unref (message);
712 *
713 * // modify @copy
714 *
715 * return copy;
716 * }
717 * ]|
718 * If the returned #GDBusMessage is different from @message and cannot
719 * be sent on @connection (it could use features, such as file
720 * descriptors, not compatible with @connection), then a warning is
721 * logged to standard error. Applications can
722 * check this ahead of time using g_dbus_message_to_blob() passing a
723 * #GDBusCapabilityFlags value obtained from @connection.
724 *
725 * Returns: (transfer full) (nullable): A #GDBusMessage that will be freed with
726 * g_object_unref() or %NULL to drop the message. Passive filter
727 * functions can simply return the passed @message object.
728 *
729 * Since: 2.26
730 */
731typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
732 GDBusMessage *message,
733 gboolean incoming,
734 gpointer user_data);
735
736GIO_AVAILABLE_IN_ALL
737guint g_dbus_connection_add_filter (GDBusConnection *connection,
738 GDBusMessageFilterFunction filter_function,
739 gpointer user_data,
740 GDestroyNotify user_data_free_func);
741
742GIO_AVAILABLE_IN_ALL
743void g_dbus_connection_remove_filter (GDBusConnection *connection,
744 guint filter_id);
745
746/* ---------------------------------------------------------------------------------------------------- */
747
748
749G_END_DECLS
750
751#endif /* __G_DBUS_CONNECTION_H__ */
752