Branch data Line data Source code
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 : :
32 : : G_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 : :
38 : : GIO_AVAILABLE_IN_ALL
39 : : GType g_dbus_connection_get_type (void) G_GNUC_CONST;
40 : :
41 : : /* ---------------------------------------------------------------------------------------------------- */
42 : :
43 : : GIO_AVAILABLE_IN_ALL
44 : : void g_bus_get (GBusType bus_type,
45 : : GCancellable *cancellable,
46 : : GAsyncReadyCallback callback,
47 : : gpointer user_data);
48 : : GIO_AVAILABLE_IN_ALL
49 : : GDBusConnection *g_bus_get_finish (GAsyncResult *res,
50 : : GError **error);
51 : : GIO_AVAILABLE_IN_ALL
52 : : GDBusConnection *g_bus_get_sync (GBusType bus_type,
53 : : GCancellable *cancellable,
54 : : GError **error);
55 : :
56 : : /* ---------------------------------------------------------------------------------------------------- */
57 : :
58 : : GIO_AVAILABLE_IN_ALL
59 : : void 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);
66 : : GIO_AVAILABLE_IN_ALL
67 : : GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
68 : : GError **error);
69 : : GIO_AVAILABLE_IN_ALL
70 : : GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
71 : : const gchar *guid,
72 : : GDBusConnectionFlags flags,
73 : : GDBusAuthObserver *observer,
74 : : GCancellable *cancellable,
75 : : GError **error);
76 : :
77 : : GIO_AVAILABLE_IN_ALL
78 : : void 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);
84 : : GIO_AVAILABLE_IN_ALL
85 : : GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
86 : : GError **error);
87 : : GIO_AVAILABLE_IN_ALL
88 : : GDBusConnection *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 : :
96 : : GIO_AVAILABLE_IN_ALL
97 : : void g_dbus_connection_start_message_processing (GDBusConnection *connection);
98 : : GIO_AVAILABLE_IN_ALL
99 : : gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
100 : : GIO_AVAILABLE_IN_ALL
101 : : GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
102 : : GIO_AVAILABLE_IN_ALL
103 : : const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
104 : : GIO_AVAILABLE_IN_ALL
105 : : const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
106 : : GIO_AVAILABLE_IN_ALL
107 : : GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
108 : :
109 : : GIO_AVAILABLE_IN_2_34
110 : : guint32 g_dbus_connection_get_last_serial (GDBusConnection *connection);
111 : :
112 : : GIO_AVAILABLE_IN_ALL
113 : : gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
114 : : GIO_AVAILABLE_IN_ALL
115 : : void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
116 : : gboolean exit_on_close);
117 : : GIO_AVAILABLE_IN_ALL
118 : : GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
119 : : GIO_AVAILABLE_IN_2_60
120 : : GDBusConnectionFlags g_dbus_connection_get_flags (GDBusConnection *connection);
121 : :
122 : : /* ---------------------------------------------------------------------------------------------------- */
123 : :
124 : : GIO_AVAILABLE_IN_ALL
125 : : void g_dbus_connection_close (GDBusConnection *connection,
126 : : GCancellable *cancellable,
127 : : GAsyncReadyCallback callback,
128 : : gpointer user_data);
129 : : GIO_AVAILABLE_IN_ALL
130 : : gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
131 : : GAsyncResult *res,
132 : : GError **error);
133 : : GIO_AVAILABLE_IN_ALL
134 : : gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
135 : : GCancellable *cancellable,
136 : : GError **error);
137 : :
138 : : /* ---------------------------------------------------------------------------------------------------- */
139 : :
140 : : GIO_AVAILABLE_IN_ALL
141 : : void g_dbus_connection_flush (GDBusConnection *connection,
142 : : GCancellable *cancellable,
143 : : GAsyncReadyCallback callback,
144 : : gpointer user_data);
145 : : GIO_AVAILABLE_IN_ALL
146 : : gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
147 : : GAsyncResult *res,
148 : : GError **error);
149 : : GIO_AVAILABLE_IN_ALL
150 : : gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
151 : : GCancellable *cancellable,
152 : : GError **error);
153 : :
154 : : /* ---------------------------------------------------------------------------------------------------- */
155 : :
156 : : GIO_AVAILABLE_IN_ALL
157 : : gboolean g_dbus_connection_send_message (GDBusConnection *connection,
158 : : GDBusMessage *message,
159 : : GDBusSendMessageFlags flags,
160 : : volatile guint32 *out_serial,
161 : : GError **error);
162 : : GIO_AVAILABLE_IN_ALL
163 : : void 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);
171 : : GIO_AVAILABLE_IN_ALL
172 : : GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
173 : : GAsyncResult *res,
174 : : GError **error);
175 : : GIO_AVAILABLE_IN_ALL
176 : : GDBusMessage *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 : :
186 : : GIO_AVAILABLE_IN_ALL
187 : : gboolean 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);
194 : : GIO_AVAILABLE_IN_ALL
195 : : void 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);
207 : : GIO_AVAILABLE_IN_ALL
208 : : GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
209 : : GAsyncResult *res,
210 : : GError **error);
211 : : GIO_AVAILABLE_IN_ALL
212 : : GVariant *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 : :
226 : : GIO_AVAILABLE_IN_2_30
227 : : void 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);
240 : : GIO_AVAILABLE_IN_2_30
241 : : GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
242 : : GUnixFDList **out_fd_list,
243 : : GAsyncResult *res,
244 : : GError **error);
245 : : GIO_AVAILABLE_IN_2_30
246 : : GVariant *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 : : */
289 : : typedef 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 : : */
317 : : typedef 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 : : */
343 : : typedef 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 : : */
402 : : struct _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 : :
416 : : GIO_AVAILABLE_IN_ALL
417 : : guint 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);
424 : : GIO_DEPRECATED_IN_2_84_FOR(g_dbus_connection_register_object_with_closures2)
425 : : guint 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);
432 : : GIO_AVAILABLE_IN_2_84
433 : : guint 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);
440 : : GIO_AVAILABLE_IN_ALL
441 : : gboolean 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 : : */
469 : : typedef 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 : : */
505 : : typedef 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 : : */
530 : : typedef 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 : : */
548 : : struct _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 : :
562 : : GIO_AVAILABLE_IN_ALL
563 : : guint 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);
570 : : GIO_AVAILABLE_IN_ALL
571 : : gboolean 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 : : */
591 : : typedef 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 : :
599 : : GIO_AVAILABLE_IN_ALL
600 : : guint 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);
610 : : GIO_AVAILABLE_IN_ALL
611 : : void 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 : : */
635 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
636 : : static inline void g_clear_dbus_signal_subscription (guint *subscription_id_pointer,
637 : : GDBusConnection *connection);
638 : :
639 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
640 : : static inline void
641 : 46 : g_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 : 46 : subscription_id = g_steal_handle_id (subscription_id_pointer);
649 : : G_GNUC_END_IGNORE_DEPRECATIONS
650 : :
651 : 46 : if (subscription_id > 0)
652 : 45 : g_dbus_connection_signal_unsubscribe (connection, subscription_id);
653 : 46 : }
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 : : */
731 : : typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
732 : : GDBusMessage *message,
733 : : gboolean incoming,
734 : : gpointer user_data);
735 : :
736 : : GIO_AVAILABLE_IN_ALL
737 : : guint g_dbus_connection_add_filter (GDBusConnection *connection,
738 : : GDBusMessageFilterFunction filter_function,
739 : : gpointer user_data,
740 : : GDestroyNotify user_data_free_func);
741 : :
742 : : GIO_AVAILABLE_IN_ALL
743 : : void g_dbus_connection_remove_filter (GDBusConnection *connection,
744 : : guint filter_id);
745 : :
746 : : /* ---------------------------------------------------------------------------------------------------- */
747 : :
748 : :
749 : : G_END_DECLS
750 : :
751 : : #endif /* __G_DBUS_CONNECTION_H__ */
|
