1 /* GDBus - GLib D-Bus Library
3 * Copyright (C) 2008-2010 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: David Zeuthen <davidz@redhat.com>
21 #ifndef __G_DBUS_CONNECTION_H__
22 #define __G_DBUS_CONNECTION_H__
24 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
25 #error "Only <gio/gio.h> can be included directly."
28 #include <gio/giotypes.h>
32 #define G_TYPE_DBUS_CONNECTION (g_dbus_connection_get_type ())
33 #define G_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
34 #define G_IS_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
37 GType
g_dbus_connection_get_type (void) G_GNUC_CONST
;
39 /* ---------------------------------------------------------------------------------------------------- */
42 void g_bus_get (GBusType bus_type
,
43 GCancellable
*cancellable
,
44 GAsyncReadyCallback callback
,
47 GDBusConnection
*g_bus_get_finish (GAsyncResult
*res
,
50 GDBusConnection
*g_bus_get_sync (GBusType bus_type
,
51 GCancellable
*cancellable
,
54 /* ---------------------------------------------------------------------------------------------------- */
57 void g_dbus_connection_new (GIOStream
*stream
,
59 GDBusConnectionFlags flags
,
60 GDBusAuthObserver
*observer
,
61 GCancellable
*cancellable
,
62 GAsyncReadyCallback callback
,
65 GDBusConnection
*g_dbus_connection_new_finish (GAsyncResult
*res
,
68 GDBusConnection
*g_dbus_connection_new_sync (GIOStream
*stream
,
70 GDBusConnectionFlags flags
,
71 GDBusAuthObserver
*observer
,
72 GCancellable
*cancellable
,
76 void g_dbus_connection_new_for_address (const gchar
*address
,
77 GDBusConnectionFlags flags
,
78 GDBusAuthObserver
*observer
,
79 GCancellable
*cancellable
,
80 GAsyncReadyCallback callback
,
83 GDBusConnection
*g_dbus_connection_new_for_address_finish (GAsyncResult
*res
,
86 GDBusConnection
*g_dbus_connection_new_for_address_sync (const gchar
*address
,
87 GDBusConnectionFlags flags
,
88 GDBusAuthObserver
*observer
,
89 GCancellable
*cancellable
,
92 /* ---------------------------------------------------------------------------------------------------- */
95 void g_dbus_connection_start_message_processing (GDBusConnection
*connection
);
97 gboolean
g_dbus_connection_is_closed (GDBusConnection
*connection
);
99 GIOStream
*g_dbus_connection_get_stream (GDBusConnection
*connection
);
100 GLIB_AVAILABLE_IN_ALL
101 const gchar
*g_dbus_connection_get_guid (GDBusConnection
*connection
);
102 GLIB_AVAILABLE_IN_ALL
103 const gchar
*g_dbus_connection_get_unique_name (GDBusConnection
*connection
);
104 GLIB_AVAILABLE_IN_ALL
105 GCredentials
*g_dbus_connection_get_peer_credentials (GDBusConnection
*connection
);
107 GLIB_AVAILABLE_IN_2_34
108 guint32
g_dbus_connection_get_last_serial (GDBusConnection
*connection
);
110 GLIB_AVAILABLE_IN_ALL
111 gboolean
g_dbus_connection_get_exit_on_close (GDBusConnection
*connection
);
112 GLIB_AVAILABLE_IN_ALL
113 void g_dbus_connection_set_exit_on_close (GDBusConnection
*connection
,
114 gboolean exit_on_close
);
115 GLIB_AVAILABLE_IN_ALL
116 GDBusCapabilityFlags
g_dbus_connection_get_capabilities (GDBusConnection
*connection
);
118 /* ---------------------------------------------------------------------------------------------------- */
120 GLIB_AVAILABLE_IN_ALL
121 void g_dbus_connection_close (GDBusConnection
*connection
,
122 GCancellable
*cancellable
,
123 GAsyncReadyCallback callback
,
125 GLIB_AVAILABLE_IN_ALL
126 gboolean
g_dbus_connection_close_finish (GDBusConnection
*connection
,
129 GLIB_AVAILABLE_IN_ALL
130 gboolean
g_dbus_connection_close_sync (GDBusConnection
*connection
,
131 GCancellable
*cancellable
,
134 /* ---------------------------------------------------------------------------------------------------- */
136 GLIB_AVAILABLE_IN_ALL
137 void g_dbus_connection_flush (GDBusConnection
*connection
,
138 GCancellable
*cancellable
,
139 GAsyncReadyCallback callback
,
141 GLIB_AVAILABLE_IN_ALL
142 gboolean
g_dbus_connection_flush_finish (GDBusConnection
*connection
,
145 GLIB_AVAILABLE_IN_ALL
146 gboolean
g_dbus_connection_flush_sync (GDBusConnection
*connection
,
147 GCancellable
*cancellable
,
150 /* ---------------------------------------------------------------------------------------------------- */
152 GLIB_AVAILABLE_IN_ALL
153 gboolean
g_dbus_connection_send_message (GDBusConnection
*connection
,
154 GDBusMessage
*message
,
155 GDBusSendMessageFlags flags
,
156 volatile guint32
*out_serial
,
158 GLIB_AVAILABLE_IN_ALL
159 void g_dbus_connection_send_message_with_reply (GDBusConnection
*connection
,
160 GDBusMessage
*message
,
161 GDBusSendMessageFlags flags
,
163 volatile guint32
*out_serial
,
164 GCancellable
*cancellable
,
165 GAsyncReadyCallback callback
,
167 GLIB_AVAILABLE_IN_ALL
168 GDBusMessage
*g_dbus_connection_send_message_with_reply_finish (GDBusConnection
*connection
,
171 GLIB_AVAILABLE_IN_ALL
172 GDBusMessage
*g_dbus_connection_send_message_with_reply_sync (GDBusConnection
*connection
,
173 GDBusMessage
*message
,
174 GDBusSendMessageFlags flags
,
176 volatile guint32
*out_serial
,
177 GCancellable
*cancellable
,
180 /* ---------------------------------------------------------------------------------------------------- */
182 GLIB_AVAILABLE_IN_ALL
183 gboolean
g_dbus_connection_emit_signal (GDBusConnection
*connection
,
184 const gchar
*destination_bus_name
,
185 const gchar
*object_path
,
186 const gchar
*interface_name
,
187 const gchar
*signal_name
,
188 GVariant
*parameters
,
190 GLIB_AVAILABLE_IN_ALL
191 void g_dbus_connection_call (GDBusConnection
*connection
,
192 const gchar
*bus_name
,
193 const gchar
*object_path
,
194 const gchar
*interface_name
,
195 const gchar
*method_name
,
196 GVariant
*parameters
,
197 const GVariantType
*reply_type
,
198 GDBusCallFlags flags
,
200 GCancellable
*cancellable
,
201 GAsyncReadyCallback callback
,
203 GLIB_AVAILABLE_IN_ALL
204 GVariant
*g_dbus_connection_call_finish (GDBusConnection
*connection
,
207 GLIB_AVAILABLE_IN_ALL
208 GVariant
*g_dbus_connection_call_sync (GDBusConnection
*connection
,
209 const gchar
*bus_name
,
210 const gchar
*object_path
,
211 const gchar
*interface_name
,
212 const gchar
*method_name
,
213 GVariant
*parameters
,
214 const GVariantType
*reply_type
,
215 GDBusCallFlags flags
,
217 GCancellable
*cancellable
,
219 GLIB_AVAILABLE_IN_2_30
220 void g_dbus_connection_call_with_unix_fd_list (GDBusConnection
*connection
,
221 const gchar
*bus_name
,
222 const gchar
*object_path
,
223 const gchar
*interface_name
,
224 const gchar
*method_name
,
225 GVariant
*parameters
,
226 const GVariantType
*reply_type
,
227 GDBusCallFlags flags
,
229 GUnixFDList
*fd_list
,
230 GCancellable
*cancellable
,
231 GAsyncReadyCallback callback
,
233 GLIB_AVAILABLE_IN_2_30
234 GVariant
*g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection
*connection
,
235 GUnixFDList
**out_fd_list
,
238 GLIB_AVAILABLE_IN_2_30
239 GVariant
*g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection
*connection
,
240 const gchar
*bus_name
,
241 const gchar
*object_path
,
242 const gchar
*interface_name
,
243 const gchar
*method_name
,
244 GVariant
*parameters
,
245 const GVariantType
*reply_type
,
246 GDBusCallFlags flags
,
248 GUnixFDList
*fd_list
,
249 GUnixFDList
**out_fd_list
,
250 GCancellable
*cancellable
,
253 /* ---------------------------------------------------------------------------------------------------- */
257 * GDBusInterfaceMethodCallFunc:
258 * @connection: A #GDBusConnection.
259 * @sender: The unique bus name of the remote caller.
260 * @object_path: The object path that the method was invoked on.
261 * @interface_name: The D-Bus interface name the method was invoked on.
262 * @method_name: The name of the method that was invoked.
263 * @parameters: A #GVariant tuple with parameters.
264 * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error.
265 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
267 * The type of the @method_call function in #GDBusInterfaceVTable.
271 typedef void (*GDBusInterfaceMethodCallFunc
) (GDBusConnection
*connection
,
273 const gchar
*object_path
,
274 const gchar
*interface_name
,
275 const gchar
*method_name
,
276 GVariant
*parameters
,
277 GDBusMethodInvocation
*invocation
,
281 * GDBusInterfaceGetPropertyFunc:
282 * @connection: A #GDBusConnection.
283 * @sender: The unique bus name of the remote caller.
284 * @object_path: The object path that the method was invoked on.
285 * @interface_name: The D-Bus interface name for the property.
286 * @property_name: The name of the property to get the value of.
287 * @error: Return location for error.
288 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
290 * The type of the @get_property function in #GDBusInterfaceVTable.
292 * Returns: A #GVariant with the value for @property_name or %NULL if
293 * @error is set. If the returned #GVariant is floating, it is
294 * consumed - otherwise its reference count is decreased by one.
298 typedef GVariant
*(*GDBusInterfaceGetPropertyFunc
) (GDBusConnection
*connection
,
300 const gchar
*object_path
,
301 const gchar
*interface_name
,
302 const gchar
*property_name
,
307 * GDBusInterfaceSetPropertyFunc:
308 * @connection: A #GDBusConnection.
309 * @sender: The unique bus name of the remote caller.
310 * @object_path: The object path that the method was invoked on.
311 * @interface_name: The D-Bus interface name for the property.
312 * @property_name: The name of the property to get the value of.
313 * @value: The value to set the property to.
314 * @error: Return location for error.
315 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
317 * The type of the @set_property function in #GDBusInterfaceVTable.
319 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
323 typedef gboolean (*GDBusInterfaceSetPropertyFunc
) (GDBusConnection
*connection
,
325 const gchar
*object_path
,
326 const gchar
*interface_name
,
327 const gchar
*property_name
,
333 * GDBusInterfaceVTable:
334 * @method_call: Function for handling incoming method calls.
335 * @get_property: Function for getting a property.
336 * @set_property: Function for setting a property.
338 * Virtual table for handling properties and method calls for a D-Bus
341 * Since 2.38, if you want to handle getting/setting D-Bus properties
342 * asynchronously, give %NULL as your get_property() or set_property()
343 * function. The D-Bus call will be directed to your @method_call function,
344 * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
346 * Ownership of the #GDBusMethodInvocation object passed to the
347 * method_call() function is transferred to your handler; you must
348 * call one of the methods of #GDBusMethodInvocation to return a reply
349 * (possibly empty), or an error. These functions also take ownership
350 * of the passed-in invocation object, so unless the invocation
351 * object has otherwise been referenced, it will be then be freed.
352 * Calling one of these functions may be done within your
353 * method_call() implementation but it also can be done at a later
354 * point to handle the method asynchronously.
356 * The usual checks on the validity of the calls is performed. For
357 * `Get` calls, an error is automatically returned if the property does
358 * not exist or the permissions do not allow access. The same checks are
359 * performed for `Set` calls, and the provided value is also checked for
360 * being the correct type.
362 * For both `Get` and `Set` calls, the #GDBusMethodInvocation
363 * passed to the @method_call handler can be queried with
364 * g_dbus_method_invocation_get_property_info() to get a pointer
365 * to the #GDBusPropertyInfo of the property.
367 * If you have readable properties specified in your interface info,
368 * you must ensure that you either provide a non-%NULL @get_property()
369 * function or provide implementations of both the `Get` and `GetAll`
370 * methods on org.freedesktop.DBus.Properties interface in your @method_call
371 * function. Note that the required return type of the `Get` call is
372 * `(v)`, not the type of the property. `GetAll` expects a return value
375 * If you have writable properties specified in your interface info,
376 * you must ensure that you either provide a non-%NULL @set_property()
377 * function or provide an implementation of the `Set` call. If implementing
378 * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
382 struct _GDBusInterfaceVTable
384 GDBusInterfaceMethodCallFunc method_call
;
385 GDBusInterfaceGetPropertyFunc get_property
;
386 GDBusInterfaceSetPropertyFunc set_property
;
389 /* Padding for future expansion - also remember to update
390 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
396 GLIB_AVAILABLE_IN_ALL
397 guint
g_dbus_connection_register_object (GDBusConnection
*connection
,
398 const gchar
*object_path
,
399 GDBusInterfaceInfo
*interface_info
,
400 const GDBusInterfaceVTable
*vtable
,
402 GDestroyNotify user_data_free_func
,
404 GLIB_AVAILABLE_IN_2_46
405 guint
g_dbus_connection_register_object_with_closures (GDBusConnection
*connection
,
406 const gchar
*object_path
,
407 GDBusInterfaceInfo
*interface_info
,
408 GClosure
*method_call_closure
,
409 GClosure
*get_property_closure
,
410 GClosure
*set_property_closure
,
412 GLIB_AVAILABLE_IN_ALL
413 gboolean
g_dbus_connection_unregister_object (GDBusConnection
*connection
,
414 guint registration_id
);
416 /* ---------------------------------------------------------------------------------------------------- */
419 * GDBusSubtreeEnumerateFunc:
420 * @connection: A #GDBusConnection.
421 * @sender: The unique bus name of the remote caller.
422 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
423 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
425 * The type of the @enumerate function in #GDBusSubtreeVTable.
427 * This function is called when generating introspection data and also
428 * when preparing to dispatch incoming messages in the event that the
429 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
430 * specified (ie: to verify that the object path is valid).
432 * Hierarchies are not supported; the items that you return should not
433 * contain the '/' character.
435 * The return value will be freed with g_strfreev().
437 * Returns: A newly allocated array of strings for node names that are children of @object_path.
441 typedef gchar
** (*GDBusSubtreeEnumerateFunc
) (GDBusConnection
*connection
,
443 const gchar
*object_path
,
447 * GDBusSubtreeIntrospectFunc:
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 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
452 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
454 * The type of the @introspect function in #GDBusSubtreeVTable.
456 * Subtrees are flat. @node, if non-%NULL, is always exactly one
457 * segment of the object path (ie: it never contains a slash).
459 * This function should return %NULL to indicate that there is no object
462 * If this function returns non-%NULL, the return value is expected to
463 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
464 * structures describing the interfaces implemented by @node. This
465 * array will have g_dbus_interface_info_unref() called on each item
466 * before being freed with g_free().
468 * The difference between returning %NULL and an array containing zero
469 * items is that the standard DBus interfaces will returned to the
470 * remote introspector in the empty array case, but not in the %NULL
473 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
477 typedef GDBusInterfaceInfo
** (*GDBusSubtreeIntrospectFunc
) (GDBusConnection
*connection
,
479 const gchar
*object_path
,
484 * GDBusSubtreeDispatchFunc:
485 * @connection: A #GDBusConnection.
486 * @sender: The unique bus name of the remote caller.
487 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
488 * @interface_name: The D-Bus interface name that the method call or property access is for.
489 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
490 * @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
491 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
493 * The type of the @dispatch function in #GDBusSubtreeVTable.
495 * Subtrees are flat. @node, if non-%NULL, is always exactly one
496 * segment of the object path (ie: it never contains a slash).
498 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
502 typedef const GDBusInterfaceVTable
* (*GDBusSubtreeDispatchFunc
) (GDBusConnection
*connection
,
504 const gchar
*object_path
,
505 const gchar
*interface_name
,
507 gpointer
*out_user_data
,
511 * GDBusSubtreeVTable:
512 * @enumerate: Function for enumerating child nodes.
513 * @introspect: Function for introspecting a child node.
514 * @dispatch: Function for dispatching a remote call on a child node.
516 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
520 struct _GDBusSubtreeVTable
522 GDBusSubtreeEnumerateFunc enumerate
;
523 GDBusSubtreeIntrospectFunc introspect
;
524 GDBusSubtreeDispatchFunc dispatch
;
527 /* Padding for future expansion - also remember to update
528 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
534 GLIB_AVAILABLE_IN_ALL
535 guint
g_dbus_connection_register_subtree (GDBusConnection
*connection
,
536 const gchar
*object_path
,
537 const GDBusSubtreeVTable
*vtable
,
538 GDBusSubtreeFlags flags
,
540 GDestroyNotify user_data_free_func
,
542 GLIB_AVAILABLE_IN_ALL
543 gboolean
g_dbus_connection_unregister_subtree (GDBusConnection
*connection
,
544 guint registration_id
);
546 /* ---------------------------------------------------------------------------------------------------- */
549 * GDBusSignalCallback:
550 * @connection: A #GDBusConnection.
551 * @sender_name: The unique bus name of the sender of the signal.
552 * @object_path: The object path that the signal was emitted on.
553 * @interface_name: The name of the interface.
554 * @signal_name: The name of the signal.
555 * @parameters: A #GVariant tuple with parameters for the signal.
556 * @user_data: User data passed when subscribing to the signal.
558 * Signature for callback function used in g_dbus_connection_signal_subscribe().
562 typedef void (*GDBusSignalCallback
) (GDBusConnection
*connection
,
563 const gchar
*sender_name
,
564 const gchar
*object_path
,
565 const gchar
*interface_name
,
566 const gchar
*signal_name
,
567 GVariant
*parameters
,
570 GLIB_AVAILABLE_IN_ALL
571 guint
g_dbus_connection_signal_subscribe (GDBusConnection
*connection
,
573 const gchar
*interface_name
,
575 const gchar
*object_path
,
577 GDBusSignalFlags flags
,
578 GDBusSignalCallback callback
,
580 GDestroyNotify user_data_free_func
);
581 GLIB_AVAILABLE_IN_ALL
582 void g_dbus_connection_signal_unsubscribe (GDBusConnection
*connection
,
583 guint subscription_id
);
585 /* ---------------------------------------------------------------------------------------------------- */
588 * GDBusMessageFilterFunction:
589 * @connection: (transfer none): A #GDBusConnection.
590 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
591 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
592 * a message to be sent to the other peer.
593 * @user_data: User data passed when adding the filter.
595 * Signature for function used in g_dbus_connection_add_filter().
597 * A filter function is passed a #GDBusMessage and expected to return
598 * a #GDBusMessage too. Passive filter functions that don't modify the
599 * message can simply return the @message object:
601 * static GDBusMessage *
602 * passive_filter (GDBusConnection *connection
603 * GDBusMessage *message,
605 * gpointer user_data)
607 * /<!-- -->* inspect @message *<!-- -->/
611 * Filter functions that wants to drop a message can simply return %NULL:
613 * static GDBusMessage *
614 * drop_filter (GDBusConnection *connection
615 * GDBusMessage *message,
617 * gpointer user_data)
619 * if (should_drop_message)
621 * g_object_unref (message);
627 * Finally, a filter function may modify a message by copying it:
629 * static GDBusMessage *
630 * modifying_filter (GDBusConnection *connection
631 * GDBusMessage *message,
633 * gpointer user_data)
635 * GDBusMessage *copy;
639 * copy = g_dbus_message_copy (message, &error);
640 * /<!-- -->* handle @error being is set *<!-- -->/
641 * g_object_unref (message);
643 * /<!-- -->* modify @copy *<!-- -->/
648 * If the returned #GDBusMessage is different from @message and cannot
649 * be sent on @connection (it could use features, such as file
650 * descriptors, not compatible with @connection), then a warning is
651 * logged to standard error. Applications can
652 * check this ahead of time using g_dbus_message_to_blob() passing a
653 * #GDBusCapabilityFlags value obtained from @connection.
655 * Returns: (transfer full) (nullable): A #GDBusMessage that will be freed with
656 * g_object_unref() or %NULL to drop the message. Passive filter
657 * functions can simply return the passed @message object.
661 typedef GDBusMessage
*(*GDBusMessageFilterFunction
) (GDBusConnection
*connection
,
662 GDBusMessage
*message
,
666 GLIB_AVAILABLE_IN_ALL
667 guint
g_dbus_connection_add_filter (GDBusConnection
*connection
,
668 GDBusMessageFilterFunction filter_function
,
670 GDestroyNotify user_data_free_func
);
672 GLIB_AVAILABLE_IN_ALL
673 void g_dbus_connection_remove_filter (GDBusConnection
*connection
,
676 /* ---------------------------------------------------------------------------------------------------- */
681 #endif /* __G_DBUS_CONNECTION_H__ */