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 void g_dbus_connection_close (GDBusConnection *connection);
89 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
90 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
91 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
92 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
93 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
94 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
95 gboolean exit_on_close);
96 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
98 /* ---------------------------------------------------------------------------------------------------- */
100 void g_dbus_connection_flush (GDBusConnection *connection,
101 GCancellable *cancellable,
102 GAsyncReadyCallback callback,
104 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
107 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
108 GCancellable *cancellable,
111 /* ---------------------------------------------------------------------------------------------------- */
113 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
114 GDBusMessage *message,
115 volatile guint32 *out_serial,
117 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
118 GDBusMessage *message,
120 volatile guint32 *out_serial,
121 GCancellable *cancellable,
122 GAsyncReadyCallback callback,
124 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
127 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
128 GDBusMessage *message,
130 volatile guint32 *out_serial,
131 GCancellable *cancellable,
134 /* ---------------------------------------------------------------------------------------------------- */
136 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
137 const gchar *destination_bus_name,
138 const gchar *object_path,
139 const gchar *interface_name,
140 const gchar *signal_name,
141 GVariant *parameters,
143 void g_dbus_connection_call (GDBusConnection *connection,
144 const gchar *bus_name,
145 const gchar *object_path,
146 const gchar *interface_name,
147 const gchar *method_name,
148 GVariant *parameters,
149 const GVariantType *reply_type,
150 GDBusCallFlags flags,
152 GCancellable *cancellable,
153 GAsyncReadyCallback callback,
155 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
158 GVariant *g_dbus_connection_call_sync (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,
170 /* ---------------------------------------------------------------------------------------------------- */
174 * GDBusInterfaceMethodCallFunc:
175 * @connection: A #GDBusConnection.
176 * @sender: The unique bus name of the remote caller.
177 * @object_path: The object path that the method was invoked on.
178 * @interface_name: The D-Bus interface name the method was invoked on.
179 * @method_name: The name of the method that was invoked.
180 * @parameters: A #GVariant tuple with parameters.
181 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
182 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
184 * The type of the @method_call function in #GDBusInterfaceVTable.
188 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
190 const gchar *object_path,
191 const gchar *interface_name,
192 const gchar *method_name,
193 GVariant *parameters,
194 GDBusMethodInvocation *invocation,
198 * GDBusInterfaceGetPropertyFunc:
199 * @connection: A #GDBusConnection.
200 * @sender: The unique bus name of the remote caller.
201 * @object_path: The object path that the method was invoked on.
202 * @interface_name: The D-Bus interface name for the property.
203 * @property_name: The name of the property to get the value of.
204 * @error: Return location for error.
205 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
207 * The type of the @get_property function in #GDBusInterfaceVTable.
209 * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
213 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
215 const gchar *object_path,
216 const gchar *interface_name,
217 const gchar *property_name,
222 * GDBusInterfaceSetPropertyFunc:
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 for the property.
227 * @property_name: The name of the property to get the value of.
228 * @value: The value to set the property to.
229 * @error: Return location for error.
230 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
232 * The type of the @set_property function in #GDBusInterfaceVTable.
234 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
238 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
240 const gchar *object_path,
241 const gchar *interface_name,
242 const gchar *property_name,
248 * GDBusInterfaceVTable:
249 * @method_call: Function for handling incoming method calls.
250 * @get_property: Function for getting a property.
251 * @set_property: Function for setting a property.
253 * Virtual table for handling properties and method calls for a D-Bus
256 * If you want to handle getting/setting D-Bus properties asynchronously, simply
257 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
258 * D-Bus interface using g_dbus_connection_register_object().
262 struct _GDBusInterfaceVTable
264 GDBusInterfaceMethodCallFunc method_call;
265 GDBusInterfaceGetPropertyFunc get_property;
266 GDBusInterfaceSetPropertyFunc set_property;
269 /* Padding for future expansion */
273 guint g_dbus_connection_register_object (GDBusConnection *connection,
274 const gchar *object_path,
275 const GDBusInterfaceInfo *interface_info,
276 const GDBusInterfaceVTable *vtable,
278 GDestroyNotify user_data_free_func,
280 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
281 guint registration_id);
283 /* ---------------------------------------------------------------------------------------------------- */
286 * GDBusSubtreeEnumerateFunc:
287 * @connection: A #GDBusConnection.
288 * @sender: The unique bus name of the remote caller.
289 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
290 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
292 * The type of the @enumerate function in #GDBusSubtreeVTable.
294 * Returns: A newly allocated array of strings for node names that are children of @object_path.
298 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
300 const gchar *object_path,
304 * GDBusSubtreeIntrospectFunc:
305 * @connection: A #GDBusConnection.
306 * @sender: The unique bus name of the remote caller.
307 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
308 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
309 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
311 * The type of the @introspect function in #GDBusSubtreeVTable.
313 * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
314 * the interfaces implemented by @node.
318 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
320 const gchar *object_path,
325 * GDBusSubtreeDispatchFunc:
326 * @connection: A #GDBusConnection.
327 * @sender: The unique bus name of the remote caller.
328 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
329 * @interface_name: The D-Bus interface name that the method call or property access is for.
330 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
331 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
332 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
334 * The type of the @dispatch function in #GDBusSubtreeVTable.
336 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
340 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
342 const gchar *object_path,
343 const gchar *interface_name,
345 gpointer *out_user_data,
349 * GDBusSubtreeVTable:
350 * @enumerate: Function for enumerating child nodes.
351 * @introspect: Function for introspecting a child node.
352 * @dispatch: Function for dispatching a remote call on a child node.
354 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
358 struct _GDBusSubtreeVTable
360 GDBusSubtreeEnumerateFunc enumerate;
361 GDBusSubtreeIntrospectFunc introspect;
362 GDBusSubtreeDispatchFunc dispatch;
365 /* Padding for future expansion */
366 void (*_g_reserved1) (void);
367 void (*_g_reserved2) (void);
368 void (*_g_reserved3) (void);
369 void (*_g_reserved4) (void);
370 void (*_g_reserved5) (void);
371 void (*_g_reserved6) (void);
372 void (*_g_reserved7) (void);
373 void (*_g_reserved8) (void);
376 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
377 const gchar *object_path,
378 const GDBusSubtreeVTable *vtable,
379 GDBusSubtreeFlags flags,
381 GDestroyNotify user_data_free_func,
383 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
384 guint registration_id);
386 /* ---------------------------------------------------------------------------------------------------- */
389 * GDBusSignalCallback:
390 * @connection: A #GDBusConnection.
391 * @sender_name: The unique bus name of the sender of the signal.
392 * @object_path: The object path that the signal was emitted on.
393 * @interface_name: The name of the interface.
394 * @signal_name: The name of the signal.
395 * @parameters: A #GVariant tuple with parameters for the signal.
396 * @user_data: User data passed when subscribing to the signal.
398 * Signature for callback function used in g_dbus_connection_signal_subscribe().
402 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
403 const gchar *sender_name,
404 const gchar *object_path,
405 const gchar *interface_name,
406 const gchar *signal_name,
407 GVariant *parameters,
410 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
412 const gchar *interface_name,
414 const gchar *object_path,
416 GDBusSignalCallback callback,
418 GDestroyNotify user_data_free_func);
419 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
420 guint subscription_id);
422 /* ---------------------------------------------------------------------------------------------------- */
425 * GDBusMessageFilterFunction:
426 * @connection: A #GDBusConnection.
427 * @message: A #GDBusMessage.
428 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
429 * a message to be sent to the other peer.
430 * @user_data: User data passed when adding the filter.
432 * Signature for function used in g_dbus_connection_add_filter().
434 * Returns: %TRUE if the filter handled @message, %FALSE to let other
439 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
440 GDBusMessage *message,
444 guint g_dbus_connection_add_filter (GDBusConnection *connection,
445 GDBusMessageFilterFunction filter_function,
447 GDestroyNotify user_data_free_func);
449 void g_dbus_connection_remove_filter (GDBusConnection *connection,
452 /* ---------------------------------------------------------------------------------------------------- */
457 #endif /* __G_DBUS_CONNECTION_H__ */