?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
docs: Fix GApplicationCommandLine typo
[glib.git] / gio / gdbusconnection.h
blobac131dc2dcabadff00070300651224a79f76dac7
1 /* GDBus - GLib D-Bus Library
2 *
3 * Copyright (C) 2008-2010 Red Hat, Inc.
4 *
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.
9 *
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.
14 *
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.
19 *
20 * Author: David Zeuthen <davidz@redhat.com>
21 */
22
23 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
24 #error "Only <gio/gio.h> can be included directly."
25 #endif
26
27 #ifndef __G_DBUS_CONNECTION_H__
28 #define __G_DBUS_CONNECTION_H__
29
30 #include <gio/giotypes.h>
31
32 G_BEGIN_DECLS
33
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))
37
38 GType g_dbus_connection_get_type (void) G_GNUC_CONST;
39
40 /* ---------------------------------------------------------------------------------------------------- */
41
42 void g_bus_get (GBusType bus_type,
43 GCancellable *cancellable,
44 GAsyncReadyCallback callback,
45 gpointer user_data);
46 GDBusConnection *g_bus_get_finish (GAsyncResult *res,
47 GError **error);
48 GDBusConnection *g_bus_get_sync (GBusType bus_type,
49 GCancellable *cancellable,
50 GError **error);
51
52 /* ---------------------------------------------------------------------------------------------------- */
53
54 void g_dbus_connection_new (GIOStream *stream,
55 const gchar *guid,
56 GDBusConnectionFlags flags,
57 GDBusAuthObserver *observer,
58 GCancellable *cancellable,
59 GAsyncReadyCallback callback,
60 gpointer user_data);
61 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
62 GError **error);
63 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
64 const gchar *guid,
65 GDBusConnectionFlags flags,
66 GDBusAuthObserver *observer,
67 GCancellable *cancellable,
68 GError **error);
69
70 void g_dbus_connection_new_for_address (const gchar *address,
71 GDBusConnectionFlags flags,
72 GDBusAuthObserver *observer,
73 GCancellable *cancellable,
74 GAsyncReadyCallback callback,
75 gpointer user_data);
76 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
77 GError **error);
78 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
79 GDBusConnectionFlags flags,
80 GDBusAuthObserver *observer,
81 GCancellable *cancellable,
82 GError **error);
83
84 /* ---------------------------------------------------------------------------------------------------- */
85
86 void g_dbus_connection_start_message_processing (GDBusConnection *connection);
87 gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
88 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
89 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
90 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
91 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
92 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
93 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
94 gboolean exit_on_close);
95 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
96
97 /* ---------------------------------------------------------------------------------------------------- */
98
99 void g_dbus_connection_close (GDBusConnection *connection,
100 GCancellable *cancellable,
101 GAsyncReadyCallback callback,
102 gpointer user_data);
103 gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
104 GAsyncResult *res,
105 GError **error);
106 gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
107 GCancellable *cancellable,
108 GError **error);
109
110 /* ---------------------------------------------------------------------------------------------------- */
111
112 void g_dbus_connection_flush (GDBusConnection *connection,
113 GCancellable *cancellable,
114 GAsyncReadyCallback callback,
115 gpointer user_data);
116 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
117 GAsyncResult *res,
118 GError **error);
119 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
120 GCancellable *cancellable,
121 GError **error);
122
123 /* ---------------------------------------------------------------------------------------------------- */
124
125 gboolean g_dbus_connection_send_message (GDBusConnection *connection,
126 GDBusMessage *message,
127 GDBusSendMessageFlags flags,
128 volatile guint32 *out_serial,
129 GError **error);
130 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
131 GDBusMessage *message,
132 GDBusSendMessageFlags flags,
133 gint timeout_msec,
134 volatile guint32 *out_serial,
135 GCancellable *cancellable,
136 GAsyncReadyCallback callback,
137 gpointer user_data);
138 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
139 GAsyncResult *res,
140 GError **error);
141 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
142 GDBusMessage *message,
143 GDBusSendMessageFlags flags,
144 gint timeout_msec,
145 volatile guint32 *out_serial,
146 GCancellable *cancellable,
147 GError **error);
148
149 /* ---------------------------------------------------------------------------------------------------- */
150
151 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
152 const gchar *destination_bus_name,
153 const gchar *object_path,
154 const gchar *interface_name,
155 const gchar *signal_name,
156 GVariant *parameters,
157 GError **error);
158 void g_dbus_connection_call (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,
166 gint timeout_msec,
167 GCancellable *cancellable,
168 GAsyncReadyCallback callback,
169 gpointer user_data);
170 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
171 GAsyncResult *res,
172 GError **error);
173 GVariant *g_dbus_connection_call_sync (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,
181 gint timeout_msec,
182 GCancellable *cancellable,
183 GError **error);
184 void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection,
185 const gchar *bus_name,
186 const gchar *object_path,
187 const gchar *interface_name,
188 const gchar *method_name,
189 GVariant *parameters,
190 const GVariantType *reply_type,
191 GDBusCallFlags flags,
192 gint timeout_msec,
193 GUnixFDList *fd_list,
194 GCancellable *cancellable,
195 GAsyncReadyCallback callback,
196 gpointer user_data);
197 GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
198 GUnixFDList **out_fd_list,
199 GAsyncResult *res,
200 GError **error);
201 GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection,
202 const gchar *bus_name,
203 const gchar *object_path,
204 const gchar *interface_name,
205 const gchar *method_name,
206 GVariant *parameters,
207 const GVariantType *reply_type,
208 GDBusCallFlags flags,
209 gint timeout_msec,
210 GUnixFDList *fd_list,
211 GUnixFDList **out_fd_list,
212 GCancellable *cancellable,
213 GError **error);
214
215 /* ---------------------------------------------------------------------------------------------------- */
216
217
218 /**
219 * GDBusInterfaceMethodCallFunc:
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 the method was invoked on.
224 * @method_name: The name of the method that was invoked.
225 * @parameters: A #GVariant tuple with parameters.
226 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
227 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
228 *
229 * The type of the @method_call function in #GDBusInterfaceVTable.
230 *
231 * Since: 2.26
232 */
233 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
234 const gchar *sender,
235 const gchar *object_path,
236 const gchar *interface_name,
237 const gchar *method_name,
238 GVariant *parameters,
239 GDBusMethodInvocation *invocation,
240 gpointer user_data);
241
242 /**
243 * GDBusInterfaceGetPropertyFunc:
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 * @error: Return location for error.
250 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
251 *
252 * The type of the @get_property function in #GDBusInterfaceVTable.
253 *
254 * Returns: A #GVariant with the value for @property_name or %NULL if
255 * @error is set. If the returned #GVariant is floating, it is
256 * consumed - otherwise its reference count is decreased by one.
257 *
258 * Since: 2.26
259 */
260 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
261 const gchar *sender,
262 const gchar *object_path,
263 const gchar *interface_name,
264 const gchar *property_name,
265 GError **error,
266 gpointer user_data);
267
268 /**
269 * GDBusInterfaceSetPropertyFunc:
270 * @connection: A #GDBusConnection.
271 * @sender: The unique bus name of the remote caller.
272 * @object_path: The object path that the method was invoked on.
273 * @interface_name: The D-Bus interface name for the property.
274 * @property_name: The name of the property to get the value of.
275 * @value: The value to set the property to.
276 * @error: Return location for error.
277 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
278 *
279 * The type of the @set_property function in #GDBusInterfaceVTable.
280 *
281 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
282 *
283 * Since: 2.26
284 */
285 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
286 const gchar *sender,
287 const gchar *object_path,
288 const gchar *interface_name,
289 const gchar *property_name,
290 GVariant *value,
291 GError **error,
292 gpointer user_data);
293
294 /**
295 * GDBusInterfaceVTable:
296 * @method_call: Function for handling incoming method calls.
297 * @get_property: Function for getting a property.
298 * @set_property: Function for setting a property.
299 *
300 * Virtual table for handling properties and method calls for a D-Bus
301 * interface.
302 *
303 * If you want to handle getting/setting D-Bus properties asynchronously, simply
304 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
305 * D-Bus interface using g_dbus_connection_register_object().
306 *
307 * Since: 2.26
308 */
309 struct _GDBusInterfaceVTable
310 {
311 GDBusInterfaceMethodCallFunc method_call;
312 GDBusInterfaceGetPropertyFunc get_property;
313 GDBusInterfaceSetPropertyFunc set_property;
314
315 /*< private >*/
316 /* Padding for future expansion - also remember to update
317 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when
318 * changing this.
319 */
320 gpointer padding[8];
321 };
322
323 guint g_dbus_connection_register_object (GDBusConnection *connection,
324 const gchar *object_path,
325 GDBusInterfaceInfo *interface_info,
326 const GDBusInterfaceVTable *vtable,
327 gpointer user_data,
328 GDestroyNotify user_data_free_func,
329 GError **error);
330 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
331 guint registration_id);
332
333 /* ---------------------------------------------------------------------------------------------------- */
334
335 /**
336 * GDBusSubtreeEnumerateFunc:
337 * @connection: A #GDBusConnection.
338 * @sender: The unique bus name of the remote caller.
339 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
340 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
341 *
342 * The type of the @enumerate function in #GDBusSubtreeVTable.
343 *
344 * This function is called when generating introspection data and also
345 * when preparing to dispatch incoming messages in the event that the
346 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
347 * specified (ie: to verify that the object path is valid).
348 *
349 * Hierarchies are not supported; the items that you return should not
350 * contain the '/' character.
351 *
352 * The return value will be freed with g_strfreev().
353 *
354 * Returns: A newly allocated array of strings for node names that are children of @object_path.
355 *
356 * Since: 2.26
357 */
358 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
359 const gchar *sender,
360 const gchar *object_path,
361 gpointer user_data);
362
363 /**
364 * GDBusSubtreeIntrospectFunc:
365 * @connection: A #GDBusConnection.
366 * @sender: The unique bus name of the remote caller.
367 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
368 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
369 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
370 *
371 * The type of the @introspect function in #GDBusSubtreeVTable.
372 *
373 * Subtrees are flat. @node, if non-%NULL, is always exactly one
374 * segment of the object path (ie: it never contains a slash).
375 *
376 * This function should return %NULL to indicate that there is no object
377 * at this node.
378 *
379 * If this function returns non-%NULL, the return value is expected to
380 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
381 * structures describing the interfaces implemented by @node. This
382 * array will have g_dbus_interface_info_unref() called on each item
383 * before being freed with g_free().
384 *
385 * The difference between returning %NULL and an array containing zero
386 * items is that the standard DBus interfaces will returned to the
387 * remote introspector in the empty array case, but not in the %NULL
388 * case.
389 *
390 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
391 *
392 * Since: 2.26
393 */
394 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
395 const gchar *sender,
396 const gchar *object_path,
397 const gchar *node,
398 gpointer user_data);
399
400 /**
401 * GDBusSubtreeDispatchFunc:
402 * @connection: A #GDBusConnection.
403 * @sender: The unique bus name of the remote caller.
404 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
405 * @interface_name: The D-Bus interface name that the method call or property access is for.
406 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
407 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
408 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
409 *
410 * The type of the @dispatch function in #GDBusSubtreeVTable.
411 *
412 * Subtrees are flat. @node, if non-%NULL, is always exactly one
413 * segment of the object path (ie: it never contains a slash).
414 *
415 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
416 *
417 * Since: 2.26
418 */
419 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
420 const gchar *sender,
421 const gchar *object_path,
422 const gchar *interface_name,
423 const gchar *node,
424 gpointer *out_user_data,
425 gpointer user_data);
426
427 /**
428 * GDBusSubtreeVTable:
429 * @enumerate: Function for enumerating child nodes.
430 * @introspect: Function for introspecting a child node.
431 * @dispatch: Function for dispatching a remote call on a child node.
432 *
433 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
434 *
435 * Since: 2.26
436 */
437 struct _GDBusSubtreeVTable
438 {
439 GDBusSubtreeEnumerateFunc enumerate;
440 GDBusSubtreeIntrospectFunc introspect;
441 GDBusSubtreeDispatchFunc dispatch;
442
443 /*< private >*/
444 /* Padding for future expansion - also remember to update
445 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when
446 * changing this.
447 */
448 gpointer padding[8];
449 };
450
451 guint g_dbus_connection_register_subtree (GDBusConnection *connection,
452 const gchar *object_path,
453 const GDBusSubtreeVTable *vtable,
454 GDBusSubtreeFlags flags,
455 gpointer user_data,
456 GDestroyNotify user_data_free_func,
457 GError **error);
458 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
459 guint registration_id);
460
461 /* ---------------------------------------------------------------------------------------------------- */
462
463 /**
464 * GDBusSignalCallback:
465 * @connection: A #GDBusConnection.
466 * @sender_name: The unique bus name of the sender of the signal.
467 * @object_path: The object path that the signal was emitted on.
468 * @interface_name: The name of the interface.
469 * @signal_name: The name of the signal.
470 * @parameters: A #GVariant tuple with parameters for the signal.
471 * @user_data: User data passed when subscribing to the signal.
472 *
473 * Signature for callback function used in g_dbus_connection_signal_subscribe().
474 *
475 * Since: 2.26
476 */
477 typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
478 const gchar *sender_name,
479 const gchar *object_path,
480 const gchar *interface_name,
481 const gchar *signal_name,
482 GVariant *parameters,
483 gpointer user_data);
484
485 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
486 const gchar *sender,
487 const gchar *interface_name,
488 const gchar *member,
489 const gchar *object_path,
490 const gchar *arg0,
491 GDBusSignalFlags flags,
492 GDBusSignalCallback callback,
493 gpointer user_data,
494 GDestroyNotify user_data_free_func);
495 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
496 guint subscription_id);
497
498 /* ---------------------------------------------------------------------------------------------------- */
499
500 /**
501 * GDBusMessageFilterFunction:
502 * @connection: (transfer none): A #GDBusConnection.
503 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
504 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
505 * a message to be sent to the other peer.
506 * @user_data: User data passed when adding the filter.
507 *
508 * Signature for function used in g_dbus_connection_add_filter().
509 *
510 * A filter function is passed a #GDBusMessage and expected to return
511 * a #GDBusMessage too. Passive filter functions that don't modify the
512 * message can simply return the @message object:
513 * |[
514 * static GDBusMessage *
515 * passive_filter (GDBusConnection *connection
516 * GDBusMessage *message,
517 * gboolean incoming,
518 * gpointer user_data)
519 * {
520 * /<!-- -->* inspect @message *<!-- -->/
521 * return message;
522 * }
523 * ]|
524 * Filter functions that wants to drop a message can simply return %NULL:
525 * |[
526 * static GDBusMessage *
527 * drop_filter (GDBusConnection *connection
528 * GDBusMessage *message,
529 * gboolean incoming,
530 * gpointer user_data)
531 * {
532 * if (should_drop_message)
533 * {
534 * g_object_unref (message);
535 * message = NULL;
536 * }
537 * return message;
538 * }
539 * ]|
540 * Finally, a filter function may modify a message by copying it:
541 * |[
542 * static GDBusMessage *
543 * modifying_filter (GDBusConnection *connection
544 * GDBusMessage *message,
545 * gboolean incoming,
546 * gpointer user_data)
547 * {
548 * GDBusMessage *copy;
549 * GError *error;
550 *
551 * error = NULL;
552 * copy = g_dbus_message_copy (message, &error);
553 * /<!-- -->* handle @error being is set *<!-- -->/
554 * g_object_unref (message);
555 *
556 * /<!-- -->* modify @copy *<!-- -->/
557 *
558 * return copy;
559 * }
560 * ]|
561 * If the returned #GDBusMessage is different from @message and cannot
562 * be sent on @connection (it could use features, such as file
563 * descriptors, not compatible with @connection), then a warning is
564 * logged to <emphasis>standard error</emphasis>. Applications can
565 * check this ahead of time using g_dbus_message_to_blob() passing a
566 * #GDBusCapabilityFlags value obtained from @connection.
567 *
568 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
569 * g_object_unref() or %NULL to drop the message. Passive filter
570 * functions can simply return the passed @message object.
571 *
572 * Since: 2.26
573 */
574 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
575 GDBusMessage *message,
576 gboolean incoming,
577 gpointer user_data);
578
579 guint g_dbus_connection_add_filter (GDBusConnection *connection,
580 GDBusMessageFilterFunction filter_function,
581 gpointer user_data,
582 GDestroyNotify user_data_free_func);
583
584 void g_dbus_connection_remove_filter (GDBusConnection *connection,
585 guint filter_id);
586
587 /* ---------------------------------------------------------------------------------------------------- */
588
589
590 G_END_DECLS
591
592 #endif /* __G_DBUS_CONNECTION_H__ */
glib mirror