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 #ifndef __G_DBUS_CONNECTION_H__
24 #define __G_DBUS_CONNECTION_H__
26 #include <gio/giotypes.h>
30 #define G_TYPE_DBUS_CONNECTION (g_dbus_connection_get_type ())
31 #define G_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
32 #define G_DBUS_CONNECTION_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
33 #define G_DBUS_CONNECTION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DBUS_CONNECTION, GDBusConnectionClass))
34 #define G_IS_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
35 #define G_IS_DBUS_CONNECTION_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DBUS_CONNECTION))
37 typedef struct _GDBusConnectionClass GDBusConnectionClass;
38 typedef struct _GDBusConnectionPrivate GDBusConnectionPrivate;
43 * The #GDBusConnection structure contains only private data and
44 * should only be accessed using the provided API.
48 struct _GDBusConnection
51 GObject parent_instance;
52 GDBusConnectionPrivate *priv;
56 * GDBusConnectionClass:
57 * @closed: Signal class handler for the #GDBusConnection::closed signal.
59 * Class structure for #GDBusConnection.
63 struct _GDBusConnectionClass
66 GObjectClass parent_class;
70 void (*closed) (GDBusConnection *connection,
71 gboolean remote_peer_vanished,
75 /* Padding for future expansion */
76 void (*_g_reserved1) (void);
77 void (*_g_reserved2) (void);
78 void (*_g_reserved3) (void);
79 void (*_g_reserved4) (void);
80 void (*_g_reserved5) (void);
81 void (*_g_reserved6) (void);
82 void (*_g_reserved7) (void);
83 void (*_g_reserved8) (void);
86 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
88 /* ---------------------------------------------------------------------------------------------------- */
90 void g_bus_get (GBusType bus_type,
91 GCancellable *cancellable,
92 GAsyncReadyCallback callback,
94 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
96 GDBusConnection *g_bus_get_sync (GBusType bus_type,
97 GCancellable *cancellable,
100 /* ---------------------------------------------------------------------------------------------------- */
102 void g_dbus_connection_new (GIOStream *stream,
104 GDBusConnectionFlags flags,
105 GDBusAuthObserver *auth_observer,
106 GCancellable *cancellable,
107 GAsyncReadyCallback callback,
109 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
111 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
113 GDBusConnectionFlags flags,
114 GDBusAuthObserver *auth_observer,
115 GCancellable *cancellable,
118 void g_dbus_connection_new_for_address (const gchar *address,
119 GDBusConnectionFlags flags,
120 GCancellable *cancellable,
121 GAsyncReadyCallback callback,
123 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
125 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
126 GDBusConnectionFlags flags,
127 GCancellable *cancellable,
130 /* ---------------------------------------------------------------------------------------------------- */
132 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
133 void g_dbus_connection_close (GDBusConnection *connection);
134 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
135 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
136 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
137 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
138 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
139 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
140 gboolean exit_on_close);
141 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
142 /* ---------------------------------------------------------------------------------------------------- */
144 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
145 GDBusMessage *message,
146 volatile guint32 *out_serial,
148 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
149 GDBusMessage *message,
151 volatile guint32 *out_serial,
152 GCancellable *cancellable,
153 GAsyncReadyCallback callback,
155 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
158 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
159 GDBusMessage *message,
161 volatile guint32 *out_serial,
162 GCancellable *cancellable,
165 /* ---------------------------------------------------------------------------------------------------- */
167 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
168 const gchar *destination_bus_name,
169 const gchar *object_path,
170 const gchar *interface_name,
171 const gchar *signal_name,
172 GVariant *parameters,
174 void g_dbus_connection_invoke_method (GDBusConnection *connection,
175 const gchar *bus_name,
176 const gchar *object_path,
177 const gchar *interface_name,
178 const gchar *method_name,
179 GVariant *parameters,
180 GDBusInvokeMethodFlags flags,
182 GCancellable *cancellable,
183 GAsyncReadyCallback callback,
185 GVariant *g_dbus_connection_invoke_method_finish (GDBusConnection *connection,
188 GVariant *g_dbus_connection_invoke_method_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 GDBusInvokeMethodFlags flags,
196 GCancellable *cancellable,
199 /* ---------------------------------------------------------------------------------------------------- */
203 * GDBusInterfaceMethodCallFunc:
204 * @connection: A #GDBusConnection.
205 * @sender: The unique bus name of the remote caller.
206 * @object_path: The object path that the method was invoked on.
207 * @interface_name: The D-Bus interface name the method was invoked on.
208 * @method_name: The name of the method that was invoked.
209 * @parameters: A #GVariant tuple with parameters.
210 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
211 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
213 * The type of the @method_call function in #GDBusInterfaceVTable.
217 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
219 const gchar *object_path,
220 const gchar *interface_name,
221 const gchar *method_name,
222 GVariant *parameters,
223 GDBusMethodInvocation *invocation,
227 * GDBusInterfaceGetPropertyFunc:
228 * @connection: A #GDBusConnection.
229 * @sender: The unique bus name of the remote caller.
230 * @object_path: The object path that the method was invoked on.
231 * @interface_name: The D-Bus interface name for the property.
232 * @property_name: The name of the property to get the value of.
233 * @error: Return location for error.
234 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
236 * The type of the @get_property function in #GDBusInterfaceVTable.
238 * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
242 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
244 const gchar *object_path,
245 const gchar *interface_name,
246 const gchar *property_name,
251 * GDBusInterfaceSetPropertyFunc:
252 * @connection: A #GDBusConnection.
253 * @sender: The unique bus name of the remote caller.
254 * @object_path: The object path that the method was invoked on.
255 * @interface_name: The D-Bus interface name for the property.
256 * @property_name: The name of the property to get the value of.
257 * @value: The value to set the property to.
258 * @error: Return location for error.
259 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
261 * The type of the @set_property function in #GDBusInterfaceVTable.
263 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
267 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
269 const gchar *object_path,
270 const gchar *interface_name,
271 const gchar *property_name,
277 * GDBusInterfaceVTable:
278 * @method_call: Function for handling incoming method calls.
279 * @get_property: Function for getting a property.
280 * @set_property: Function for setting a property.
282 * Virtual table for handling properties and method calls for a D-Bus
285 * If you want to handle getting/setting D-Bus properties asynchronously, simply
286 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
287 * D-Bus interface using g_dbus_connection_register_object().
291 struct _GDBusInterfaceVTable
293 GDBusInterfaceMethodCallFunc method_call;
294 GDBusInterfaceGetPropertyFunc get_property;
295 GDBusInterfaceSetPropertyFunc set_property;
298 /* Padding for future expansion */
299 void (*_g_reserved1) (void);
300 void (*_g_reserved2) (void);
301 void (*_g_reserved3) (void);
302 void (*_g_reserved4) (void);
303 void (*_g_reserved5) (void);
304 void (*_g_reserved6) (void);
305 void (*_g_reserved7) (void);
306 void (*_g_reserved8) (void);
309 guint g_dbus_connection_register_object (GDBusConnection *connection,
310 const gchar *object_path,
311 const gchar *interface_name,
312 const GDBusInterfaceInfo *introspection_data,
313 const GDBusInterfaceVTable *vtable,
315 GDestroyNotify user_data_free_func,
317 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
318 guint registration_id);
320 /* ---------------------------------------------------------------------------------------------------- */
323 * GDBusSubtreeEnumerateFunc:
324 * @connection: A #GDBusConnection.
325 * @sender: The unique bus name of the remote caller.
326 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
327 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
329 * The type of the @enumerate function in #GDBusSubtreeVTable.
331 * Returns: A newly allocated array of strings for node names that are children of @object_path.
335 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
337 const gchar *object_path,
341 * GDBusSubtreeIntrospectFunc:
342 * @connection: A #GDBusConnection.
343 * @sender: The unique bus name of the remote caller.
344 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
345 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
346 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
348 * The type of the @introspect function in #GDBusSubtreeVTable.
350 * Returns: A newly-allocated #GPtrArray with pointers to #GDBusInterfaceInfo describing
351 * the interfaces implemented by @node.
355 typedef GPtrArray *(*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
357 const gchar *object_path,
362 * GDBusSubtreeDispatchFunc:
363 * @connection: A #GDBusConnection.
364 * @sender: The unique bus name of the remote caller.
365 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
366 * @interface_name: The D-Bus interface name that the method call or property access is for.
367 * @node: A node that is a child of @object_path (relative to @object_path) or <quote>/</quote> for the root of the subtree.
368 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
369 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
371 * The type of the @dispatch function in #GDBusSubtreeVTable.
373 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
377 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
379 const gchar *object_path,
380 const gchar *interface_name,
382 gpointer *out_user_data,
386 * GDBusSubtreeVTable:
387 * @enumerate: Function for enumerating child nodes.
388 * @introspect: Function for introspecting a child node.
389 * @dispatch: Function for dispatching a remote call on a child node.
391 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
395 struct _GDBusSubtreeVTable
397 GDBusSubtreeEnumerateFunc enumerate;
398 GDBusSubtreeIntrospectFunc introspect;
399 GDBusSubtreeDispatchFunc dispatch;
402 /* Padding for future expansion */
403 void (*_g_reserved1) (void);
404 void (*_g_reserved2) (void);
405 void (*_g_reserved3) (void);
406 void (*_g_reserved4) (void);
407 void (*_g_reserved5) (void);
408 void (*_g_reserved6) (void);
409 void (*_g_reserved7) (void);
410 void (*_g_reserved8) (void);
413 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
414 const gchar *object_path,
415 const GDBusSubtreeVTable *vtable,
416 GDBusSubtreeFlags flags,
418 GDestroyNotify user_data_free_func,
420 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
421 guint registration_id);
423 /* ---------------------------------------------------------------------------------------------------- */
426 * GDBusSignalCallback:
427 * @connection: A #GDBusConnection.
428 * @sender_name: The unique bus name of the sender of the signal.
429 * @object_path: The object path that the signal was emitted on.
430 * @interface_name: The name of the signal.
431 * @signal_name: The name of the signal.
432 * @parameters: A #GVariant tuple with parameters for the signal.
433 * @user_data: User data passed when subscribing to the signal.
435 * Signature for callback function used in g_dbus_connection_signal_subscribe().
439 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
440 const gchar *sender_name,
441 const gchar *object_path,
442 const gchar *interface_name,
443 const gchar *signal_name,
444 GVariant *parameters,
447 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
449 const gchar *interface_name,
451 const gchar *object_path,
453 GDBusSignalCallback callback,
455 GDestroyNotify user_data_free_func);
456 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
457 guint subscription_id);
459 /* ---------------------------------------------------------------------------------------------------- */
462 * GDBusMessageFilterFunction:
463 * @connection: A #GDBusConnection.
464 * @message: A #GDBusMessage.
465 * @user_data: User data passed when adding the filter.
467 * Signature for function used in g_dbus_connection_add_filter().
469 * Returns: %TRUE if the filter handled @message, %FALSE to let other
474 typedef gboolean (*GDBusMessageFilterFunction) (GDBusConnection *connection,
475 GDBusMessage *message,
478 guint g_dbus_connection_add_filter (GDBusConnection *connection,
479 GDBusMessageFilterFunction filter_function,
481 GDestroyNotify user_data_free_func);
483 void g_dbus_connection_remove_filter (GDBusConnection *connection,
486 /* ---------------------------------------------------------------------------------------------------- */
491 #endif /* __G_DBUS_CONNECTION_H__ */