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_DBUS_CONNECTION_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
37 #define G_DBUS_CONNECTION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
38 #define G_IS_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
39 #define G_IS_DBUS_CONNECTION_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DBUS_CONNECTION))
41 typedef struct _GDBusConnectionClass GDBusConnectionClass;
42 typedef struct _GDBusConnectionPrivate GDBusConnectionPrivate;
47 * The #GDBusConnection structure contains only private data and
48 * should only be accessed using the provided API.
52 struct _GDBusConnection
55 GObject parent_instance;
56 GDBusConnectionPrivate *priv;
60 * GDBusConnectionClass:
61 * @closed: Signal class handler for the #GDBusConnection::closed signal.
63 * Class structure for #GDBusConnection.
67 struct _GDBusConnectionClass
70 GObjectClass parent_class;
74 void (*closed) (GDBusConnection *connection,
75 gboolean remote_peer_vanished,
79 /* Padding for future expansion */
80 void (*_g_reserved1) (void);
81 void (*_g_reserved2) (void);
82 void (*_g_reserved3) (void);
83 void (*_g_reserved4) (void);
84 void (*_g_reserved5) (void);
85 void (*_g_reserved6) (void);
86 void (*_g_reserved7) (void);
87 void (*_g_reserved8) (void);
90 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
92 /* ---------------------------------------------------------------------------------------------------- */
94 void g_bus_get (GBusType bus_type,
95 GCancellable *cancellable,
96 GAsyncReadyCallback callback,
98 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
100 GDBusConnection *g_bus_get_sync (GBusType bus_type,
101 GCancellable *cancellable,
104 /* ---------------------------------------------------------------------------------------------------- */
106 void g_dbus_connection_new (GIOStream *stream,
108 GDBusConnectionFlags flags,
109 GDBusAuthObserver *observer,
110 GCancellable *cancellable,
111 GAsyncReadyCallback callback,
113 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
115 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
117 GDBusConnectionFlags flags,
118 GDBusAuthObserver *observer,
119 GCancellable *cancellable,
122 void g_dbus_connection_new_for_address (const gchar *address,
123 GDBusConnectionFlags flags,
124 GDBusAuthObserver *observer,
125 GCancellable *cancellable,
126 GAsyncReadyCallback callback,
128 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
130 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
131 GDBusConnectionFlags flags,
132 GDBusAuthObserver *observer,
133 GCancellable *cancellable,
136 /* ---------------------------------------------------------------------------------------------------- */
138 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
139 void g_dbus_connection_close (GDBusConnection *connection);
140 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
141 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
142 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
143 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
144 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
145 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
146 gboolean exit_on_close);
147 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
148 /* ---------------------------------------------------------------------------------------------------- */
150 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
151 GDBusMessage *message,
152 volatile guint32 *out_serial,
154 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
155 GDBusMessage *message,
157 volatile guint32 *out_serial,
158 GCancellable *cancellable,
159 GAsyncReadyCallback callback,
161 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
164 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
165 GDBusMessage *message,
167 volatile guint32 *out_serial,
168 GCancellable *cancellable,
171 /* ---------------------------------------------------------------------------------------------------- */
173 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
174 const gchar *destination_bus_name,
175 const gchar *object_path,
176 const gchar *interface_name,
177 const gchar *signal_name,
178 GVariant *parameters,
180 void g_dbus_connection_call (GDBusConnection *connection,
181 const gchar *bus_name,
182 const gchar *object_path,
183 const gchar *interface_name,
184 const gchar *method_name,
185 GVariant *parameters,
186 const GVariantType *reply_type,
187 GDBusCallFlags flags,
189 GCancellable *cancellable,
190 GAsyncReadyCallback callback,
192 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
195 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
196 const gchar *bus_name,
197 const gchar *object_path,
198 const gchar *interface_name,
199 const gchar *method_name,
200 GVariant *parameters,
201 const GVariantType *reply_type,
202 GDBusCallFlags flags,
204 GCancellable *cancellable,
207 /* ---------------------------------------------------------------------------------------------------- */
211 * GDBusInterfaceMethodCallFunc:
212 * @connection: A #GDBusConnection.
213 * @sender: The unique bus name of the remote caller.
214 * @object_path: The object path that the method was invoked on.
215 * @interface_name: The D-Bus interface name the method was invoked on.
216 * @method_name: The name of the method that was invoked.
217 * @parameters: A #GVariant tuple with parameters.
218 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
219 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
221 * The type of the @method_call function in #GDBusInterfaceVTable.
225 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
227 const gchar *object_path,
228 const gchar *interface_name,
229 const gchar *method_name,
230 GVariant *parameters,
231 GDBusMethodInvocation *invocation,
235 * GDBusInterfaceGetPropertyFunc:
236 * @connection: A #GDBusConnection.
237 * @sender: The unique bus name of the remote caller.
238 * @object_path: The object path that the method was invoked on.
239 * @interface_name: The D-Bus interface name for the property.
240 * @property_name: The name of the property to get the value of.
241 * @error: Return location for error.
242 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
244 * The type of the @get_property function in #GDBusInterfaceVTable.
246 * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
250 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
252 const gchar *object_path,
253 const gchar *interface_name,
254 const gchar *property_name,
259 * GDBusInterfaceSetPropertyFunc:
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 for the property.
264 * @property_name: The name of the property to get the value of.
265 * @value: The value to set the property to.
266 * @error: Return location for error.
267 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
269 * The type of the @set_property function in #GDBusInterfaceVTable.
271 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
275 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
277 const gchar *object_path,
278 const gchar *interface_name,
279 const gchar *property_name,
285 * GDBusInterfaceVTable:
286 * @method_call: Function for handling incoming method calls.
287 * @get_property: Function for getting a property.
288 * @set_property: Function for setting a property.
290 * Virtual table for handling properties and method calls for a D-Bus
293 * If you want to handle getting/setting D-Bus properties asynchronously, simply
294 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
295 * D-Bus interface using g_dbus_connection_register_object().
299 struct _GDBusInterfaceVTable
301 GDBusInterfaceMethodCallFunc method_call;
302 GDBusInterfaceGetPropertyFunc get_property;
303 GDBusInterfaceSetPropertyFunc set_property;
306 /* Padding for future expansion */
307 void (*_g_reserved1) (void);
308 void (*_g_reserved2) (void);
309 void (*_g_reserved3) (void);
310 void (*_g_reserved4) (void);
311 void (*_g_reserved5) (void);
312 void (*_g_reserved6) (void);
313 void (*_g_reserved7) (void);
314 void (*_g_reserved8) (void);
317 guint g_dbus_connection_register_object (GDBusConnection *connection,
318 const gchar *object_path,
319 const GDBusInterfaceInfo *introspection_data,
320 const GDBusInterfaceVTable *vtable,
322 GDestroyNotify user_data_free_func,
324 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
325 guint registration_id);
327 /* ---------------------------------------------------------------------------------------------------- */
330 * GDBusSubtreeEnumerateFunc:
331 * @connection: A #GDBusConnection.
332 * @sender: The unique bus name of the remote caller.
333 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
334 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
336 * The type of the @enumerate function in #GDBusSubtreeVTable.
338 * Returns: A newly allocated array of strings for node names that are children of @object_path.
342 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
344 const gchar *object_path,
348 * GDBusSubtreeIntrospectFunc:
349 * @connection: A #GDBusConnection.
350 * @sender: The unique bus name of the remote caller.
351 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
352 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
353 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
355 * The type of the @introspect function in #GDBusSubtreeVTable.
357 * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
358 * the interfaces implemented by @node.
362 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
364 const gchar *object_path,
369 * GDBusSubtreeDispatchFunc:
370 * @connection: A #GDBusConnection.
371 * @sender: The unique bus name of the remote caller.
372 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
373 * @interface_name: The D-Bus interface name that the method call or property access is for.
374 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
375 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
376 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
378 * The type of the @dispatch function in #GDBusSubtreeVTable.
380 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
384 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
386 const gchar *object_path,
387 const gchar *interface_name,
389 gpointer *out_user_data,
393 * GDBusSubtreeVTable:
394 * @enumerate: Function for enumerating child nodes.
395 * @introspect: Function for introspecting a child node.
396 * @dispatch: Function for dispatching a remote call on a child node.
398 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
402 struct _GDBusSubtreeVTable
404 GDBusSubtreeEnumerateFunc enumerate;
405 GDBusSubtreeIntrospectFunc introspect;
406 GDBusSubtreeDispatchFunc dispatch;
409 /* Padding for future expansion */
410 void (*_g_reserved1) (void);
411 void (*_g_reserved2) (void);
412 void (*_g_reserved3) (void);
413 void (*_g_reserved4) (void);
414 void (*_g_reserved5) (void);
415 void (*_g_reserved6) (void);
416 void (*_g_reserved7) (void);
417 void (*_g_reserved8) (void);
420 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
421 const gchar *object_path,
422 const GDBusSubtreeVTable *vtable,
423 GDBusSubtreeFlags flags,
425 GDestroyNotify user_data_free_func,
427 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
428 guint registration_id);
430 /* ---------------------------------------------------------------------------------------------------- */
433 * GDBusSignalCallback:
434 * @connection: A #GDBusConnection.
435 * @sender_name: The unique bus name of the sender of the signal.
436 * @object_path: The object path that the signal was emitted on.
437 * @interface_name: The name of the interface.
438 * @signal_name: The name of the signal.
439 * @parameters: A #GVariant tuple with parameters for the signal.
440 * @user_data: User data passed when subscribing to the signal.
442 * Signature for callback function used in g_dbus_connection_signal_subscribe().
446 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
447 const gchar *sender_name,
448 const gchar *object_path,
449 const gchar *interface_name,
450 const gchar *signal_name,
451 GVariant *parameters,
454 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
456 const gchar *interface_name,
458 const gchar *object_path,
460 GDBusSignalCallback callback,
462 GDestroyNotify user_data_free_func);
463 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
464 guint subscription_id);
466 /* ---------------------------------------------------------------------------------------------------- */
469 * GDBusMessageFilterFunction:
470 * @connection: A #GDBusConnection.
471 * @message: A #GDBusMessage.
472 * @user_data: User data passed when adding the filter.
474 * Signature for function used in g_dbus_connection_add_filter().
476 * Returns: %TRUE if the filter handled @message, %FALSE to let other
481 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
482 GDBusMessage *message,
485 guint g_dbus_connection_add_filter (GDBusConnection *connection,
486 GDBusMessageFilterFunction filter_function,
488 GDestroyNotify user_data_free_func);
490 void g_dbus_connection_remove_filter (GDBusConnection *connection,
493 /* ---------------------------------------------------------------------------------------------------- */
498 #endif /* __G_DBUS_CONNECTION_H__ */