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 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
24 #error "Only <gio/gio.h> can be included directly."
27 #ifndef __G_DBUS_CONNECTION_H__
28 #define __G_DBUS_CONNECTION_H__
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))
38 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
40 /* ---------------------------------------------------------------------------------------------------- */
42 void g_bus_get (GBusType bus_type,
43 GCancellable *cancellable,
44 GAsyncReadyCallback callback,
46 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
48 GDBusConnection *g_bus_get_sync (GBusType bus_type,
49 GCancellable *cancellable,
52 /* ---------------------------------------------------------------------------------------------------- */
54 void g_dbus_connection_new (GIOStream *stream,
56 GDBusConnectionFlags flags,
57 GDBusAuthObserver *observer,
58 GCancellable *cancellable,
59 GAsyncReadyCallback callback,
61 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
63 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
65 GDBusConnectionFlags flags,
66 GDBusAuthObserver *observer,
67 GCancellable *cancellable,
70 void g_dbus_connection_new_for_address (const gchar *address,
71 GDBusConnectionFlags flags,
72 GDBusAuthObserver *observer,
73 GCancellable *cancellable,
74 GAsyncReadyCallback callback,
76 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
78 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
79 GDBusConnectionFlags flags,
80 GDBusAuthObserver *observer,
81 GCancellable *cancellable,
84 /* ---------------------------------------------------------------------------------------------------- */
86 void g_dbus_connection_start_message_processing (GDBusConnection *connection);
87 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
88 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
89 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
90 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
91 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
92 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
93 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
94 gboolean exit_on_close);
95 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
97 /* ---------------------------------------------------------------------------------------------------- */
99 void g_dbus_connection_close (GDBusConnection *connection,
100 GCancellable *cancellable,
101 GAsyncReadyCallback callback,
103 gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
106 gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
107 GCancellable *cancellable,
110 /* ---------------------------------------------------------------------------------------------------- */
112 void g_dbus_connection_flush (GDBusConnection *connection,
113 GCancellable *cancellable,
114 GAsyncReadyCallback callback,
116 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
119 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
120 GCancellable *cancellable,
123 /* ---------------------------------------------------------------------------------------------------- */
125 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
126 GDBusMessage *message,
127 GDBusSendMessageFlags flags,
128 volatile guint32 *out_serial,
130 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
131 GDBusMessage *message,
132 GDBusSendMessageFlags flags,
134 volatile guint32 *out_serial,
135 GCancellable *cancellable,
136 GAsyncReadyCallback callback,
138 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
141 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
142 GDBusMessage *message,
143 GDBusSendMessageFlags flags,
145 volatile guint32 *out_serial,
146 GCancellable *cancellable,
149 /* ---------------------------------------------------------------------------------------------------- */
151 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
152 const gchar *destination_bus_name,
153 const gchar *object_path,
154 const gchar *interface_name,
155 const gchar *signal_name,
156 GVariant *parameters,
158 void g_dbus_connection_call (GDBusConnection *connection,
159 const gchar *bus_name,
160 const gchar *object_path,
161 const gchar *interface_name,
162 const gchar *method_name,
163 GVariant *parameters,
164 const GVariantType *reply_type,
165 GDBusCallFlags flags,
167 GCancellable *cancellable,
168 GAsyncReadyCallback callback,
170 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
173 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
174 const gchar *bus_name,
175 const gchar *object_path,
176 const gchar *interface_name,
177 const gchar *method_name,
178 GVariant *parameters,
179 const GVariantType *reply_type,
180 GDBusCallFlags flags,
182 GCancellable *cancellable,
184 GLIB_AVAILABLE_IN_2_30
185 void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection,
186 const gchar *bus_name,
187 const gchar *object_path,
188 const gchar *interface_name,
189 const gchar *method_name,
190 GVariant *parameters,
191 const GVariantType *reply_type,
192 GDBusCallFlags flags,
194 GUnixFDList *fd_list,
195 GCancellable *cancellable,
196 GAsyncReadyCallback callback,
198 GLIB_AVAILABLE_IN_2_30
199 GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
200 GUnixFDList **out_fd_list,
203 GLIB_AVAILABLE_IN_2_30
204 GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection,
205 const gchar *bus_name,
206 const gchar *object_path,
207 const gchar *interface_name,
208 const gchar *method_name,
209 GVariant *parameters,
210 const GVariantType *reply_type,
211 GDBusCallFlags flags,
213 GUnixFDList *fd_list,
214 GUnixFDList **out_fd_list,
215 GCancellable *cancellable,
218 /* ---------------------------------------------------------------------------------------------------- */
222 * GDBusInterfaceMethodCallFunc:
223 * @connection: A #GDBusConnection.
224 * @sender: The unique bus name of the remote caller.
225 * @object_path: The object path that the method was invoked on.
226 * @interface_name: The D-Bus interface name the method was invoked on.
227 * @method_name: The name of the method that was invoked.
228 * @parameters: A #GVariant tuple with parameters.
229 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
230 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
232 * The type of the @method_call function in #GDBusInterfaceVTable.
236 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
238 const gchar *object_path,
239 const gchar *interface_name,
240 const gchar *method_name,
241 GVariant *parameters,
242 GDBusMethodInvocation *invocation,
246 * GDBusInterfaceGetPropertyFunc:
247 * @connection: A #GDBusConnection.
248 * @sender: The unique bus name of the remote caller.
249 * @object_path: The object path that the method was invoked on.
250 * @interface_name: The D-Bus interface name for the property.
251 * @property_name: The name of the property to get the value of.
252 * @error: Return location for error.
253 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
255 * The type of the @get_property function in #GDBusInterfaceVTable.
257 * Returns: A #GVariant with the value for @property_name or %NULL if
258 * @error is set. If the returned #GVariant is floating, it is
259 * consumed - otherwise its reference count is decreased by one.
263 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
265 const gchar *object_path,
266 const gchar *interface_name,
267 const gchar *property_name,
272 * GDBusInterfaceSetPropertyFunc:
273 * @connection: A #GDBusConnection.
274 * @sender: The unique bus name of the remote caller.
275 * @object_path: The object path that the method was invoked on.
276 * @interface_name: The D-Bus interface name for the property.
277 * @property_name: The name of the property to get the value of.
278 * @value: The value to set the property to.
279 * @error: Return location for error.
280 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
282 * The type of the @set_property function in #GDBusInterfaceVTable.
284 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
288 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
290 const gchar *object_path,
291 const gchar *interface_name,
292 const gchar *property_name,
298 * GDBusInterfaceVTable:
299 * @method_call: Function for handling incoming method calls.
300 * @get_property: Function for getting a property.
301 * @set_property: Function for setting a property.
303 * Virtual table for handling properties and method calls for a D-Bus
306 * If you want to handle getting/setting D-Bus properties asynchronously, simply
307 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
308 * D-Bus interface using g_dbus_connection_register_object().
312 struct _GDBusInterfaceVTable
314 GDBusInterfaceMethodCallFunc method_call;
315 GDBusInterfaceGetPropertyFunc get_property;
316 GDBusInterfaceSetPropertyFunc set_property;
319 /* Padding for future expansion - also remember to update
320 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
326 guint g_dbus_connection_register_object (GDBusConnection *connection,
327 const gchar *object_path,
328 GDBusInterfaceInfo *interface_info,
329 const GDBusInterfaceVTable *vtable,
331 GDestroyNotify user_data_free_func,
333 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
334 guint registration_id);
336 /* ---------------------------------------------------------------------------------------------------- */
339 * GDBusSubtreeEnumerateFunc:
340 * @connection: A #GDBusConnection.
341 * @sender: The unique bus name of the remote caller.
342 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
343 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
345 * The type of the @enumerate function in #GDBusSubtreeVTable.
347 * This function is called when generating introspection data and also
348 * when preparing to dispatch incoming messages in the event that the
349 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
350 * specified (ie: to verify that the object path is valid).
352 * Hierarchies are not supported; the items that you return should not
353 * contain the '/' character.
355 * The return value will be freed with g_strfreev().
357 * Returns: A newly allocated array of strings for node names that are children of @object_path.
361 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
363 const gchar *object_path,
367 * GDBusSubtreeIntrospectFunc:
368 * @connection: A #GDBusConnection.
369 * @sender: The unique bus name of the remote caller.
370 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
371 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
372 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
374 * The type of the @introspect function in #GDBusSubtreeVTable.
376 * Subtrees are flat. @node, if non-%NULL, is always exactly one
377 * segment of the object path (ie: it never contains a slash).
379 * This function should return %NULL to indicate that there is no object
382 * If this function returns non-%NULL, the return value is expected to
383 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
384 * structures describing the interfaces implemented by @node. This
385 * array will have g_dbus_interface_info_unref() called on each item
386 * before being freed with g_free().
388 * The difference between returning %NULL and an array containing zero
389 * items is that the standard DBus interfaces will returned to the
390 * remote introspector in the empty array case, but not in the %NULL
393 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
397 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
399 const gchar *object_path,
404 * GDBusSubtreeDispatchFunc:
405 * @connection: A #GDBusConnection.
406 * @sender: The unique bus name of the remote caller.
407 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
408 * @interface_name: The D-Bus interface name that the method call or property access is for.
409 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
410 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
411 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
413 * The type of the @dispatch 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 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
422 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
424 const gchar *object_path,
425 const gchar *interface_name,
427 gpointer *out_user_data,
431 * GDBusSubtreeVTable:
432 * @enumerate: Function for enumerating child nodes.
433 * @introspect: Function for introspecting a child node.
434 * @dispatch: Function for dispatching a remote call on a child node.
436 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
440 struct _GDBusSubtreeVTable
442 GDBusSubtreeEnumerateFunc enumerate;
443 GDBusSubtreeIntrospectFunc introspect;
444 GDBusSubtreeDispatchFunc dispatch;
447 /* Padding for future expansion - also remember to update
448 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
454 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
455 const gchar *object_path,
456 const GDBusSubtreeVTable *vtable,
457 GDBusSubtreeFlags flags,
459 GDestroyNotify user_data_free_func,
461 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
462 guint registration_id);
464 /* ---------------------------------------------------------------------------------------------------- */
467 * GDBusSignalCallback:
468 * @connection: A #GDBusConnection.
469 * @sender_name: The unique bus name of the sender of the signal.
470 * @object_path: The object path that the signal was emitted on.
471 * @interface_name: The name of the interface.
472 * @signal_name: The name of the signal.
473 * @parameters: A #GVariant tuple with parameters for the signal.
474 * @user_data: User data passed when subscribing to the signal.
476 * Signature for callback function used in g_dbus_connection_signal_subscribe().
480 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
481 const gchar *sender_name,
482 const gchar *object_path,
483 const gchar *interface_name,
484 const gchar *signal_name,
485 GVariant *parameters,
488 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
490 const gchar *interface_name,
492 const gchar *object_path,
494 GDBusSignalFlags flags,
495 GDBusSignalCallback callback,
497 GDestroyNotify user_data_free_func);
498 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
499 guint subscription_id);
501 /* ---------------------------------------------------------------------------------------------------- */
504 * GDBusMessageFilterFunction:
505 * @connection: (transfer none): A #GDBusConnection.
506 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
507 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
508 * a message to be sent to the other peer.
509 * @user_data: User data passed when adding the filter.
511 * Signature for function used in g_dbus_connection_add_filter().
513 * A filter function is passed a #GDBusMessage and expected to return
514 * a #GDBusMessage too. Passive filter functions that don't modify the
515 * message can simply return the @message object:
517 * static GDBusMessage *
518 * passive_filter (GDBusConnection *connection
519 * GDBusMessage *message,
521 * gpointer user_data)
523 * /<!-- -->* inspect @message *<!-- -->/
527 * Filter functions that wants to drop a message can simply return %NULL:
529 * static GDBusMessage *
530 * drop_filter (GDBusConnection *connection
531 * GDBusMessage *message,
533 * gpointer user_data)
535 * if (should_drop_message)
537 * g_object_unref (message);
543 * Finally, a filter function may modify a message by copying it:
545 * static GDBusMessage *
546 * modifying_filter (GDBusConnection *connection
547 * GDBusMessage *message,
549 * gpointer user_data)
551 * GDBusMessage *copy;
555 * copy = g_dbus_message_copy (message, &error);
556 * /<!-- -->* handle @error being is set *<!-- -->/
557 * g_object_unref (message);
559 * /<!-- -->* modify @copy *<!-- -->/
564 * If the returned #GDBusMessage is different from @message and cannot
565 * be sent on @connection (it could use features, such as file
566 * descriptors, not compatible with @connection), then a warning is
567 * logged to <emphasis>standard error</emphasis>. Applications can
568 * check this ahead of time using g_dbus_message_to_blob() passing a
569 * #GDBusCapabilityFlags value obtained from @connection.
571 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
572 * g_object_unref() or %NULL to drop the message. Passive filter
573 * functions can simply return the passed @message object.
577 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
578 GDBusMessage *message,
582 guint g_dbus_connection_add_filter (GDBusConnection *connection,
583 GDBusMessageFilterFunction filter_function,
585 GDestroyNotify user_data_free_func);
587 void g_dbus_connection_remove_filter (GDBusConnection *connection,
590 /* ---------------------------------------------------------------------------------------------------- */
595 #endif /* __G_DBUS_CONNECTION_H__ */