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

source code of include/glib-2.0/gio/gdbusconnection.h