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, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: David Zeuthen <davidz@redhat.com>
23 #ifndef __G_DBUS_CONNECTION_H__
24 #define __G_DBUS_CONNECTION_H__
26 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
27 #error "Only <gio/gio.h> can be included directly."
30 #include <gio/giotypes.h>
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))
39 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
41 /* ---------------------------------------------------------------------------------------------------- */
44 void g_bus_get (GBusType bus_type,
45 GCancellable *cancellable,
46 GAsyncReadyCallback callback,
49 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
52 GDBusConnection *g_bus_get_sync (GBusType bus_type,
53 GCancellable *cancellable,
56 /* ---------------------------------------------------------------------------------------------------- */
59 void g_dbus_connection_new (GIOStream *stream,
61 GDBusConnectionFlags flags,
62 GDBusAuthObserver *observer,
63 GCancellable *cancellable,
64 GAsyncReadyCallback callback,
67 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
70 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
72 GDBusConnectionFlags flags,
73 GDBusAuthObserver *observer,
74 GCancellable *cancellable,
78 void g_dbus_connection_new_for_address (const gchar *address,
79 GDBusConnectionFlags flags,
80 GDBusAuthObserver *observer,
81 GCancellable *cancellable,
82 GAsyncReadyCallback callback,
85 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
88 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
89 GDBusConnectionFlags flags,
90 GDBusAuthObserver *observer,
91 GCancellable *cancellable,
94 /* ---------------------------------------------------------------------------------------------------- */
97 void g_dbus_connection_start_message_processing (GDBusConnection *connection);
99 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
100 GLIB_AVAILABLE_IN_ALL
101 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
102 GLIB_AVAILABLE_IN_ALL
103 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
104 GLIB_AVAILABLE_IN_ALL
105 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
106 GLIB_AVAILABLE_IN_ALL
107 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
109 GLIB_AVAILABLE_IN_2_34
110 guint32 g_dbus_connection_get_last_serial (GDBusConnection *connection);
112 GLIB_AVAILABLE_IN_ALL
113 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
114 GLIB_AVAILABLE_IN_ALL
115 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
116 gboolean exit_on_close);
117 GLIB_AVAILABLE_IN_ALL
118 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
120 /* ---------------------------------------------------------------------------------------------------- */
122 GLIB_AVAILABLE_IN_ALL
123 void g_dbus_connection_close (GDBusConnection *connection,
124 GCancellable *cancellable,
125 GAsyncReadyCallback callback,
127 GLIB_AVAILABLE_IN_ALL
128 gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
131 GLIB_AVAILABLE_IN_ALL
132 gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
133 GCancellable *cancellable,
136 /* ---------------------------------------------------------------------------------------------------- */
138 GLIB_AVAILABLE_IN_ALL
139 void g_dbus_connection_flush (GDBusConnection *connection,
140 GCancellable *cancellable,
141 GAsyncReadyCallback callback,
143 GLIB_AVAILABLE_IN_ALL
144 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
147 GLIB_AVAILABLE_IN_ALL
148 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
149 GCancellable *cancellable,
152 /* ---------------------------------------------------------------------------------------------------- */
154 GLIB_AVAILABLE_IN_ALL
155 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
156 GDBusMessage *message,
157 GDBusSendMessageFlags flags,
158 volatile guint32 *out_serial,
160 GLIB_AVAILABLE_IN_ALL
161 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
162 GDBusMessage *message,
163 GDBusSendMessageFlags flags,
165 volatile guint32 *out_serial,
166 GCancellable *cancellable,
167 GAsyncReadyCallback callback,
169 GLIB_AVAILABLE_IN_ALL
170 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
173 GLIB_AVAILABLE_IN_ALL
174 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
175 GDBusMessage *message,
176 GDBusSendMessageFlags flags,
178 volatile guint32 *out_serial,
179 GCancellable *cancellable,
182 /* ---------------------------------------------------------------------------------------------------- */
184 GLIB_AVAILABLE_IN_ALL
185 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
186 const gchar *destination_bus_name,
187 const gchar *object_path,
188 const gchar *interface_name,
189 const gchar *signal_name,
190 GVariant *parameters,
192 GLIB_AVAILABLE_IN_ALL
193 void g_dbus_connection_call (GDBusConnection *connection,
194 const gchar *bus_name,
195 const gchar *object_path,
196 const gchar *interface_name,
197 const gchar *method_name,
198 GVariant *parameters,
199 const GVariantType *reply_type,
200 GDBusCallFlags flags,
202 GCancellable *cancellable,
203 GAsyncReadyCallback callback,
205 GLIB_AVAILABLE_IN_ALL
206 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
209 GLIB_AVAILABLE_IN_ALL
210 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
211 const gchar *bus_name,
212 const gchar *object_path,
213 const gchar *interface_name,
214 const gchar *method_name,
215 GVariant *parameters,
216 const GVariantType *reply_type,
217 GDBusCallFlags flags,
219 GCancellable *cancellable,
221 GLIB_AVAILABLE_IN_2_30
222 void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection,
223 const gchar *bus_name,
224 const gchar *object_path,
225 const gchar *interface_name,
226 const gchar *method_name,
227 GVariant *parameters,
228 const GVariantType *reply_type,
229 GDBusCallFlags flags,
231 GUnixFDList *fd_list,
232 GCancellable *cancellable,
233 GAsyncReadyCallback callback,
235 GLIB_AVAILABLE_IN_2_30
236 GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
237 GUnixFDList **out_fd_list,
240 GLIB_AVAILABLE_IN_2_30
241 GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection,
242 const gchar *bus_name,
243 const gchar *object_path,
244 const gchar *interface_name,
245 const gchar *method_name,
246 GVariant *parameters,
247 const GVariantType *reply_type,
248 GDBusCallFlags flags,
250 GUnixFDList *fd_list,
251 GUnixFDList **out_fd_list,
252 GCancellable *cancellable,
255 /* ---------------------------------------------------------------------------------------------------- */
259 * GDBusInterfaceMethodCallFunc:
260 * @connection: A #GDBusConnection.
261 * @sender: The unique bus name of the remote caller.
262 * @object_path: The object path that the method was invoked on.
263 * @interface_name: The D-Bus interface name the method was invoked on.
264 * @method_name: The name of the method that was invoked.
265 * @parameters: A #GVariant tuple with parameters.
266 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
267 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
269 * The type of the @method_call function in #GDBusInterfaceVTable.
273 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
275 const gchar *object_path,
276 const gchar *interface_name,
277 const gchar *method_name,
278 GVariant *parameters,
279 GDBusMethodInvocation *invocation,
283 * GDBusInterfaceGetPropertyFunc:
284 * @connection: A #GDBusConnection.
285 * @sender: The unique bus name of the remote caller.
286 * @object_path: The object path that the method was invoked on.
287 * @interface_name: The D-Bus interface name for the property.
288 * @property_name: The name of the property to get the value of.
289 * @error: Return location for error.
290 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
292 * The type of the @get_property function in #GDBusInterfaceVTable.
294 * Returns: A #GVariant with the value for @property_name or %NULL if
295 * @error is set. If the returned #GVariant is floating, it is
296 * consumed - otherwise its reference count is decreased by one.
300 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
302 const gchar *object_path,
303 const gchar *interface_name,
304 const gchar *property_name,
309 * GDBusInterfaceSetPropertyFunc:
310 * @connection: A #GDBusConnection.
311 * @sender: The unique bus name of the remote caller.
312 * @object_path: The object path that the method was invoked on.
313 * @interface_name: The D-Bus interface name for the property.
314 * @property_name: The name of the property to get the value of.
315 * @value: The value to set the property to.
316 * @error: Return location for error.
317 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
319 * The type of the @set_property function in #GDBusInterfaceVTable.
321 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
325 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
327 const gchar *object_path,
328 const gchar *interface_name,
329 const gchar *property_name,
335 * GDBusInterfaceVTable:
336 * @method_call: Function for handling incoming method calls.
337 * @get_property: Function for getting a property.
338 * @set_property: Function for setting a property.
340 * Virtual table for handling properties and method calls for a D-Bus
343 * If you want to handle getting/setting D-Bus properties asynchronously, simply
344 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
345 * D-Bus interface using g_dbus_connection_register_object().
349 struct _GDBusInterfaceVTable
351 GDBusInterfaceMethodCallFunc method_call;
352 GDBusInterfaceGetPropertyFunc get_property;
353 GDBusInterfaceSetPropertyFunc set_property;
356 /* Padding for future expansion - also remember to update
357 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
363 GLIB_AVAILABLE_IN_ALL
364 guint g_dbus_connection_register_object (GDBusConnection *connection,
365 const gchar *object_path,
366 GDBusInterfaceInfo *interface_info,
367 const GDBusInterfaceVTable *vtable,
369 GDestroyNotify user_data_free_func,
371 GLIB_AVAILABLE_IN_ALL
372 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
373 guint registration_id);
375 /* ---------------------------------------------------------------------------------------------------- */
378 * GDBusSubtreeEnumerateFunc:
379 * @connection: A #GDBusConnection.
380 * @sender: The unique bus name of the remote caller.
381 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
382 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
384 * The type of the @enumerate function in #GDBusSubtreeVTable.
386 * This function is called when generating introspection data and also
387 * when preparing to dispatch incoming messages in the event that the
388 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
389 * specified (ie: to verify that the object path is valid).
391 * Hierarchies are not supported; the items that you return should not
392 * contain the '/' character.
394 * The return value will be freed with g_strfreev().
396 * Returns: A newly allocated array of strings for node names that are children of @object_path.
400 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
402 const gchar *object_path,
406 * GDBusSubtreeIntrospectFunc:
407 * @connection: A #GDBusConnection.
408 * @sender: The unique bus name of the remote caller.
409 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
410 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
411 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
413 * The type of the @introspect function in #GDBusSubtreeVTable.
415 * Subtrees are flat. @node, if non-%NULL, is always exactly one
416 * segment of the object path (ie: it never contains a slash).
418 * This function should return %NULL to indicate that there is no object
421 * If this function returns non-%NULL, the return value is expected to
422 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
423 * structures describing the interfaces implemented by @node. This
424 * array will have g_dbus_interface_info_unref() called on each item
425 * before being freed with g_free().
427 * The difference between returning %NULL and an array containing zero
428 * items is that the standard DBus interfaces will returned to the
429 * remote introspector in the empty array case, but not in the %NULL
432 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
436 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
438 const gchar *object_path,
443 * GDBusSubtreeDispatchFunc:
444 * @connection: A #GDBusConnection.
445 * @sender: The unique bus name of the remote caller.
446 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
447 * @interface_name: The D-Bus interface name that the method call or property access is for.
448 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
449 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
450 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
452 * The type of the @dispatch function in #GDBusSubtreeVTable.
454 * Subtrees are flat. @node, if non-%NULL, is always exactly one
455 * segment of the object path (ie: it never contains a slash).
457 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
461 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
463 const gchar *object_path,
464 const gchar *interface_name,
466 gpointer *out_user_data,
470 * GDBusSubtreeVTable:
471 * @enumerate: Function for enumerating child nodes.
472 * @introspect: Function for introspecting a child node.
473 * @dispatch: Function for dispatching a remote call on a child node.
475 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
479 struct _GDBusSubtreeVTable
481 GDBusSubtreeEnumerateFunc enumerate;
482 GDBusSubtreeIntrospectFunc introspect;
483 GDBusSubtreeDispatchFunc dispatch;
486 /* Padding for future expansion - also remember to update
487 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
493 GLIB_AVAILABLE_IN_ALL
494 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
495 const gchar *object_path,
496 const GDBusSubtreeVTable *vtable,
497 GDBusSubtreeFlags flags,
499 GDestroyNotify user_data_free_func,
501 GLIB_AVAILABLE_IN_ALL
502 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
503 guint registration_id);
505 /* ---------------------------------------------------------------------------------------------------- */
508 * GDBusSignalCallback:
509 * @connection: A #GDBusConnection.
510 * @sender_name: The unique bus name of the sender of the signal.
511 * @object_path: The object path that the signal was emitted on.
512 * @interface_name: The name of the interface.
513 * @signal_name: The name of the signal.
514 * @parameters: A #GVariant tuple with parameters for the signal.
515 * @user_data: User data passed when subscribing to the signal.
517 * Signature for callback function used in g_dbus_connection_signal_subscribe().
521 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
522 const gchar *sender_name,
523 const gchar *object_path,
524 const gchar *interface_name,
525 const gchar *signal_name,
526 GVariant *parameters,
529 GLIB_AVAILABLE_IN_ALL
530 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
532 const gchar *interface_name,
534 const gchar *object_path,
536 GDBusSignalFlags flags,
537 GDBusSignalCallback callback,
539 GDestroyNotify user_data_free_func);
540 GLIB_AVAILABLE_IN_ALL
541 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
542 guint subscription_id);
544 /* ---------------------------------------------------------------------------------------------------- */
547 * GDBusMessageFilterFunction:
548 * @connection: (transfer none): A #GDBusConnection.
549 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
550 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
551 * a message to be sent to the other peer.
552 * @user_data: User data passed when adding the filter.
554 * Signature for function used in g_dbus_connection_add_filter().
556 * A filter function is passed a #GDBusMessage and expected to return
557 * a #GDBusMessage too. Passive filter functions that don't modify the
558 * message can simply return the @message object:
560 * static GDBusMessage *
561 * passive_filter (GDBusConnection *connection
562 * GDBusMessage *message,
564 * gpointer user_data)
566 * /<!-- -->* inspect @message *<!-- -->/
570 * Filter functions that wants to drop a message can simply return %NULL:
572 * static GDBusMessage *
573 * drop_filter (GDBusConnection *connection
574 * GDBusMessage *message,
576 * gpointer user_data)
578 * if (should_drop_message)
580 * g_object_unref (message);
586 * Finally, a filter function may modify a message by copying it:
588 * static GDBusMessage *
589 * modifying_filter (GDBusConnection *connection
590 * GDBusMessage *message,
592 * gpointer user_data)
594 * GDBusMessage *copy;
598 * copy = g_dbus_message_copy (message, &error);
599 * /<!-- -->* handle @error being is set *<!-- -->/
600 * g_object_unref (message);
602 * /<!-- -->* modify @copy *<!-- -->/
607 * If the returned #GDBusMessage is different from @message and cannot
608 * be sent on @connection (it could use features, such as file
609 * descriptors, not compatible with @connection), then a warning is
610 * logged to <emphasis>standard error</emphasis>. Applications can
611 * check this ahead of time using g_dbus_message_to_blob() passing a
612 * #GDBusCapabilityFlags value obtained from @connection.
614 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
615 * g_object_unref() or %NULL to drop the message. Passive filter
616 * functions can simply return the passed @message object.
620 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
621 GDBusMessage *message,
625 GLIB_AVAILABLE_IN_ALL
626 guint g_dbus_connection_add_filter (GDBusConnection *connection,
627 GDBusMessageFilterFunction filter_function,
629 GDestroyNotify user_data_free_func);
631 GLIB_AVAILABLE_IN_ALL
632 void g_dbus_connection_remove_filter (GDBusConnection *connection,
635 /* ---------------------------------------------------------------------------------------------------- */
640 #endif /* __G_DBUS_CONNECTION_H__ */