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 */
83 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
85 /* ---------------------------------------------------------------------------------------------------- */
87 void g_bus_get (GBusType bus_type,
88 GCancellable *cancellable,
89 GAsyncReadyCallback callback,
91 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
93 GDBusConnection *g_bus_get_sync (GBusType bus_type,
94 GCancellable *cancellable,
97 /* ---------------------------------------------------------------------------------------------------- */
99 void g_dbus_connection_new (GIOStream *stream,
101 GDBusConnectionFlags flags,
102 GDBusAuthObserver *observer,
103 GCancellable *cancellable,
104 GAsyncReadyCallback callback,
106 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
108 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
110 GDBusConnectionFlags flags,
111 GDBusAuthObserver *observer,
112 GCancellable *cancellable,
115 void g_dbus_connection_new_for_address (const gchar *address,
116 GDBusConnectionFlags flags,
117 GDBusAuthObserver *observer,
118 GCancellable *cancellable,
119 GAsyncReadyCallback callback,
121 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
123 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
124 GDBusConnectionFlags flags,
125 GDBusAuthObserver *observer,
126 GCancellable *cancellable,
129 /* ---------------------------------------------------------------------------------------------------- */
131 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
132 void g_dbus_connection_close (GDBusConnection *connection);
133 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
134 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
135 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
136 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
137 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
138 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
139 gboolean exit_on_close);
140 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
141 /* ---------------------------------------------------------------------------------------------------- */
143 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
144 GDBusMessage *message,
145 volatile guint32 *out_serial,
147 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
148 GDBusMessage *message,
150 volatile guint32 *out_serial,
151 GCancellable *cancellable,
152 GAsyncReadyCallback callback,
154 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
157 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
158 GDBusMessage *message,
160 volatile guint32 *out_serial,
161 GCancellable *cancellable,
164 /* ---------------------------------------------------------------------------------------------------- */
166 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
167 const gchar *destination_bus_name,
168 const gchar *object_path,
169 const gchar *interface_name,
170 const gchar *signal_name,
171 GVariant *parameters,
173 void g_dbus_connection_call (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,
183 GAsyncReadyCallback callback,
185 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
188 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
189 const gchar *bus_name,
190 const gchar *object_path,
191 const gchar *interface_name,
192 const gchar *method_name,
193 GVariant *parameters,
194 const GVariantType *reply_type,
195 GDBusCallFlags flags,
197 GCancellable *cancellable,
200 /* ---------------------------------------------------------------------------------------------------- */
204 * GDBusInterfaceMethodCallFunc:
205 * @connection: A #GDBusConnection.
206 * @sender: The unique bus name of the remote caller.
207 * @object_path: The object path that the method was invoked on.
208 * @interface_name: The D-Bus interface name the method was invoked on.
209 * @method_name: The name of the method that was invoked.
210 * @parameters: A #GVariant tuple with parameters.
211 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
212 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
214 * The type of the @method_call function in #GDBusInterfaceVTable.
218 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
220 const gchar *object_path,
221 const gchar *interface_name,
222 const gchar *method_name,
223 GVariant *parameters,
224 GDBusMethodInvocation *invocation,
228 * GDBusInterfaceGetPropertyFunc:
229 * @connection: A #GDBusConnection.
230 * @sender: The unique bus name of the remote caller.
231 * @object_path: The object path that the method was invoked on.
232 * @interface_name: The D-Bus interface name for the property.
233 * @property_name: The name of the property to get the value of.
234 * @error: Return location for error.
235 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
237 * The type of the @get_property function in #GDBusInterfaceVTable.
239 * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
243 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
245 const gchar *object_path,
246 const gchar *interface_name,
247 const gchar *property_name,
252 * GDBusInterfaceSetPropertyFunc:
253 * @connection: A #GDBusConnection.
254 * @sender: The unique bus name of the remote caller.
255 * @object_path: The object path that the method was invoked on.
256 * @interface_name: The D-Bus interface name for the property.
257 * @property_name: The name of the property to get the value of.
258 * @value: The value to set the property to.
259 * @error: Return location for error.
260 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
262 * The type of the @set_property function in #GDBusInterfaceVTable.
264 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
268 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
270 const gchar *object_path,
271 const gchar *interface_name,
272 const gchar *property_name,
278 * GDBusInterfaceVTable:
279 * @method_call: Function for handling incoming method calls.
280 * @get_property: Function for getting a property.
281 * @set_property: Function for setting a property.
283 * Virtual table for handling properties and method calls for a D-Bus
286 * If you want to handle getting/setting D-Bus properties asynchronously, simply
287 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
288 * D-Bus interface using g_dbus_connection_register_object().
292 struct _GDBusInterfaceVTable
294 GDBusInterfaceMethodCallFunc method_call;
295 GDBusInterfaceGetPropertyFunc get_property;
296 GDBusInterfaceSetPropertyFunc set_property;
299 /* Padding for future expansion */
303 guint g_dbus_connection_register_object (GDBusConnection *connection,
304 const gchar *object_path,
305 const GDBusInterfaceInfo *introspection_data,
306 const GDBusInterfaceVTable *vtable,
308 GDestroyNotify user_data_free_func,
310 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
311 guint registration_id);
313 /* ---------------------------------------------------------------------------------------------------- */
316 * GDBusSubtreeEnumerateFunc:
317 * @connection: A #GDBusConnection.
318 * @sender: The unique bus name of the remote caller.
319 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
320 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
322 * The type of the @enumerate function in #GDBusSubtreeVTable.
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 <quote>/</quote> 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 * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
344 * the interfaces implemented by @node.
348 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
350 const gchar *object_path,
355 * GDBusSubtreeDispatchFunc:
356 * @connection: A #GDBusConnection.
357 * @sender: The unique bus name of the remote caller.
358 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
359 * @interface_name: The D-Bus interface name that the method call or property access is for.
360 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
361 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
362 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
364 * The type of the @dispatch function in #GDBusSubtreeVTable.
366 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
370 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
372 const gchar *object_path,
373 const gchar *interface_name,
375 gpointer *out_user_data,
379 * GDBusSubtreeVTable:
380 * @enumerate: Function for enumerating child nodes.
381 * @introspect: Function for introspecting a child node.
382 * @dispatch: Function for dispatching a remote call on a child node.
384 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
388 struct _GDBusSubtreeVTable
390 GDBusSubtreeEnumerateFunc enumerate;
391 GDBusSubtreeIntrospectFunc introspect;
392 GDBusSubtreeDispatchFunc dispatch;
395 /* Padding for future expansion */
396 void (*_g_reserved1) (void);
397 void (*_g_reserved2) (void);
398 void (*_g_reserved3) (void);
399 void (*_g_reserved4) (void);
400 void (*_g_reserved5) (void);
401 void (*_g_reserved6) (void);
402 void (*_g_reserved7) (void);
403 void (*_g_reserved8) (void);
406 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
407 const gchar *object_path,
408 const GDBusSubtreeVTable *vtable,
409 GDBusSubtreeFlags flags,
411 GDestroyNotify user_data_free_func,
413 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
414 guint registration_id);
416 /* ---------------------------------------------------------------------------------------------------- */
419 * GDBusSignalCallback:
420 * @connection: A #GDBusConnection.
421 * @sender_name: The unique bus name of the sender of the signal.
422 * @object_path: The object path that the signal was emitted on.
423 * @interface_name: The name of the interface.
424 * @signal_name: The name of the signal.
425 * @parameters: A #GVariant tuple with parameters for the signal.
426 * @user_data: User data passed when subscribing to the signal.
428 * Signature for callback function used in g_dbus_connection_signal_subscribe().
432 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
433 const gchar *sender_name,
434 const gchar *object_path,
435 const gchar *interface_name,
436 const gchar *signal_name,
437 GVariant *parameters,
440 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
442 const gchar *interface_name,
444 const gchar *object_path,
446 GDBusSignalCallback callback,
448 GDestroyNotify user_data_free_func);
449 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
450 guint subscription_id);
452 /* ---------------------------------------------------------------------------------------------------- */
455 * GDBusMessageFilterFunction:
456 * @connection: A #GDBusConnection.
457 * @message: A #GDBusMessage.
458 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
459 * a message to be sent to the other peer.
460 * @user_data: User data passed when adding the filter.
462 * Signature for function used in g_dbus_connection_add_filter().
464 * Returns: %TRUE if the filter handled @message, %FALSE to let other
469 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
470 GDBusMessage *message,
474 guint g_dbus_connection_add_filter (GDBusConnection *connection,
475 GDBusMessageFilterFunction filter_function,
477 GDestroyNotify user_data_free_func);
479 void g_dbus_connection_remove_filter (GDBusConnection *connection,
482 /* ---------------------------------------------------------------------------------------------------- */
487 #endif /* __G_DBUS_CONNECTION_H__ */