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: A #GDBusMethodInvocation object that can 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
344 * function, with the provided @interface_name set to
345 * <literal>"org.freedesktop.DBus.Properties"</literal>.
347 * The usual checks on the validity of the calls is performed. For
348 * <literal>'Get'</literal> calls, an error is automatically returned if
349 * the property does not exist or the permissions do not allow access.
350 * The same checks are performed for <literal>'Set'</literal> calls, and
351 * the provided value is also checked for being the correct type.
353 * For both <literal>'Get'</literal> and <literal>'Set'</literal> calls,
354 * the #GDBusMethodInvocation passed to the method_call handler can be
355 * queried with g_dbus_method_invocation_get_property_info() to get a
356 * pointer to the #GDBusPropertyInfo of the property.
358 * If you have readable properties specified in your interface info, you
359 * must ensure that you either provide a non-%NULL @get_property()
360 * function or provide implementations of both the
361 * <literal>'Get'</literal> and <literal>'GetAll'</literal> methods on
362 * the <literal>'org.freedesktop.DBus.Properties'</literal> interface in
363 * your @method_call function. Note that the required return type of
364 * the <literal>'Get'</literal> call is <literal>(v)</literal>, not the
365 * type of the property. <literal>'GetAll'</literal> expects a return
366 * value of type <literal>a{sv}</literal>.
368 * If you have writable properties specified in your interface info, you
369 * must ensure that you either provide a non-%NULL @set_property()
370 * function or provide an implementation of the <literal>'Set'</literal>
371 * call. If implementing the call, you must return the value of type
372 * %G_VARIANT_TYPE_UNIT.
376 struct _GDBusInterfaceVTable
378 GDBusInterfaceMethodCallFunc method_call;
379 GDBusInterfaceGetPropertyFunc get_property;
380 GDBusInterfaceSetPropertyFunc set_property;
383 /* Padding for future expansion - also remember to update
384 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
390 GLIB_AVAILABLE_IN_ALL
391 guint g_dbus_connection_register_object (GDBusConnection *connection,
392 const gchar *object_path,
393 GDBusInterfaceInfo *interface_info,
394 const GDBusInterfaceVTable *vtable,
396 GDestroyNotify user_data_free_func,
398 GLIB_AVAILABLE_IN_ALL
399 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
400 guint registration_id);
402 /* ---------------------------------------------------------------------------------------------------- */
405 * GDBusSubtreeEnumerateFunc:
406 * @connection: A #GDBusConnection.
407 * @sender: The unique bus name of the remote caller.
408 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
409 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
411 * The type of the @enumerate function in #GDBusSubtreeVTable.
413 * This function is called when generating introspection data and also
414 * when preparing to dispatch incoming messages in the event that the
415 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
416 * specified (ie: to verify that the object path is valid).
418 * Hierarchies are not supported; the items that you return should not
419 * contain the '/' character.
421 * The return value will be freed with g_strfreev().
423 * Returns: A newly allocated array of strings for node names that are children of @object_path.
427 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
429 const gchar *object_path,
433 * GDBusSubtreeIntrospectFunc:
434 * @connection: A #GDBusConnection.
435 * @sender: The unique bus name of the remote caller.
436 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
437 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
438 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
440 * The type of the @introspect function in #GDBusSubtreeVTable.
442 * Subtrees are flat. @node, if non-%NULL, is always exactly one
443 * segment of the object path (ie: it never contains a slash).
445 * This function should return %NULL to indicate that there is no object
448 * If this function returns non-%NULL, the return value is expected to
449 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
450 * structures describing the interfaces implemented by @node. This
451 * array will have g_dbus_interface_info_unref() called on each item
452 * before being freed with g_free().
454 * The difference between returning %NULL and an array containing zero
455 * items is that the standard DBus interfaces will returned to the
456 * remote introspector in the empty array case, but not in the %NULL
459 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
463 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
465 const gchar *object_path,
470 * GDBusSubtreeDispatchFunc:
471 * @connection: A #GDBusConnection.
472 * @sender: The unique bus name of the remote caller.
473 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
474 * @interface_name: The D-Bus interface name that the method call or property access is for.
475 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
476 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
477 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
479 * The type of the @dispatch function in #GDBusSubtreeVTable.
481 * Subtrees are flat. @node, if non-%NULL, is always exactly one
482 * segment of the object path (ie: it never contains a slash).
484 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
488 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
490 const gchar *object_path,
491 const gchar *interface_name,
493 gpointer *out_user_data,
497 * GDBusSubtreeVTable:
498 * @enumerate: Function for enumerating child nodes.
499 * @introspect: Function for introspecting a child node.
500 * @dispatch: Function for dispatching a remote call on a child node.
502 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
506 struct _GDBusSubtreeVTable
508 GDBusSubtreeEnumerateFunc enumerate;
509 GDBusSubtreeIntrospectFunc introspect;
510 GDBusSubtreeDispatchFunc dispatch;
513 /* Padding for future expansion - also remember to update
514 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
520 GLIB_AVAILABLE_IN_ALL
521 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
522 const gchar *object_path,
523 const GDBusSubtreeVTable *vtable,
524 GDBusSubtreeFlags flags,
526 GDestroyNotify user_data_free_func,
528 GLIB_AVAILABLE_IN_ALL
529 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
530 guint registration_id);
532 /* ---------------------------------------------------------------------------------------------------- */
535 * GDBusSignalCallback:
536 * @connection: A #GDBusConnection.
537 * @sender_name: The unique bus name of the sender of the signal.
538 * @object_path: The object path that the signal was emitted on.
539 * @interface_name: The name of the interface.
540 * @signal_name: The name of the signal.
541 * @parameters: A #GVariant tuple with parameters for the signal.
542 * @user_data: User data passed when subscribing to the signal.
544 * Signature for callback function used in g_dbus_connection_signal_subscribe().
548 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
549 const gchar *sender_name,
550 const gchar *object_path,
551 const gchar *interface_name,
552 const gchar *signal_name,
553 GVariant *parameters,
556 GLIB_AVAILABLE_IN_ALL
557 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
559 const gchar *interface_name,
561 const gchar *object_path,
563 GDBusSignalFlags flags,
564 GDBusSignalCallback callback,
566 GDestroyNotify user_data_free_func);
567 GLIB_AVAILABLE_IN_ALL
568 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
569 guint subscription_id);
571 /* ---------------------------------------------------------------------------------------------------- */
574 * GDBusMessageFilterFunction:
575 * @connection: (transfer none): A #GDBusConnection.
576 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
577 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
578 * a message to be sent to the other peer.
579 * @user_data: User data passed when adding the filter.
581 * Signature for function used in g_dbus_connection_add_filter().
583 * A filter function is passed a #GDBusMessage and expected to return
584 * a #GDBusMessage too. Passive filter functions that don't modify the
585 * message can simply return the @message object:
587 * static GDBusMessage *
588 * passive_filter (GDBusConnection *connection
589 * GDBusMessage *message,
591 * gpointer user_data)
593 * /<!-- -->* inspect @message *<!-- -->/
597 * Filter functions that wants to drop a message can simply return %NULL:
599 * static GDBusMessage *
600 * drop_filter (GDBusConnection *connection
601 * GDBusMessage *message,
603 * gpointer user_data)
605 * if (should_drop_message)
607 * g_object_unref (message);
613 * Finally, a filter function may modify a message by copying it:
615 * static GDBusMessage *
616 * modifying_filter (GDBusConnection *connection
617 * GDBusMessage *message,
619 * gpointer user_data)
621 * GDBusMessage *copy;
625 * copy = g_dbus_message_copy (message, &error);
626 * /<!-- -->* handle @error being is set *<!-- -->/
627 * g_object_unref (message);
629 * /<!-- -->* modify @copy *<!-- -->/
634 * If the returned #GDBusMessage is different from @message and cannot
635 * be sent on @connection (it could use features, such as file
636 * descriptors, not compatible with @connection), then a warning is
637 * logged to <emphasis>standard error</emphasis>. Applications can
638 * check this ahead of time using g_dbus_message_to_blob() passing a
639 * #GDBusCapabilityFlags value obtained from @connection.
641 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
642 * g_object_unref() or %NULL to drop the message. Passive filter
643 * functions can simply return the passed @message object.
647 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
648 GDBusMessage *message,
652 GLIB_AVAILABLE_IN_ALL
653 guint g_dbus_connection_add_filter (GDBusConnection *connection,
654 GDBusMessageFilterFunction filter_function,
656 GDestroyNotify user_data_free_func);
658 GLIB_AVAILABLE_IN_ALL
659 void g_dbus_connection_remove_filter (GDBusConnection *connection,
662 /* ---------------------------------------------------------------------------------------------------- */
667 #endif /* __G_DBUS_CONNECTION_H__ */