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