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;
59 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
61 /* ---------------------------------------------------------------------------------------------------- */
63 void g_bus_get (GBusType bus_type,
64 GCancellable *cancellable,
65 GAsyncReadyCallback callback,
67 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
69 GDBusConnection *g_bus_get_sync (GBusType bus_type,
70 GCancellable *cancellable,
73 /* ---------------------------------------------------------------------------------------------------- */
75 void g_dbus_connection_new (GIOStream *stream,
77 GDBusConnectionFlags flags,
78 GDBusAuthObserver *observer,
79 GCancellable *cancellable,
80 GAsyncReadyCallback callback,
82 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
84 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
86 GDBusConnectionFlags flags,
87 GDBusAuthObserver *observer,
88 GCancellable *cancellable,
91 void g_dbus_connection_new_for_address (const gchar *address,
92 GDBusConnectionFlags flags,
93 GDBusAuthObserver *observer,
94 GCancellable *cancellable,
95 GAsyncReadyCallback callback,
97 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
99 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
100 GDBusConnectionFlags flags,
101 GDBusAuthObserver *observer,
102 GCancellable *cancellable,
105 /* ---------------------------------------------------------------------------------------------------- */
107 void g_dbus_connection_start_message_processing (GDBusConnection *connection);
108 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
109 void g_dbus_connection_close (GDBusConnection *connection);
110 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
111 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
112 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
113 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
114 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
115 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
116 gboolean exit_on_close);
117 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
119 /* ---------------------------------------------------------------------------------------------------- */
121 void g_dbus_connection_flush (GDBusConnection *connection,
122 GCancellable *cancellable,
123 GAsyncReadyCallback callback,
125 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
128 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
129 GCancellable *cancellable,
132 /* ---------------------------------------------------------------------------------------------------- */
134 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
135 GDBusMessage *message,
136 volatile guint32 *out_serial,
138 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
139 GDBusMessage *message,
141 volatile guint32 *out_serial,
142 GCancellable *cancellable,
143 GAsyncReadyCallback callback,
145 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
148 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
149 GDBusMessage *message,
151 volatile guint32 *out_serial,
152 GCancellable *cancellable,
155 /* ---------------------------------------------------------------------------------------------------- */
157 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
158 const gchar *destination_bus_name,
159 const gchar *object_path,
160 const gchar *interface_name,
161 const gchar *signal_name,
162 GVariant *parameters,
164 void g_dbus_connection_call (GDBusConnection *connection,
165 const gchar *bus_name,
166 const gchar *object_path,
167 const gchar *interface_name,
168 const gchar *method_name,
169 GVariant *parameters,
170 const GVariantType *reply_type,
171 GDBusCallFlags flags,
173 GCancellable *cancellable,
174 GAsyncReadyCallback callback,
176 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
179 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
180 const gchar *bus_name,
181 const gchar *object_path,
182 const gchar *interface_name,
183 const gchar *method_name,
184 GVariant *parameters,
185 const GVariantType *reply_type,
186 GDBusCallFlags flags,
188 GCancellable *cancellable,
191 /* ---------------------------------------------------------------------------------------------------- */
195 * GDBusInterfaceMethodCallFunc:
196 * @connection: A #GDBusConnection.
197 * @sender: The unique bus name of the remote caller.
198 * @object_path: The object path that the method was invoked on.
199 * @interface_name: The D-Bus interface name the method was invoked on.
200 * @method_name: The name of the method that was invoked.
201 * @parameters: A #GVariant tuple with parameters.
202 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
203 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
205 * The type of the @method_call function in #GDBusInterfaceVTable.
209 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
211 const gchar *object_path,
212 const gchar *interface_name,
213 const gchar *method_name,
214 GVariant *parameters,
215 GDBusMethodInvocation *invocation,
219 * GDBusInterfaceGetPropertyFunc:
220 * @connection: A #GDBusConnection.
221 * @sender: The unique bus name of the remote caller.
222 * @object_path: The object path that the method was invoked on.
223 * @interface_name: The D-Bus interface name for the property.
224 * @property_name: The name of the property to get the value of.
225 * @error: Return location for error.
226 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
228 * The type of the @get_property function in #GDBusInterfaceVTable.
230 * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
234 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
236 const gchar *object_path,
237 const gchar *interface_name,
238 const gchar *property_name,
243 * GDBusInterfaceSetPropertyFunc:
244 * @connection: A #GDBusConnection.
245 * @sender: The unique bus name of the remote caller.
246 * @object_path: The object path that the method was invoked on.
247 * @interface_name: The D-Bus interface name for the property.
248 * @property_name: The name of the property to get the value of.
249 * @value: The value to set the property to.
250 * @error: Return location for error.
251 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
253 * The type of the @set_property function in #GDBusInterfaceVTable.
255 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
259 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
261 const gchar *object_path,
262 const gchar *interface_name,
263 const gchar *property_name,
269 * GDBusInterfaceVTable:
270 * @method_call: Function for handling incoming method calls.
271 * @get_property: Function for getting a property.
272 * @set_property: Function for setting a property.
274 * Virtual table for handling properties and method calls for a D-Bus
277 * If you want to handle getting/setting D-Bus properties asynchronously, simply
278 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
279 * D-Bus interface using g_dbus_connection_register_object().
283 struct _GDBusInterfaceVTable
285 GDBusInterfaceMethodCallFunc method_call;
286 GDBusInterfaceGetPropertyFunc get_property;
287 GDBusInterfaceSetPropertyFunc set_property;
290 /* Padding for future expansion */
294 guint g_dbus_connection_register_object (GDBusConnection *connection,
295 const gchar *object_path,
296 const GDBusInterfaceInfo *interface_info,
297 const GDBusInterfaceVTable *vtable,
299 GDestroyNotify user_data_free_func,
301 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
302 guint registration_id);
304 /* ---------------------------------------------------------------------------------------------------- */
307 * GDBusSubtreeEnumerateFunc:
308 * @connection: A #GDBusConnection.
309 * @sender: The unique bus name of the remote caller.
310 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
311 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
313 * The type of the @enumerate function in #GDBusSubtreeVTable.
315 * Returns: A newly allocated array of strings for node names that are children of @object_path.
319 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
321 const gchar *object_path,
325 * GDBusSubtreeIntrospectFunc:
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 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
330 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
332 * The type of the @introspect function in #GDBusSubtreeVTable.
334 * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
335 * the interfaces implemented by @node.
339 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
341 const gchar *object_path,
346 * GDBusSubtreeDispatchFunc:
347 * @connection: A #GDBusConnection.
348 * @sender: The unique bus name of the remote caller.
349 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
350 * @interface_name: The D-Bus interface name that the method call or property access is for.
351 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
352 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
353 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
355 * The type of the @dispatch function in #GDBusSubtreeVTable.
357 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
361 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
363 const gchar *object_path,
364 const gchar *interface_name,
366 gpointer *out_user_data,
370 * GDBusSubtreeVTable:
371 * @enumerate: Function for enumerating child nodes.
372 * @introspect: Function for introspecting a child node.
373 * @dispatch: Function for dispatching a remote call on a child node.
375 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
379 struct _GDBusSubtreeVTable
381 GDBusSubtreeEnumerateFunc enumerate;
382 GDBusSubtreeIntrospectFunc introspect;
383 GDBusSubtreeDispatchFunc dispatch;
386 /* Padding for future expansion */
387 void (*_g_reserved1) (void);
388 void (*_g_reserved2) (void);
389 void (*_g_reserved3) (void);
390 void (*_g_reserved4) (void);
391 void (*_g_reserved5) (void);
392 void (*_g_reserved6) (void);
393 void (*_g_reserved7) (void);
394 void (*_g_reserved8) (void);
397 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
398 const gchar *object_path,
399 const GDBusSubtreeVTable *vtable,
400 GDBusSubtreeFlags flags,
402 GDestroyNotify user_data_free_func,
404 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
405 guint registration_id);
407 /* ---------------------------------------------------------------------------------------------------- */
410 * GDBusSignalCallback:
411 * @connection: A #GDBusConnection.
412 * @sender_name: The unique bus name of the sender of the signal.
413 * @object_path: The object path that the signal was emitted on.
414 * @interface_name: The name of the interface.
415 * @signal_name: The name of the signal.
416 * @parameters: A #GVariant tuple with parameters for the signal.
417 * @user_data: User data passed when subscribing to the signal.
419 * Signature for callback function used in g_dbus_connection_signal_subscribe().
423 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
424 const gchar *sender_name,
425 const gchar *object_path,
426 const gchar *interface_name,
427 const gchar *signal_name,
428 GVariant *parameters,
431 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
433 const gchar *interface_name,
435 const gchar *object_path,
437 GDBusSignalCallback callback,
439 GDestroyNotify user_data_free_func);
440 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
441 guint subscription_id);
443 /* ---------------------------------------------------------------------------------------------------- */
446 * GDBusMessageFilterFunction:
447 * @connection: A #GDBusConnection.
448 * @message: A #GDBusMessage.
449 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
450 * a message to be sent to the other peer.
451 * @user_data: User data passed when adding the filter.
453 * Signature for function used in g_dbus_connection_add_filter().
455 * Returns: %TRUE if the filter handled @message, %FALSE to let other
460 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
461 GDBusMessage *message,
465 guint g_dbus_connection_add_filter (GDBusConnection *connection,
466 GDBusMessageFilterFunction filter_function,
468 GDestroyNotify user_data_free_func);
470 void g_dbus_connection_remove_filter (GDBusConnection *connection,
473 /* ---------------------------------------------------------------------------------------------------- */
478 #endif /* __G_DBUS_CONNECTION_H__ */