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 */
410 : : gpointer padding[8];
411 : : };
412 : :
413 : : GIO_AVAILABLE_IN_ALL
414 : : guint g_dbus_connection_register_object (GDBusConnection *connection,
415 : : const gchar *object_path,
416 : : GDBusInterfaceInfo *interface_info,
417 : : const GDBusInterfaceVTable *vtable,
418 : : gpointer user_data,
419 : : GDestroyNotify user_data_free_func,
420 : : GError **error);
421 : : GIO_DEPRECATED_IN_2_84_FOR(g_dbus_connection_register_object_with_closures2)
422 : : guint g_dbus_connection_register_object_with_closures (GDBusConnection *connection,
423 : : const gchar *object_path,
424 : : GDBusInterfaceInfo *interface_info,
425 : : GClosure *method_call_closure,
426 : : GClosure *get_property_closure,
427 : : GClosure *set_property_closure,
428 : : GError **error);
429 : : GIO_AVAILABLE_IN_2_84
430 : : guint g_dbus_connection_register_object_with_closures2 (GDBusConnection *connection,
431 : : const gchar *object_path,
432 : : GDBusInterfaceInfo *interface_info,
433 : : GClosure *method_call_closure,
434 : : GClosure *get_property_closure,
435 : : GClosure *set_property_closure,
436 : : GError **error);
437 : : GIO_AVAILABLE_IN_ALL
438 : : gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
439 : : guint registration_id);
440 : :
441 : : /* ---------------------------------------------------------------------------------------------------- */
442 : :
443 : : /**
444 : : * GDBusSubtreeEnumerateFunc:
445 : : * @connection: A #GDBusConnection.
446 : : * @sender: The unique bus name of the remote caller.
447 : : * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
448 : : * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
449 : : *
450 : : * The type of the @enumerate function in #GDBusSubtreeVTable.
451 : : *
452 : : * This function is called when generating introspection data and also
453 : : * when preparing to dispatch incoming messages in the event that the
454 : : * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
455 : : * specified (ie: to verify that the object path is valid).
456 : : *
457 : : * Hierarchies are not supported; the items that you return should not
458 : : * contain the `/` character.
459 : : *
460 : : * The return value will be freed with g_strfreev().
461 : : *
462 : : * Returns: (array zero-terminated=1) (transfer full): A newly allocated array of strings for node names that are children of @object_path.
463 : : *
464 : : * Since: 2.26
465 : : */
466 : : typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
467 : : const gchar *sender,
468 : : const gchar *object_path,
469 : : gpointer user_data);
470 : :
471 : : /**
472 : : * GDBusSubtreeIntrospectFunc:
473 : : * @connection: A #GDBusConnection.
474 : : * @sender: The unique bus name of the remote caller.
475 : : * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
476 : : * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
477 : : * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
478 : : *
479 : : * The type of the @introspect function in #GDBusSubtreeVTable.
480 : : *
481 : : * Subtrees are flat. @node, if non-%NULL, is always exactly one
482 : : * segment of the object path (ie: it never contains a slash).
483 : : *
484 : : * This function should return %NULL to indicate that there is no object
485 : : * at this node.
486 : : *
487 : : * If this function returns non-%NULL, the return value is expected to
488 : : * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
489 : : * structures describing the interfaces implemented by @node. This
490 : : * array will have g_dbus_interface_info_unref() called on each item
491 : : * before being freed with g_free().
492 : : *
493 : : * The difference between returning %NULL and an array containing zero
494 : : * items is that the standard DBus interfaces will returned to the
495 : : * remote introspector in the empty array case, but not in the %NULL
496 : : * case.
497 : : *
498 : : * Returns: (array zero-terminated=1) (nullable) (transfer full): A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
499 : : *
500 : : * Since: 2.26
501 : : */
502 : : typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
503 : : const gchar *sender,
504 : : const gchar *object_path,
505 : : const gchar *node,
506 : : gpointer user_data);
507 : :
508 : : /**
509 : : * GDBusSubtreeDispatchFunc:
510 : : * @connection: A #GDBusConnection.
511 : : * @sender: The unique bus name of the remote caller.
512 : : * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
513 : : * @interface_name: The D-Bus interface name that the method call or property access is for.
514 : : * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
515 : : * @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable.
516 : : * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
517 : : *
518 : : * The type of the @dispatch function in #GDBusSubtreeVTable.
519 : : *
520 : : * Subtrees are flat. @node, if non-%NULL, is always exactly one
521 : : * segment of the object path (ie: it never contains a slash).
522 : : *
523 : : * Returns: (nullable): A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
524 : : *
525 : : * Since: 2.26
526 : : */
527 : : typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
528 : : const gchar *sender,
529 : : const gchar *object_path,
530 : : const gchar *interface_name,
531 : : const gchar *node,
532 : : gpointer *out_user_data,
533 : : gpointer user_data);
534 : :
535 : : /**
536 : : * GDBusSubtreeVTable:
537 : : * @enumerate: Function for enumerating child nodes.
538 : : * @introspect: Function for introspecting a child node.
539 : : * @dispatch: Function for dispatching a remote call on a child node.
540 : : *
541 : : * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
542 : : *
543 : : * Since: 2.26
544 : : */
545 : : struct _GDBusSubtreeVTable
546 : : {
547 : : GDBusSubtreeEnumerateFunc enumerate;
548 : : GDBusSubtreeIntrospectFunc introspect;
549 : : GDBusSubtreeDispatchFunc dispatch;
550 : :
551 : : /*< private >*/
552 : : /* Padding for future expansion */
553 : : gpointer padding[8];
554 : : };
555 : :
556 : : GIO_AVAILABLE_IN_ALL
557 : : guint g_dbus_connection_register_subtree (GDBusConnection *connection,
558 : : const gchar *object_path,
559 : : const GDBusSubtreeVTable *vtable,
560 : : GDBusSubtreeFlags flags,
561 : : gpointer user_data,
562 : : GDestroyNotify user_data_free_func,
563 : : GError **error);
564 : : GIO_AVAILABLE_IN_ALL
565 : : gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
566 : : guint registration_id);
567 : :
568 : : /* ---------------------------------------------------------------------------------------------------- */
569 : :
570 : : /**
571 : : * GDBusSignalCallback:
572 : : * @connection: A #GDBusConnection.
573 : : * @sender_name: (nullable): The unique bus name of the sender of the signal,
574 : : or %NULL on a peer-to-peer D-Bus connection.
575 : : * @object_path: The object path that the signal was emitted on.
576 : : * @interface_name: The name of the interface.
577 : : * @signal_name: The name of the signal.
578 : : * @parameters: A #GVariant tuple with parameters for the signal.
579 : : * @user_data: User data passed when subscribing to the signal.
580 : : *
581 : : * Signature for callback function used in g_dbus_connection_signal_subscribe().
582 : : *
583 : : * Since: 2.26
584 : : */
585 : : typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
586 : : const gchar *sender_name,
587 : : const gchar *object_path,
588 : : const gchar *interface_name,
589 : : const gchar *signal_name,
590 : : GVariant *parameters,
591 : : gpointer user_data);
592 : :
593 : : GIO_AVAILABLE_IN_ALL
594 : : guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
595 : : const gchar *sender,
596 : : const gchar *interface_name,
597 : : const gchar *member,
598 : : const gchar *object_path,
599 : : const gchar *arg0,
600 : : GDBusSignalFlags flags,
601 : : GDBusSignalCallback callback,
602 : : gpointer user_data,
603 : : GDestroyNotify user_data_free_func);
604 : : GIO_AVAILABLE_IN_ALL
605 : : void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
606 : : guint subscription_id);
607 : :
608 : : /**
609 : : * g_clear_dbus_signal_subscription: (skip)
610 : : * @subscription_id_pointer: (not optional) (inout): A pointer to either a
611 : : * subscription ID obtained from [method@Gio.DBusConnection.signal_subscribe],
612 : : * or zero.
613 : : * @connection: The connection from which the subscription ID was obtained.
614 : : * This pointer may be `NULL` or invalid, if the subscription ID is zero.
615 : : *
616 : : * If @subscription_id_pointer points to a nonzero subscription ID,
617 : : * unsubscribe from that D-Bus signal subscription as if via
618 : : * [method@Gio.DBusConnection.signal_unsubscribe].
619 : : *
620 : : * Also set the value pointed to by @subscription_id_pointer to zero,
621 : : * which signifies it’s no longer a valid subscription ID.
622 : : *
623 : : * This convenience function for C code helps to ensure that each signal
624 : : * subscription is unsubscribed exactly once, similar to
625 : : * [func@GObject.clear_object] and [func@GObject.clear_signal_handler].
626 : : *
627 : : * Since: 2.84
628 : : */
629 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
630 : : static inline void g_clear_dbus_signal_subscription (guint *subscription_id_pointer,
631 : : GDBusConnection *connection);
632 : :
633 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_84
634 : : static inline void
635 : 46 : g_clear_dbus_signal_subscription (guint *subscription_id_pointer,
636 : : GDBusConnection *connection)
637 : : {
638 : : guint subscription_id;
639 : :
640 : : /* Suppress "Not available before" warning */
641 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
642 : 46 : subscription_id = g_steal_handle_id (subscription_id_pointer);
643 : : G_GNUC_END_IGNORE_DEPRECATIONS
644 : :
645 : 46 : if (subscription_id > 0)
646 : 45 : g_dbus_connection_signal_unsubscribe (connection, subscription_id);
647 : 46 : }
648 : :
649 : : /* ---------------------------------------------------------------------------------------------------- */
650 : :
651 : : /**
652 : : * GDBusMessageFilterFunction:
653 : : * @connection: (transfer none): A #GDBusConnection.
654 : : * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
655 : : * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
656 : : * a message to be sent to the other peer.
657 : : * @user_data: User data passed when adding the filter.
658 : : *
659 : : * Signature for function used in g_dbus_connection_add_filter().
660 : : *
661 : : * A filter function is passed a #GDBusMessage and expected to return
662 : : * a #GDBusMessage too. Passive filter functions that don't modify the
663 : : * message can simply return the @message object:
664 : : * |[
665 : : * static GDBusMessage *
666 : : * passive_filter (GDBusConnection *connection
667 : : * GDBusMessage *message,
668 : : * gboolean incoming,
669 : : * gpointer user_data)
670 : : * {
671 : : * // inspect @message
672 : : * return message;
673 : : * }
674 : : * ]|
675 : : * Filter functions that wants to drop a message can simply return %NULL:
676 : : * |[
677 : : * static GDBusMessage *
678 : : * drop_filter (GDBusConnection *connection
679 : : * GDBusMessage *message,
680 : : * gboolean incoming,
681 : : * gpointer user_data)
682 : : * {
683 : : * if (should_drop_message)
684 : : * {
685 : : * g_object_unref (message);
686 : : * message = NULL;
687 : : * }
688 : : * return message;
689 : : * }
690 : : * ]|
691 : : * Finally, a filter function may modify a message by copying it:
692 : : * |[
693 : : * static GDBusMessage *
694 : : * modifying_filter (GDBusConnection *connection
695 : : * GDBusMessage *message,
696 : : * gboolean incoming,
697 : : * gpointer user_data)
698 : : * {
699 : : * GDBusMessage *copy;
700 : : * GError *error;
701 : : *
702 : : * error = NULL;
703 : : * copy = g_dbus_message_copy (message, &error);
704 : : * // handle @error being set
705 : : * g_object_unref (message);
706 : : *
707 : : * // modify @copy
708 : : *
709 : : * return copy;
710 : : * }
711 : : * ]|
712 : : * If the returned #GDBusMessage is different from @message and cannot
713 : : * be sent on @connection (it could use features, such as file
714 : : * descriptors, not compatible with @connection), then a warning is
715 : : * logged to standard error. Applications can
716 : : * check this ahead of time using g_dbus_message_to_blob() passing a
717 : : * #GDBusCapabilityFlags value obtained from @connection.
718 : : *
719 : : * Returns: (transfer full) (nullable): A #GDBusMessage that will be freed with
720 : : * g_object_unref() or %NULL to drop the message. Passive filter
721 : : * functions can simply return the passed @message object.
722 : : *
723 : : * Since: 2.26
724 : : */
725 : : typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
726 : : GDBusMessage *message,
727 : : gboolean incoming,
728 : : gpointer user_data);
729 : :
730 : : GIO_AVAILABLE_IN_ALL
731 : : guint g_dbus_connection_add_filter (GDBusConnection *connection,
732 : : GDBusMessageFilterFunction filter_function,
733 : : gpointer user_data,
734 : : GDestroyNotify user_data_free_func);
735 : :
736 : : GIO_AVAILABLE_IN_ALL
737 : : void g_dbus_connection_remove_filter (GDBusConnection *connection,
738 : : guint filter_id);
739 : :
740 : : /* ---------------------------------------------------------------------------------------------------- */
741 : :
742 : :
743 : : G_END_DECLS
744 : :
745 : : #endif /* __G_DBUS_CONNECTION_H__ */
|
