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
,
185 /* ---------------------------------------------------------------------------------------------------- */
189 * GDBusInterfaceMethodCallFunc:
190 * @connection: A #GDBusConnection.
191 * @sender: The unique bus name of the remote caller.
192 * @object_path: The object path that the method was invoked on.
193 * @interface_name: The D-Bus interface name the method was invoked on.
194 * @method_name: The name of the method that was invoked.
195 * @parameters: A #GVariant tuple with parameters.
196 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
197 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
199 * The type of the @method_call function in #GDBusInterfaceVTable.
203 typedef void (*GDBusInterfaceMethodCallFunc
) (GDBusConnection
*connection
,
205 const gchar
*object_path
,
206 const gchar
*interface_name
,
207 const gchar
*method_name
,
208 GVariant
*parameters
,
209 GDBusMethodInvocation
*invocation
,
213 * GDBusInterfaceGetPropertyFunc:
214 * @connection: A #GDBusConnection.
215 * @sender: The unique bus name of the remote caller.
216 * @object_path: The object path that the method was invoked on.
217 * @interface_name: The D-Bus interface name for the property.
218 * @property_name: The name of the property to get the value of.
219 * @error: Return location for error.
220 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
222 * The type of the @get_property function in #GDBusInterfaceVTable.
224 * Returns: A #GVariant with the value for @property_name or %NULL if
225 * @error is set. If the returned #GVariant is floating, it is
226 * consumed - otherwise its reference count is decreased by one.
230 typedef GVariant
*(*GDBusInterfaceGetPropertyFunc
) (GDBusConnection
*connection
,
232 const gchar
*object_path
,
233 const gchar
*interface_name
,
234 const gchar
*property_name
,
239 * GDBusInterfaceSetPropertyFunc:
240 * @connection: A #GDBusConnection.
241 * @sender: The unique bus name of the remote caller.
242 * @object_path: The object path that the method was invoked on.
243 * @interface_name: The D-Bus interface name for the property.
244 * @property_name: The name of the property to get the value of.
245 * @value: The value to set the property to.
246 * @error: Return location for error.
247 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
249 * The type of the @set_property function in #GDBusInterfaceVTable.
251 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
255 typedef gboolean (*GDBusInterfaceSetPropertyFunc
) (GDBusConnection
*connection
,
257 const gchar
*object_path
,
258 const gchar
*interface_name
,
259 const gchar
*property_name
,
265 * GDBusInterfaceVTable:
266 * @method_call: Function for handling incoming method calls.
267 * @get_property: Function for getting a property.
268 * @set_property: Function for setting a property.
270 * Virtual table for handling properties and method calls for a D-Bus
273 * If you want to handle getting/setting D-Bus properties asynchronously, simply
274 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
275 * D-Bus interface using g_dbus_connection_register_object().
279 struct _GDBusInterfaceVTable
281 GDBusInterfaceMethodCallFunc method_call
;
282 GDBusInterfaceGetPropertyFunc get_property
;
283 GDBusInterfaceSetPropertyFunc set_property
;
286 /* Padding for future expansion - also remember to update
287 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
293 guint
g_dbus_connection_register_object (GDBusConnection
*connection
,
294 const gchar
*object_path
,
295 GDBusInterfaceInfo
*interface_info
,
296 const GDBusInterfaceVTable
*vtable
,
298 GDestroyNotify user_data_free_func
,
300 gboolean
g_dbus_connection_unregister_object (GDBusConnection
*connection
,
301 guint registration_id
);
303 /* ---------------------------------------------------------------------------------------------------- */
306 * GDBusSubtreeEnumerateFunc:
307 * @connection: A #GDBusConnection.
308 * @sender: The unique bus name of the remote caller.
309 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
310 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
312 * The type of the @enumerate function in #GDBusSubtreeVTable.
314 * This function is called when generating introspection data and also
315 * when preparing to dispatch incoming messages in the event that the
316 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
317 * specified (ie: to verify that the object path is valid).
319 * Hierarchies are not supported; the items that you return should not
320 * contain the '/' character.
322 * The return value will be freed with g_strfreev().
324 * Returns: A newly allocated array of strings for node names that are children of @object_path.
328 typedef gchar
** (*GDBusSubtreeEnumerateFunc
) (GDBusConnection
*connection
,
330 const gchar
*object_path
,
334 * GDBusSubtreeIntrospectFunc:
335 * @connection: A #GDBusConnection.
336 * @sender: The unique bus name of the remote caller.
337 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
338 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
339 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
341 * The type of the @introspect function in #GDBusSubtreeVTable.
343 * Subtrees are flat. @node, if non-%NULL, is always exactly one
344 * segment of the object path (ie: it never contains a slash).
346 * This function should return %NULL to indicate that there is no object
349 * If this function returns non-%NULL, the return value is expected to
350 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
351 * structures describing the interfaces implemented by @node. This
352 * array will have g_dbus_interface_info_unref() called on each item
353 * before being freed with g_free().
355 * The difference between returning %NULL and an array containing zero
356 * items is that the standard DBus interfaces will returned to the
357 * remote introspector in the empty array case, but not in the %NULL
360 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
364 typedef GDBusInterfaceInfo
** (*GDBusSubtreeIntrospectFunc
) (GDBusConnection
*connection
,
366 const gchar
*object_path
,
371 * GDBusSubtreeDispatchFunc:
372 * @connection: A #GDBusConnection.
373 * @sender: The unique bus name of the remote caller.
374 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
375 * @interface_name: The D-Bus interface name that the method call or property access is for.
376 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
377 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
378 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
380 * The type of the @dispatch function in #GDBusSubtreeVTable.
382 * Subtrees are flat. @node, if non-%NULL, is always exactly one
383 * segment of the object path (ie: it never contains a slash).
385 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
389 typedef const GDBusInterfaceVTable
* (*GDBusSubtreeDispatchFunc
) (GDBusConnection
*connection
,
391 const gchar
*object_path
,
392 const gchar
*interface_name
,
394 gpointer
*out_user_data
,
398 * GDBusSubtreeVTable:
399 * @enumerate: Function for enumerating child nodes.
400 * @introspect: Function for introspecting a child node.
401 * @dispatch: Function for dispatching a remote call on a child node.
403 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
407 struct _GDBusSubtreeVTable
409 GDBusSubtreeEnumerateFunc enumerate
;
410 GDBusSubtreeIntrospectFunc introspect
;
411 GDBusSubtreeDispatchFunc dispatch
;
414 /* Padding for future expansion - also remember to update
415 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
421 guint
g_dbus_connection_register_subtree (GDBusConnection
*connection
,
422 const gchar
*object_path
,
423 const GDBusSubtreeVTable
*vtable
,
424 GDBusSubtreeFlags flags
,
426 GDestroyNotify user_data_free_func
,
428 gboolean
g_dbus_connection_unregister_subtree (GDBusConnection
*connection
,
429 guint registration_id
);
431 /* ---------------------------------------------------------------------------------------------------- */
434 * GDBusSignalCallback:
435 * @connection: A #GDBusConnection.
436 * @sender_name: The unique bus name of the sender of the signal.
437 * @object_path: The object path that the signal was emitted on.
438 * @interface_name: The name of the interface.
439 * @signal_name: The name of the signal.
440 * @parameters: A #GVariant tuple with parameters for the signal.
441 * @user_data: User data passed when subscribing to the signal.
443 * Signature for callback function used in g_dbus_connection_signal_subscribe().
447 typedef void (*GDBusSignalCallback
) (GDBusConnection
*connection
,
448 const gchar
*sender_name
,
449 const gchar
*object_path
,
450 const gchar
*interface_name
,
451 const gchar
*signal_name
,
452 GVariant
*parameters
,
455 guint
g_dbus_connection_signal_subscribe (GDBusConnection
*connection
,
457 const gchar
*interface_name
,
459 const gchar
*object_path
,
461 GDBusSignalFlags flags
,
462 GDBusSignalCallback callback
,
464 GDestroyNotify user_data_free_func
);
465 void g_dbus_connection_signal_unsubscribe (GDBusConnection
*connection
,
466 guint subscription_id
);
468 /* ---------------------------------------------------------------------------------------------------- */
471 * GDBusMessageFilterFunction:
472 * @connection: (transfer none): A #GDBusConnection.
473 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
474 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
475 * a message to be sent to the other peer.
476 * @user_data: User data passed when adding the filter.
478 * Signature for function used in g_dbus_connection_add_filter().
480 * A filter function is passed a #GDBusMessage and expected to return
481 * a #GDBusMessage too. Passive filter functions that don't modify the
482 * message can simply return the @message object:
484 * static GDBusMessage *
485 * passive_filter (GDBusConnection *connection
486 * GDBusMessage *message,
488 * gpointer user_data)
490 * /<!-- -->* inspect @message *<!-- -->/
494 * Filter functions that wants to drop a message can simply return %NULL:
496 * static GDBusMessage *
497 * drop_filter (GDBusConnection *connection
498 * GDBusMessage *message,
500 * gpointer user_data)
502 * if (should_drop_message)
504 * g_object_unref (message);
510 * Finally, a filter function may modify a message by copying it:
512 * static GDBusMessage *
513 * modifying_filter (GDBusConnection *connection
514 * GDBusMessage *message,
516 * gpointer user_data)
518 * GDBusMessage *copy;
522 * copy = g_dbus_message_copy (message, &error);
523 * /<!-- -->* handle @error being is set *<!-- -->/
524 * g_object_unref (message);
526 * /<!-- -->* modify @copy *<!-- -->/
531 * If the returned #GDBusMessage is different from @message and cannot
532 * be sent on @connection (it could use features, such as file
533 * descriptors, not compatible with @connection), then a warning is
534 * logged to <emphasis>standard error</emphasis>. Applications can
535 * check this ahead of time using g_dbus_message_to_blob() passing a
536 * #GDBusCapabilityFlags value obtained from @connection.
538 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
539 * g_object_unref() or %NULL to drop the message. Passive filter
540 * functions can simply return the passed @message object.
544 typedef GDBusMessage
*(*GDBusMessageFilterFunction
) (GDBusConnection
*connection
,
545 GDBusMessage
*message
,
549 guint
g_dbus_connection_add_filter (GDBusConnection
*connection
,
550 GDBusMessageFilterFunction filter_function
,
552 GDestroyNotify user_data_free_func
);
554 void g_dbus_connection_remove_filter (GDBusConnection
*connection
,
557 /* ---------------------------------------------------------------------------------------------------- */
562 #endif /* __G_DBUS_CONNECTION_H__ */