/src/glib/gio/gdbusconnection.h
Line | Count | Source (jump to first uncovered line) |
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 | | g_clear_dbus_signal_subscription (guint *subscription_id_pointer, |
642 | | GDBusConnection *connection) |
643 | 0 | { |
644 | 0 | guint subscription_id; |
645 | 0 |
|
646 | 0 | /* Suppress "Not available before" warning */ |
647 | 0 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
648 | 0 | subscription_id = g_steal_handle_id (subscription_id_pointer); |
649 | 0 | G_GNUC_END_IGNORE_DEPRECATIONS |
650 | 0 |
|
651 | 0 | if (subscription_id > 0) |
652 | 0 | g_dbus_connection_signal_unsubscribe (connection, subscription_id); |
653 | 0 | } |
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__ */ |