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 * Since 2.38, if you want to handle getting/setting D-Bus properties
344 * asynchronously, give %NULL as your get_property() or set_property()
345 * function. The D-Bus call will be directed to your @method_call
346 * function, with the provided @interface_name set to
347 * <literal>"org.freedesktop.DBus.Properties"</literal>.
349 * The usual checks on the validity of the calls is performed. For
350 * <literal>'Get'</literal> calls, an error is automatically returned if
351 * the property does not exist or the permissions do not allow access.
352 * The same checks are performed for <literal>'Set'</literal> calls, and
353 * the provided value is also checked for being the correct type.
355 * For both <literal>'Get'</literal> and <literal>'Set'</literal> calls,
356 * the #GDBusMethodInvocation passed to the method_call handler can be
357 * queried with g_dbus_method_invocation_get_property_info() to get a
358 * pointer to the #GDBusPropertyInfo of the property.
360 * If you have readable properties specified in your interface info, you
361 * must ensure that you either provide a non-%NULL @get_property()
362 * function or provide implementations of both the
363 * <literal>'Get'</literal> and <literal>'GetAll'</literal> methods on
364 * the <literal>'org.freedesktop.DBus.Properties'</literal> interface in
365 * your @method_call function. Note that the required return type of
366 * the <literal>'Get'</literal> call is <literal>(v)</literal>, not the
367 * type of the property. <literal>'GetAll'</literal> expects a return
368 * value of type <literal>a{sv}</literal>.
370 * If you have writable properties specified in your interface info, you
371 * must ensure that you either provide a non-%NULL @set_property()
372 * function or provide an implementation of the <literal>'Set'</literal>
373 * call. If implementing the call, you must return the value of type
374 * %G_VARIANT_TYPE_UNIT.
378 struct _GDBusInterfaceVTable
380 GDBusInterfaceMethodCallFunc method_call
;
381 GDBusInterfaceGetPropertyFunc get_property
;
382 GDBusInterfaceSetPropertyFunc set_property
;
385 /* Padding for future expansion - also remember to update
386 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
392 GLIB_AVAILABLE_IN_ALL
393 guint
g_dbus_connection_register_object (GDBusConnection
*connection
,
394 const gchar
*object_path
,
395 GDBusInterfaceInfo
*interface_info
,
396 const GDBusInterfaceVTable
*vtable
,
398 GDestroyNotify user_data_free_func
,
400 GLIB_AVAILABLE_IN_ALL
401 gboolean
g_dbus_connection_unregister_object (GDBusConnection
*connection
,
402 guint registration_id
);
404 /* ---------------------------------------------------------------------------------------------------- */
407 * GDBusSubtreeEnumerateFunc:
408 * @connection: A #GDBusConnection.
409 * @sender: The unique bus name of the remote caller.
410 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
411 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
413 * The type of the @enumerate function in #GDBusSubtreeVTable.
415 * This function is called when generating introspection data and also
416 * when preparing to dispatch incoming messages in the event that the
417 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
418 * specified (ie: to verify that the object path is valid).
420 * Hierarchies are not supported; the items that you return should not
421 * contain the '/' character.
423 * The return value will be freed with g_strfreev().
425 * Returns: A newly allocated array of strings for node names that are children of @object_path.
429 typedef gchar
** (*GDBusSubtreeEnumerateFunc
) (GDBusConnection
*connection
,
431 const gchar
*object_path
,
435 * GDBusSubtreeIntrospectFunc:
436 * @connection: A #GDBusConnection.
437 * @sender: The unique bus name of the remote caller.
438 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
439 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
440 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
442 * The type of the @introspect function in #GDBusSubtreeVTable.
444 * Subtrees are flat. @node, if non-%NULL, is always exactly one
445 * segment of the object path (ie: it never contains a slash).
447 * This function should return %NULL to indicate that there is no object
450 * If this function returns non-%NULL, the return value is expected to
451 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
452 * structures describing the interfaces implemented by @node. This
453 * array will have g_dbus_interface_info_unref() called on each item
454 * before being freed with g_free().
456 * The difference between returning %NULL and an array containing zero
457 * items is that the standard DBus interfaces will returned to the
458 * remote introspector in the empty array case, but not in the %NULL
461 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
465 typedef GDBusInterfaceInfo
** (*GDBusSubtreeIntrospectFunc
) (GDBusConnection
*connection
,
467 const gchar
*object_path
,
472 * GDBusSubtreeDispatchFunc:
473 * @connection: A #GDBusConnection.
474 * @sender: The unique bus name of the remote caller.
475 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
476 * @interface_name: The D-Bus interface name that the method call or property access is for.
477 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
478 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
479 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
481 * The type of the @dispatch function in #GDBusSubtreeVTable.
483 * Subtrees are flat. @node, if non-%NULL, is always exactly one
484 * segment of the object path (ie: it never contains a slash).
486 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
490 typedef const GDBusInterfaceVTable
* (*GDBusSubtreeDispatchFunc
) (GDBusConnection
*connection
,
492 const gchar
*object_path
,
493 const gchar
*interface_name
,
495 gpointer
*out_user_data
,
499 * GDBusSubtreeVTable:
500 * @enumerate: Function for enumerating child nodes.
501 * @introspect: Function for introspecting a child node.
502 * @dispatch: Function for dispatching a remote call on a child node.
504 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
508 struct _GDBusSubtreeVTable
510 GDBusSubtreeEnumerateFunc enumerate
;
511 GDBusSubtreeIntrospectFunc introspect
;
512 GDBusSubtreeDispatchFunc dispatch
;
515 /* Padding for future expansion - also remember to update
516 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
522 GLIB_AVAILABLE_IN_ALL
523 guint
g_dbus_connection_register_subtree (GDBusConnection
*connection
,
524 const gchar
*object_path
,
525 const GDBusSubtreeVTable
*vtable
,
526 GDBusSubtreeFlags flags
,
528 GDestroyNotify user_data_free_func
,
530 GLIB_AVAILABLE_IN_ALL
531 gboolean
g_dbus_connection_unregister_subtree (GDBusConnection
*connection
,
532 guint registration_id
);
534 /* ---------------------------------------------------------------------------------------------------- */
537 * GDBusSignalCallback:
538 * @connection: A #GDBusConnection.
539 * @sender_name: The unique bus name of the sender of the signal.
540 * @object_path: The object path that the signal was emitted on.
541 * @interface_name: The name of the interface.
542 * @signal_name: The name of the signal.
543 * @parameters: A #GVariant tuple with parameters for the signal.
544 * @user_data: User data passed when subscribing to the signal.
546 * Signature for callback function used in g_dbus_connection_signal_subscribe().
550 typedef void (*GDBusSignalCallback
) (GDBusConnection
*connection
,
551 const gchar
*sender_name
,
552 const gchar
*object_path
,
553 const gchar
*interface_name
,
554 const gchar
*signal_name
,
555 GVariant
*parameters
,
558 GLIB_AVAILABLE_IN_ALL
559 guint
g_dbus_connection_signal_subscribe (GDBusConnection
*connection
,
561 const gchar
*interface_name
,
563 const gchar
*object_path
,
565 GDBusSignalFlags flags
,
566 GDBusSignalCallback callback
,
568 GDestroyNotify user_data_free_func
);
569 GLIB_AVAILABLE_IN_ALL
570 void g_dbus_connection_signal_unsubscribe (GDBusConnection
*connection
,
571 guint subscription_id
);
573 /* ---------------------------------------------------------------------------------------------------- */
576 * GDBusMessageFilterFunction:
577 * @connection: (transfer none): A #GDBusConnection.
578 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
579 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
580 * a message to be sent to the other peer.
581 * @user_data: User data passed when adding the filter.
583 * Signature for function used in g_dbus_connection_add_filter().
585 * A filter function is passed a #GDBusMessage and expected to return
586 * a #GDBusMessage too. Passive filter functions that don't modify the
587 * message can simply return the @message object:
589 * static GDBusMessage *
590 * passive_filter (GDBusConnection *connection
591 * GDBusMessage *message,
593 * gpointer user_data)
595 * /<!-- -->* inspect @message *<!-- -->/
599 * Filter functions that wants to drop a message can simply return %NULL:
601 * static GDBusMessage *
602 * drop_filter (GDBusConnection *connection
603 * GDBusMessage *message,
605 * gpointer user_data)
607 * if (should_drop_message)
609 * g_object_unref (message);
615 * Finally, a filter function may modify a message by copying it:
617 * static GDBusMessage *
618 * modifying_filter (GDBusConnection *connection
619 * GDBusMessage *message,
621 * gpointer user_data)
623 * GDBusMessage *copy;
627 * copy = g_dbus_message_copy (message, &error);
628 * /<!-- -->* handle @error being is set *<!-- -->/
629 * g_object_unref (message);
631 * /<!-- -->* modify @copy *<!-- -->/
636 * If the returned #GDBusMessage is different from @message and cannot
637 * be sent on @connection (it could use features, such as file
638 * descriptors, not compatible with @connection), then a warning is
639 * logged to <emphasis>standard error</emphasis>. Applications can
640 * check this ahead of time using g_dbus_message_to_blob() passing a
641 * #GDBusCapabilityFlags value obtained from @connection.
643 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
644 * g_object_unref() or %NULL to drop the message. Passive filter
645 * functions can simply return the passed @message object.
649 typedef GDBusMessage
*(*GDBusMessageFilterFunction
) (GDBusConnection
*connection
,
650 GDBusMessage
*message
,
654 GLIB_AVAILABLE_IN_ALL
655 guint
g_dbus_connection_add_filter (GDBusConnection
*connection
,
656 GDBusMessageFilterFunction filter_function
,
658 GDestroyNotify user_data_free_func
);
660 GLIB_AVAILABLE_IN_ALL
661 void g_dbus_connection_remove_filter (GDBusConnection
*connection
,
664 /* ---------------------------------------------------------------------------------------------------- */
669 #endif /* __G_DBUS_CONNECTION_H__ */