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 /* ---------------------------------------------------------------------------------------------------- */
94 GLIB_AVAILABLE_IN_2_40
95 guint32 g_dbus_request_name (GDBusConnection *connection,
97 GBusNameOwnerFlags flags,
99 GLIB_AVAILABLE_IN_2_40
100 guint32 g_dbus_release_name (GDBusConnection *connection,
103 GLIB_AVAILABLE_IN_2_40
104 gchar *g_dbus_get_bus_id (GDBusConnection *connection,
106 GLIB_AVAILABLE_IN_2_40
107 gchar **g_dbus_get_list_names (GDBusConnection *connection,
109 GLIB_AVAILABLE_IN_2_40
110 gchar **g_dbus_get_list_activatable_names (GDBusConnection *connection,
112 GLIB_AVAILABLE_IN_2_40
113 gchar **g_dbus_get_list_queued_owners (GDBusConnection *connection,
116 GLIB_AVAILABLE_IN_2_40
117 gchar *g_dbus_get_name_owner (GDBusConnection *connection,
120 GLIB_AVAILABLE_IN_2_40
121 guint32 g_dbus_get_connection_pid (GDBusConnection *connection,
124 GLIB_AVAILABLE_IN_2_40
125 guint32 g_dbus_get_connection_uid (GDBusConnection *connection,
129 /* ---------------------------------------------------------------------------------------------------- */
131 GLIB_AVAILABLE_IN_ALL
132 void g_dbus_connection_start_message_processing (GDBusConnection *connection);
133 GLIB_AVAILABLE_IN_ALL
134 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
135 GLIB_AVAILABLE_IN_ALL
136 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
137 GLIB_AVAILABLE_IN_ALL
138 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
139 GLIB_AVAILABLE_IN_ALL
140 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
141 GLIB_AVAILABLE_IN_ALL
142 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
144 GLIB_AVAILABLE_IN_2_34
145 guint32 g_dbus_connection_get_last_serial (GDBusConnection *connection);
147 GLIB_AVAILABLE_IN_ALL
148 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
149 GLIB_AVAILABLE_IN_ALL
150 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
151 gboolean exit_on_close);
152 GLIB_AVAILABLE_IN_ALL
153 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
155 /* ---------------------------------------------------------------------------------------------------- */
157 GLIB_AVAILABLE_IN_ALL
158 void g_dbus_connection_close (GDBusConnection *connection,
159 GCancellable *cancellable,
160 GAsyncReadyCallback callback,
162 GLIB_AVAILABLE_IN_ALL
163 gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
166 GLIB_AVAILABLE_IN_ALL
167 gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
168 GCancellable *cancellable,
171 /* ---------------------------------------------------------------------------------------------------- */
173 GLIB_AVAILABLE_IN_ALL
174 void g_dbus_connection_flush (GDBusConnection *connection,
175 GCancellable *cancellable,
176 GAsyncReadyCallback callback,
178 GLIB_AVAILABLE_IN_ALL
179 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
182 GLIB_AVAILABLE_IN_ALL
183 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
184 GCancellable *cancellable,
187 /* ---------------------------------------------------------------------------------------------------- */
189 GLIB_AVAILABLE_IN_ALL
190 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
191 GDBusMessage *message,
192 GDBusSendMessageFlags flags,
193 volatile guint32 *out_serial,
195 GLIB_AVAILABLE_IN_ALL
196 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
197 GDBusMessage *message,
198 GDBusSendMessageFlags flags,
200 volatile guint32 *out_serial,
201 GCancellable *cancellable,
202 GAsyncReadyCallback callback,
204 GLIB_AVAILABLE_IN_ALL
205 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
208 GLIB_AVAILABLE_IN_ALL
209 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
210 GDBusMessage *message,
211 GDBusSendMessageFlags flags,
213 volatile guint32 *out_serial,
214 GCancellable *cancellable,
217 /* ---------------------------------------------------------------------------------------------------- */
219 GLIB_AVAILABLE_IN_ALL
220 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
221 const gchar *destination_bus_name,
222 const gchar *object_path,
223 const gchar *interface_name,
224 const gchar *signal_name,
225 GVariant *parameters,
227 GLIB_AVAILABLE_IN_ALL
228 void g_dbus_connection_call (GDBusConnection *connection,
229 const gchar *bus_name,
230 const gchar *object_path,
231 const gchar *interface_name,
232 const gchar *method_name,
233 GVariant *parameters,
234 const GVariantType *reply_type,
235 GDBusCallFlags flags,
237 GCancellable *cancellable,
238 GAsyncReadyCallback callback,
240 GLIB_AVAILABLE_IN_ALL
241 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
244 GLIB_AVAILABLE_IN_ALL
245 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
246 const gchar *bus_name,
247 const gchar *object_path,
248 const gchar *interface_name,
249 const gchar *method_name,
250 GVariant *parameters,
251 const GVariantType *reply_type,
252 GDBusCallFlags flags,
254 GCancellable *cancellable,
256 GLIB_AVAILABLE_IN_2_30
257 void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection,
258 const gchar *bus_name,
259 const gchar *object_path,
260 const gchar *interface_name,
261 const gchar *method_name,
262 GVariant *parameters,
263 const GVariantType *reply_type,
264 GDBusCallFlags flags,
266 GUnixFDList *fd_list,
267 GCancellable *cancellable,
268 GAsyncReadyCallback callback,
270 GLIB_AVAILABLE_IN_2_30
271 GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
272 GUnixFDList **out_fd_list,
275 GLIB_AVAILABLE_IN_2_30
276 GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection,
277 const gchar *bus_name,
278 const gchar *object_path,
279 const gchar *interface_name,
280 const gchar *method_name,
281 GVariant *parameters,
282 const GVariantType *reply_type,
283 GDBusCallFlags flags,
285 GUnixFDList *fd_list,
286 GUnixFDList **out_fd_list,
287 GCancellable *cancellable,
290 /* ---------------------------------------------------------------------------------------------------- */
294 * GDBusInterfaceMethodCallFunc:
295 * @connection: A #GDBusConnection.
296 * @sender: The unique bus name of the remote caller.
297 * @object_path: The object path that the method was invoked on.
298 * @interface_name: The D-Bus interface name the method was invoked on.
299 * @method_name: The name of the method that was invoked.
300 * @parameters: A #GVariant tuple with parameters.
301 * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error.
302 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
304 * The type of the @method_call function in #GDBusInterfaceVTable.
308 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
310 const gchar *object_path,
311 const gchar *interface_name,
312 const gchar *method_name,
313 GVariant *parameters,
314 GDBusMethodInvocation *invocation,
318 * GDBusInterfaceGetPropertyFunc:
319 * @connection: A #GDBusConnection.
320 * @sender: The unique bus name of the remote caller.
321 * @object_path: The object path that the method was invoked on.
322 * @interface_name: The D-Bus interface name for the property.
323 * @property_name: The name of the property to get the value of.
324 * @error: Return location for error.
325 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
327 * The type of the @get_property function in #GDBusInterfaceVTable.
329 * Returns: A #GVariant with the value for @property_name or %NULL if
330 * @error is set. If the returned #GVariant is floating, it is
331 * consumed - otherwise its reference count is decreased by one.
335 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
337 const gchar *object_path,
338 const gchar *interface_name,
339 const gchar *property_name,
344 * GDBusInterfaceSetPropertyFunc:
345 * @connection: A #GDBusConnection.
346 * @sender: The unique bus name of the remote caller.
347 * @object_path: The object path that the method was invoked on.
348 * @interface_name: The D-Bus interface name for the property.
349 * @property_name: The name of the property to get the value of.
350 * @value: The value to set the property to.
351 * @error: Return location for error.
352 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
354 * The type of the @set_property function in #GDBusInterfaceVTable.
356 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
360 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
362 const gchar *object_path,
363 const gchar *interface_name,
364 const gchar *property_name,
370 * GDBusInterfaceVTable:
371 * @method_call: Function for handling incoming method calls.
372 * @get_property: Function for getting a property.
373 * @set_property: Function for setting a property.
375 * Virtual table for handling properties and method calls for a D-Bus
378 * Since 2.38, if you want to handle getting/setting D-Bus properties
379 * asynchronously, give %NULL as your get_property() or set_property()
380 * function. The D-Bus call will be directed to your @method_call function,
381 * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
383 * Ownership of the #GDBusMethodInvocation object passed to the
384 * method_call() function is transferred to your handler; you must
385 * call one of the methods of #GDBusMethodInvocation to return a reply
386 * (possibly empty), or an error. These functions also take ownership
387 * of the passed-in invocation object, so unless the invocation
388 * object has otherwise been referenced, it will be then be freed.
389 * Calling one of these functions may be done within your
390 * method_call() implementation but it also can be done at a later
391 * point to handle the method asynchronously.
393 * The usual checks on the validity of the calls is performed. For
394 * `Get` calls, an error is automatically returned if the property does
395 * not exist or the permissions do not allow access. The same checks are
396 * performed for `Set` calls, and the provided value is also checked for
397 * being the correct type.
399 * For both `Get` and `Set` calls, the #GDBusMethodInvocation
400 * passed to the @method_call handler can be queried with
401 * g_dbus_method_invocation_get_property_info() to get a pointer
402 * to the #GDBusPropertyInfo of the property.
404 * If you have readable properties specified in your interface info,
405 * you must ensure that you either provide a non-%NULL @get_property()
406 * function or provide implementations of both the `Get` and `GetAll`
407 * methods on org.freedesktop.DBus.Properties interface in your @method_call
408 * function. Note that the required return type of the `Get` call is
409 * `(v)`, not the type of the property. `GetAll` expects a return value
412 * If you have writable properties specified in your interface info,
413 * you must ensure that you either provide a non-%NULL @set_property()
414 * function or provide an implementation of the `Set` call. If implementing
415 * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
419 struct _GDBusInterfaceVTable
421 GDBusInterfaceMethodCallFunc method_call;
422 GDBusInterfaceGetPropertyFunc get_property;
423 GDBusInterfaceSetPropertyFunc set_property;
426 /* Padding for future expansion - also remember to update
427 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
433 GLIB_AVAILABLE_IN_ALL
434 guint g_dbus_connection_register_object (GDBusConnection *connection,
435 const gchar *object_path,
436 GDBusInterfaceInfo *interface_info,
437 const GDBusInterfaceVTable *vtable,
439 GDestroyNotify user_data_free_func,
441 GLIB_AVAILABLE_IN_ALL
442 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
443 guint registration_id);
445 /* ---------------------------------------------------------------------------------------------------- */
448 * GDBusSubtreeEnumerateFunc:
449 * @connection: A #GDBusConnection.
450 * @sender: The unique bus name of the remote caller.
451 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
452 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
454 * The type of the @enumerate function in #GDBusSubtreeVTable.
456 * This function is called when generating introspection data and also
457 * when preparing to dispatch incoming messages in the event that the
458 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
459 * specified (ie: to verify that the object path is valid).
461 * Hierarchies are not supported; the items that you return should not
462 * contain the '/' character.
464 * The return value will be freed with g_strfreev().
466 * Returns: A newly allocated array of strings for node names that are children of @object_path.
470 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
472 const gchar *object_path,
476 * GDBusSubtreeIntrospectFunc:
477 * @connection: A #GDBusConnection.
478 * @sender: The unique bus name of the remote caller.
479 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
480 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
481 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
483 * The type of the @introspect function in #GDBusSubtreeVTable.
485 * Subtrees are flat. @node, if non-%NULL, is always exactly one
486 * segment of the object path (ie: it never contains a slash).
488 * This function should return %NULL to indicate that there is no object
491 * If this function returns non-%NULL, the return value is expected to
492 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
493 * structures describing the interfaces implemented by @node. This
494 * array will have g_dbus_interface_info_unref() called on each item
495 * before being freed with g_free().
497 * The difference between returning %NULL and an array containing zero
498 * items is that the standard DBus interfaces will returned to the
499 * remote introspector in the empty array case, but not in the %NULL
502 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
506 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
508 const gchar *object_path,
513 * GDBusSubtreeDispatchFunc:
514 * @connection: A #GDBusConnection.
515 * @sender: The unique bus name of the remote caller.
516 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
517 * @interface_name: The D-Bus interface name that the method call or property access is for.
518 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
519 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
520 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
522 * The type of the @dispatch function in #GDBusSubtreeVTable.
524 * Subtrees are flat. @node, if non-%NULL, is always exactly one
525 * segment of the object path (ie: it never contains a slash).
527 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
531 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
533 const gchar *object_path,
534 const gchar *interface_name,
536 gpointer *out_user_data,
540 * GDBusSubtreeVTable:
541 * @enumerate: Function for enumerating child nodes.
542 * @introspect: Function for introspecting a child node.
543 * @dispatch: Function for dispatching a remote call on a child node.
545 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
549 struct _GDBusSubtreeVTable
551 GDBusSubtreeEnumerateFunc enumerate;
552 GDBusSubtreeIntrospectFunc introspect;
553 GDBusSubtreeDispatchFunc dispatch;
556 /* Padding for future expansion - also remember to update
557 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
563 GLIB_AVAILABLE_IN_ALL
564 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
565 const gchar *object_path,
566 const GDBusSubtreeVTable *vtable,
567 GDBusSubtreeFlags flags,
569 GDestroyNotify user_data_free_func,
571 GLIB_AVAILABLE_IN_ALL
572 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
573 guint registration_id);
575 /* ---------------------------------------------------------------------------------------------------- */
578 * GDBusSignalCallback:
579 * @connection: A #GDBusConnection.
580 * @sender_name: The unique bus name of the sender of the signal.
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.
587 * Signature for callback function used in g_dbus_connection_signal_subscribe().
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,
599 GLIB_AVAILABLE_IN_ALL
600 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
602 const gchar *interface_name,
604 const gchar *object_path,
606 GDBusSignalFlags flags,
607 GDBusSignalCallback callback,
609 GDestroyNotify user_data_free_func);
610 GLIB_AVAILABLE_IN_ALL
611 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
612 guint subscription_id);
614 /* ---------------------------------------------------------------------------------------------------- */
617 * GDBusMessageFilterFunction:
618 * @connection: (transfer none): A #GDBusConnection.
619 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
620 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
621 * a message to be sent to the other peer.
622 * @user_data: User data passed when adding the filter.
624 * Signature for function used in g_dbus_connection_add_filter().
626 * A filter function is passed a #GDBusMessage and expected to return
627 * a #GDBusMessage too. Passive filter functions that don't modify the
628 * message can simply return the @message object:
630 * static GDBusMessage *
631 * passive_filter (GDBusConnection *connection
632 * GDBusMessage *message,
634 * gpointer user_data)
636 * /<!-- -->* inspect @message *<!-- -->/
640 * Filter functions that wants to drop a message can simply return %NULL:
642 * static GDBusMessage *
643 * drop_filter (GDBusConnection *connection
644 * GDBusMessage *message,
646 * gpointer user_data)
648 * if (should_drop_message)
650 * g_object_unref (message);
656 * Finally, a filter function may modify a message by copying it:
658 * static GDBusMessage *
659 * modifying_filter (GDBusConnection *connection
660 * GDBusMessage *message,
662 * gpointer user_data)
664 * GDBusMessage *copy;
668 * copy = g_dbus_message_copy (message, &error);
669 * /<!-- -->* handle @error being is set *<!-- -->/
670 * g_object_unref (message);
672 * /<!-- -->* modify @copy *<!-- -->/
677 * If the returned #GDBusMessage is different from @message and cannot
678 * be sent on @connection (it could use features, such as file
679 * descriptors, not compatible with @connection), then a warning is
680 * logged to <emphasis>standard error</emphasis>. Applications can
681 * check this ahead of time using g_dbus_message_to_blob() passing a
682 * #GDBusCapabilityFlags value obtained from @connection.
684 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
685 * g_object_unref() or %NULL to drop the message. Passive filter
686 * functions can simply return the passed @message object.
690 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
691 GDBusMessage *message,
695 GLIB_AVAILABLE_IN_ALL
696 guint g_dbus_connection_add_filter (GDBusConnection *connection,
697 GDBusMessageFilterFunction filter_function,
699 GDestroyNotify user_data_free_func);
701 GLIB_AVAILABLE_IN_ALL
702 void g_dbus_connection_remove_filter (GDBusConnection *connection,
705 /* ---------------------------------------------------------------------------------------------------- */
710 #endif /* __G_DBUS_CONNECTION_H__ */