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.1 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, see <http://www.gnu.org/licenses/>. 17 * 18 * Author: David Zeuthen <davidz@redhat.com> 19 */ 20 21 #ifndef __G_DBUS_CONNECTION_H__ 22 #define __G_DBUS_CONNECTION_H__ 23 24 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION) 25 #error "Only <gio/gio.h> can be included directly." 26 #endif 27 28 #include <gio/giotypes.h> 29 30 G_BEGIN_DECLS 31 32 #define G_TYPE_DBUS_CONNECTION (g_dbus_connection_get_type ()) 33 #define G_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection)) 34 #define G_IS_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION)) 35 36 GLIB_AVAILABLE_IN_ALL 37 GType g_dbus_connection_get_type (void) G_GNUC_CONST; 38 39 /* ---------------------------------------------------------------------------------------------------- */ 40 41 GLIB_AVAILABLE_IN_ALL 42 void g_bus_get (GBusType bus_type, 43 GCancellable *cancellable, 44 GAsyncReadyCallback callback, 45 gpointer user_data); 46 GLIB_AVAILABLE_IN_ALL 47 GDBusConnection *g_bus_get_finish (GAsyncResult *res, 48 GError **error); 49 GLIB_AVAILABLE_IN_ALL 50 GDBusConnection *g_bus_get_sync (GBusType bus_type, 51 GCancellable *cancellable, 52 GError **error); 53 54 /* ---------------------------------------------------------------------------------------------------- */ 55 56 GLIB_AVAILABLE_IN_ALL 57 void g_dbus_connection_new (GIOStream *stream, 58 const gchar *guid, 59 GDBusConnectionFlags flags, 60 GDBusAuthObserver *observer, 61 GCancellable *cancellable, 62 GAsyncReadyCallback callback, 63 gpointer user_data); 64 GLIB_AVAILABLE_IN_ALL 65 GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res, 66 GError **error); 67 GLIB_AVAILABLE_IN_ALL 68 GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream, 69 const gchar *guid, 70 GDBusConnectionFlags flags, 71 GDBusAuthObserver *observer, 72 GCancellable *cancellable, 73 GError **error); 74 75 GLIB_AVAILABLE_IN_ALL 76 void g_dbus_connection_new_for_address (const gchar *address, 77 GDBusConnectionFlags flags, 78 GDBusAuthObserver *observer, 79 GCancellable *cancellable, 80 GAsyncReadyCallback callback, 81 gpointer user_data); 82 GLIB_AVAILABLE_IN_ALL 83 GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res, 84 GError **error); 85 GLIB_AVAILABLE_IN_ALL 86 GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address, 87 GDBusConnectionFlags flags, 88 GDBusAuthObserver *observer, 89 GCancellable *cancellable, 90 GError **error); 91 92 /* ---------------------------------------------------------------------------------------------------- */ 93 94 GLIB_AVAILABLE_IN_ALL 95 void g_dbus_connection_start_message_processing (GDBusConnection *connection); 96 GLIB_AVAILABLE_IN_ALL 97 gboolean g_dbus_connection_is_closed (GDBusConnection *connection); 98 GLIB_AVAILABLE_IN_ALL 99 GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection); 100 GLIB_AVAILABLE_IN_ALL 101 const gchar *g_dbus_connection_get_guid (GDBusConnection *connection); 102 GLIB_AVAILABLE_IN_ALL 103 const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection); 104 GLIB_AVAILABLE_IN_ALL 105 GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection); 106 107 GLIB_AVAILABLE_IN_2_34 108 guint32 g_dbus_connection_get_last_serial (GDBusConnection *connection); 109 110 GLIB_AVAILABLE_IN_ALL 111 gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection); 112 GLIB_AVAILABLE_IN_ALL 113 void g_dbus_connection_set_exit_on_close (GDBusConnection *connection, 114 gboolean exit_on_close); 115 GLIB_AVAILABLE_IN_ALL 116 GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection); 117 GLIB_AVAILABLE_IN_2_60 118 GDBusConnectionFlags g_dbus_connection_get_flags (GDBusConnection *connection); 119 120 /* ---------------------------------------------------------------------------------------------------- */ 121 122 GLIB_AVAILABLE_IN_ALL 123 void g_dbus_connection_close (GDBusConnection *connection, 124 GCancellable *cancellable, 125 GAsyncReadyCallback callback, 126 gpointer user_data); 127 GLIB_AVAILABLE_IN_ALL 128 gboolean g_dbus_connection_close_finish (GDBusConnection *connection, 129 GAsyncResult *res, 130 GError **error); 131 GLIB_AVAILABLE_IN_ALL 132 gboolean g_dbus_connection_close_sync (GDBusConnection *connection, 133 GCancellable *cancellable, 134 GError **error); 135 136 /* ---------------------------------------------------------------------------------------------------- */ 137 138 GLIB_AVAILABLE_IN_ALL 139 void g_dbus_connection_flush (GDBusConnection *connection, 140 GCancellable *cancellable, 141 GAsyncReadyCallback callback, 142 gpointer user_data); 143 GLIB_AVAILABLE_IN_ALL 144 gboolean g_dbus_connection_flush_finish (GDBusConnection *connection, 145 GAsyncResult *res, 146 GError **error); 147 GLIB_AVAILABLE_IN_ALL 148 gboolean g_dbus_connection_flush_sync (GDBusConnection *connection, 149 GCancellable *cancellable, 150 GError **error); 151 152 /* ---------------------------------------------------------------------------------------------------- */ 153 154 GLIB_AVAILABLE_IN_ALL 155 gboolean g_dbus_connection_send_message (GDBusConnection *connection, 156 GDBusMessage *message, 157 GDBusSendMessageFlags flags, 158 volatile guint32 *out_serial, 159 GError **error); 160 GLIB_AVAILABLE_IN_ALL 161 void g_dbus_connection_send_message_with_reply (GDBusConnection *connection, 162 GDBusMessage *message, 163 GDBusSendMessageFlags flags, 164 gint timeout_msec, 165 volatile guint32 *out_serial, 166 GCancellable *cancellable, 167 GAsyncReadyCallback callback, 168 gpointer user_data); 169 GLIB_AVAILABLE_IN_ALL 170 GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection, 171 GAsyncResult *res, 172 GError **error); 173 GLIB_AVAILABLE_IN_ALL 174 GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection, 175 GDBusMessage *message, 176 GDBusSendMessageFlags flags, 177 gint timeout_msec, 178 volatile guint32 *out_serial, 179 GCancellable *cancellable, 180 GError **error); 181 182 /* ---------------------------------------------------------------------------------------------------- */ 183 184 GLIB_AVAILABLE_IN_ALL 185 gboolean g_dbus_connection_emit_signal (GDBusConnection *connection, 186 const gchar *destination_bus_name, 187 const gchar *object_path, 188 const gchar *interface_name, 189 const gchar *signal_name, 190 GVariant *parameters, 191 GError **error); 192 GLIB_AVAILABLE_IN_ALL 193 void g_dbus_connection_call (GDBusConnection *connection, 194 const gchar *bus_name, 195 const gchar *object_path, 196 const gchar *interface_name, 197 const gchar *method_name, 198 GVariant *parameters, 199 const GVariantType *reply_type, 200 GDBusCallFlags flags, 201 gint timeout_msec, 202 GCancellable *cancellable, 203 GAsyncReadyCallback callback, 204 gpointer user_data); 205 GLIB_AVAILABLE_IN_ALL 206 GVariant *g_dbus_connection_call_finish (GDBusConnection *connection, 207 GAsyncResult *res, 208 GError **error); 209 GLIB_AVAILABLE_IN_ALL 210 GVariant *g_dbus_connection_call_sync (GDBusConnection *connection, 211 const gchar *bus_name, 212 const gchar *object_path, 213 const gchar *interface_name, 214 const gchar *method_name, 215 GVariant *parameters, 216 const GVariantType *reply_type, 217 GDBusCallFlags flags, 218 gint timeout_msec, 219 GCancellable *cancellable, 220 GError **error); 221 GLIB_AVAILABLE_IN_2_30 222 void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection, 223 const gchar *bus_name, 224 const gchar *object_path, 225 const gchar *interface_name, 226 const gchar *method_name, 227 GVariant *parameters, 228 const GVariantType *reply_type, 229 GDBusCallFlags flags, 230 gint timeout_msec, 231 GUnixFDList *fd_list, 232 GCancellable *cancellable, 233 GAsyncReadyCallback callback, 234 gpointer user_data); 235 GLIB_AVAILABLE_IN_2_30 236 GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection, 237 GUnixFDList **out_fd_list, 238 GAsyncResult *res, 239 GError **error); 240 GLIB_AVAILABLE_IN_2_30 241 GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection, 242 const gchar *bus_name, 243 const gchar *object_path, 244 const gchar *interface_name, 245 const gchar *method_name, 246 GVariant *parameters, 247 const GVariantType *reply_type, 248 GDBusCallFlags flags, 249 gint timeout_msec, 250 GUnixFDList *fd_list, 251 GUnixFDList **out_fd_list, 252 GCancellable *cancellable, 253 GError **error); 254 255 /* ---------------------------------------------------------------------------------------------------- */ 256 257 258 /** 259 * GDBusInterfaceMethodCallFunc: 260 * @connection: A #GDBusConnection. 261 * @sender: The unique bus name of the remote caller. 262 * @object_path: The object path that the method was invoked on. 263 * @interface_name: The D-Bus interface name the method was invoked on. 264 * @method_name: The name of the method that was invoked. 265 * @parameters: A #GVariant tuple with parameters. 266 * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error. 267 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). 268 * 269 * The type of the @method_call function in #GDBusInterfaceVTable. 270 * 271 * Since: 2.26 272 */ 273 typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection, 274 const gchar *sender, 275 const gchar *object_path, 276 const gchar *interface_name, 277 const gchar *method_name, 278 GVariant *parameters, 279 GDBusMethodInvocation *invocation, 280 gpointer user_data); 281 282 /** 283 * GDBusInterfaceGetPropertyFunc: 284 * @connection: A #GDBusConnection. 285 * @sender: The unique bus name of the remote caller. 286 * @object_path: The object path that the method was invoked on. 287 * @interface_name: The D-Bus interface name for the property. 288 * @property_name: The name of the property to get the value of. 289 * @error: Return location for error. 290 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). 291 * 292 * The type of the @get_property function in #GDBusInterfaceVTable. 293 * 294 * Returns: A #GVariant with the value for @property_name or %NULL if 295 * @error is set. If the returned #GVariant is floating, it is 296 * consumed - otherwise its reference count is decreased by one. 297 * 298 * Since: 2.26 299 */ 300 typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection, 301 const gchar *sender, 302 const gchar *object_path, 303 const gchar *interface_name, 304 const gchar *property_name, 305 GError **error, 306 gpointer user_data); 307 308 /** 309 * GDBusInterfaceSetPropertyFunc: 310 * @connection: A #GDBusConnection. 311 * @sender: The unique bus name of the remote caller. 312 * @object_path: The object path that the method was invoked on. 313 * @interface_name: The D-Bus interface name for the property. 314 * @property_name: The name of the property to get the value of. 315 * @value: The value to set the property to. 316 * @error: Return location for error. 317 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). 318 * 319 * The type of the @set_property function in #GDBusInterfaceVTable. 320 * 321 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set. 322 * 323 * Since: 2.26 324 */ 325 typedef gboolean (*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection, 326 const gchar *sender, 327 const gchar *object_path, 328 const gchar *interface_name, 329 const gchar *property_name, 330 GVariant *value, 331 GError **error, 332 gpointer user_data); 333 334 /** 335 * GDBusInterfaceVTable: 336 * @method_call: Function for handling incoming method calls. 337 * @get_property: Function for getting a property. 338 * @set_property: Function for setting a property. 339 * 340 * Virtual table for handling properties and method calls for a D-Bus 341 * interface. 342 * 343 * Since 2.38, if you want to handle getting/setting D-Bus properties 344 * asynchronously, give %NULL as your get_property() or set_property() 345 * function. The D-Bus call will be directed to your @method_call function, 346 * with the provided @interface_name set to "org.freedesktop.DBus.Properties". 347 * 348 * Ownership of the #GDBusMethodInvocation object passed to the 349 * method_call() function is transferred to your handler; you must 350 * call one of the methods of #GDBusMethodInvocation to return a reply 351 * (possibly empty), or an error. These functions also take ownership 352 * of the passed-in invocation object, so unless the invocation 353 * object has otherwise been referenced, it will be then be freed. 354 * Calling one of these functions may be done within your 355 * method_call() implementation but it also can be done at a later 356 * point to handle the method asynchronously. 357 * 358 * The usual checks on the validity of the calls is performed. For 359 * `Get` calls, an error is automatically returned if the property does 360 * not exist or the permissions do not allow access. The same checks are 361 * performed for `Set` calls, and the provided value is also checked for 362 * being the correct type. 363 * 364 * For both `Get` and `Set` calls, the #GDBusMethodInvocation 365 * passed to the @method_call handler can be queried with 366 * g_dbus_method_invocation_get_property_info() to get a pointer 367 * to the #GDBusPropertyInfo of the property. 368 * 369 * If you have readable properties specified in your interface info, 370 * you must ensure that you either provide a non-%NULL @get_property() 371 * function or provide implementations of both the `Get` and `GetAll` 372 * methods on org.freedesktop.DBus.Properties interface in your @method_call 373 * function. Note that the required return type of the `Get` call is 374 * `(v)`, not the type of the property. `GetAll` expects a return value 375 * of type `a{sv}`. 376 * 377 * If you have writable properties specified in your interface info, 378 * you must ensure that you either provide a non-%NULL @set_property() 379 * function or provide an implementation of the `Set` call. If implementing 380 * the call, you must return the value of type %G_VARIANT_TYPE_UNIT. 381 * 382 * Since: 2.26 383 */ 384 struct _GDBusInterfaceVTable 385 { 386 GDBusInterfaceMethodCallFunc method_call; 387 GDBusInterfaceGetPropertyFunc get_property; 388 GDBusInterfaceSetPropertyFunc set_property; 389 390 /*< private >*/ 391 /* Padding for future expansion - also remember to update 392 * gdbusconnection.c:_g_dbus_interface_vtable_copy() when 393 * changing this. 394 */ 395 gpointer padding[8]; 396 }; 397 398 GLIB_AVAILABLE_IN_ALL 399 guint g_dbus_connection_register_object (GDBusConnection *connection, 400 const gchar *object_path, 401 GDBusInterfaceInfo *interface_info, 402 const GDBusInterfaceVTable *vtable, 403 gpointer user_data, 404 GDestroyNotify user_data_free_func, 405 GError **error); 406 GLIB_AVAILABLE_IN_2_46 407 guint g_dbus_connection_register_object_with_closures (GDBusConnection *connection, 408 const gchar *object_path, 409 GDBusInterfaceInfo *interface_info, 410 GClosure *method_call_closure, 411 GClosure *get_property_closure, 412 GClosure *set_property_closure, 413 GError **error); 414 GLIB_AVAILABLE_IN_ALL 415 gboolean g_dbus_connection_unregister_object (GDBusConnection *connection, 416 guint registration_id); 417 418 /* ---------------------------------------------------------------------------------------------------- */ 419 420 /** 421 * GDBusSubtreeEnumerateFunc: 422 * @connection: A #GDBusConnection. 423 * @sender: The unique bus name of the remote caller. 424 * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). 425 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). 426 * 427 * The type of the @enumerate function in #GDBusSubtreeVTable. 428 * 429 * This function is called when generating introspection data and also 430 * when preparing to dispatch incoming messages in the event that the 431 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not 432 * specified (ie: to verify that the object path is valid). 433 * 434 * Hierarchies are not supported; the items that you return should not 435 * contain the `/` character. 436 * 437 * The return value will be freed with g_strfreev(). 438 * 439 * Returns: (array zero-terminated=1) (transfer full): A newly allocated array of strings for node names that are children of @object_path. 440 * 441 * Since: 2.26 442 */ 443 typedef gchar** (*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection, 444 const gchar *sender, 445 const gchar *object_path, 446 gpointer user_data); 447 448 /** 449 * GDBusSubtreeIntrospectFunc: 450 * @connection: A #GDBusConnection. 451 * @sender: The unique bus name of the remote caller. 452 * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). 453 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. 454 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). 455 * 456 * The type of the @introspect function in #GDBusSubtreeVTable. 457 * 458 * Subtrees are flat. @node, if non-%NULL, is always exactly one 459 * segment of the object path (ie: it never contains a slash). 460 * 461 * This function should return %NULL to indicate that there is no object 462 * at this node. 463 * 464 * If this function returns non-%NULL, the return value is expected to 465 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo 466 * structures describing the interfaces implemented by @node. This 467 * array will have g_dbus_interface_info_unref() called on each item 468 * before being freed with g_free(). 469 * 470 * The difference between returning %NULL and an array containing zero 471 * items is that the standard DBus interfaces will returned to the 472 * remote introspector in the empty array case, but not in the %NULL 473 * case. 474 * 475 * Returns: (array zero-terminated=1) (nullable) (transfer full): A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. 476 * 477 * Since: 2.26 478 */ 479 typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection, 480 const gchar *sender, 481 const gchar *object_path, 482 const gchar *node, 483 gpointer user_data); 484 485 /** 486 * GDBusSubtreeDispatchFunc: 487 * @connection: A #GDBusConnection. 488 * @sender: The unique bus name of the remote caller. 489 * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). 490 * @interface_name: The D-Bus interface name that the method call or property access is for. 491 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. 492 * @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable. 493 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). 494 * 495 * The type of the @dispatch function in #GDBusSubtreeVTable. 496 * 497 * Subtrees are flat. @node, if non-%NULL, is always exactly one 498 * segment of the object path (ie: it never contains a slash). 499 * 500 * Returns: (nullable): A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. 501 * 502 * Since: 2.26 503 */ 504 typedef const GDBusInterfaceVTable * (*GDBusSubtreeDispatchFunc) (GDBusConnection *connection, 505 const gchar *sender, 506 const gchar *object_path, 507 const gchar *interface_name, 508 const gchar *node, 509 gpointer *out_user_data, 510 gpointer user_data); 511 512 /** 513 * GDBusSubtreeVTable: 514 * @enumerate: Function for enumerating child nodes. 515 * @introspect: Function for introspecting a child node. 516 * @dispatch: Function for dispatching a remote call on a child node. 517 * 518 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). 519 * 520 * Since: 2.26 521 */ 522 struct _GDBusSubtreeVTable 523 { 524 GDBusSubtreeEnumerateFunc enumerate; 525 GDBusSubtreeIntrospectFunc introspect; 526 GDBusSubtreeDispatchFunc dispatch; 527 528 /*< private >*/ 529 /* Padding for future expansion - also remember to update 530 * gdbusconnection.c:_g_dbus_subtree_vtable_copy() when 531 * changing this. 532 */ 533 gpointer padding[8]; 534 }; 535 536 GLIB_AVAILABLE_IN_ALL 537 guint g_dbus_connection_register_subtree (GDBusConnection *connection, 538 const gchar *object_path, 539 const GDBusSubtreeVTable *vtable, 540 GDBusSubtreeFlags flags, 541 gpointer user_data, 542 GDestroyNotify user_data_free_func, 543 GError **error); 544 GLIB_AVAILABLE_IN_ALL 545 gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection, 546 guint registration_id); 547 548 /* ---------------------------------------------------------------------------------------------------- */ 549 550 /** 551 * GDBusSignalCallback: 552 * @connection: A #GDBusConnection. 553 * @sender_name: (nullable): The unique bus name of the sender of the signal, 554 or %NULL on a peer-to-peer D-Bus connection. 555 * @object_path: The object path that the signal was emitted on. 556 * @interface_name: The name of the interface. 557 * @signal_name: The name of the signal. 558 * @parameters: A #GVariant tuple with parameters for the signal. 559 * @user_data: User data passed when subscribing to the signal. 560 * 561 * Signature for callback function used in g_dbus_connection_signal_subscribe(). 562 * 563 * Since: 2.26 564 */ 565 typedef void (*GDBusSignalCallback) (GDBusConnection *connection, 566 const gchar *sender_name, 567 const gchar *object_path, 568 const gchar *interface_name, 569 const gchar *signal_name, 570 GVariant *parameters, 571 gpointer user_data); 572 573 GLIB_AVAILABLE_IN_ALL 574 guint g_dbus_connection_signal_subscribe (GDBusConnection *connection, 575 const gchar *sender, 576 const gchar *interface_name, 577 const gchar *member, 578 const gchar *object_path, 579 const gchar *arg0, 580 GDBusSignalFlags flags, 581 GDBusSignalCallback callback, 582 gpointer user_data, 583 GDestroyNotify user_data_free_func); 584 GLIB_AVAILABLE_IN_ALL 585 void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection, 586 guint subscription_id); 587 588 /* ---------------------------------------------------------------------------------------------------- */ 589 590 /** 591 * GDBusMessageFilterFunction: 592 * @connection: (transfer none): A #GDBusConnection. 593 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of. 594 * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is 595 * a message to be sent to the other peer. 596 * @user_data: User data passed when adding the filter. 597 * 598 * Signature for function used in g_dbus_connection_add_filter(). 599 * 600 * A filter function is passed a #GDBusMessage and expected to return 601 * a #GDBusMessage too. Passive filter functions that don't modify the 602 * message can simply return the @message object: 603 * |[ 604 * static GDBusMessage * 605 * passive_filter (GDBusConnection *connection 606 * GDBusMessage *message, 607 * gboolean incoming, 608 * gpointer user_data) 609 * { 610 * // inspect @message 611 * return message; 612 * } 613 * ]| 614 * Filter functions that wants to drop a message can simply return %NULL: 615 * |[ 616 * static GDBusMessage * 617 * drop_filter (GDBusConnection *connection 618 * GDBusMessage *message, 619 * gboolean incoming, 620 * gpointer user_data) 621 * { 622 * if (should_drop_message) 623 * { 624 * g_object_unref (message); 625 * message = NULL; 626 * } 627 * return message; 628 * } 629 * ]| 630 * Finally, a filter function may modify a message by copying it: 631 * |[ 632 * static GDBusMessage * 633 * modifying_filter (GDBusConnection *connection 634 * GDBusMessage *message, 635 * gboolean incoming, 636 * gpointer user_data) 637 * { 638 * GDBusMessage *copy; 639 * GError *error; 640 * 641 * error = NULL; 642 * copy = g_dbus_message_copy (message, &error); 643 * // handle @error being set 644 * g_object_unref (message); 645 * 646 * // modify @copy 647 * 648 * return copy; 649 * } 650 * ]| 651 * If the returned #GDBusMessage is different from @message and cannot 652 * be sent on @connection (it could use features, such as file 653 * descriptors, not compatible with @connection), then a warning is 654 * logged to standard error. Applications can 655 * check this ahead of time using g_dbus_message_to_blob() passing a 656 * #GDBusCapabilityFlags value obtained from @connection. 657 * 658 * Returns: (transfer full) (nullable): A #GDBusMessage that will be freed with 659 * g_object_unref() or %NULL to drop the message. Passive filter 660 * functions can simply return the passed @message object. 661 * 662 * Since: 2.26 663 */ 664 typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection, 665 GDBusMessage *message, 666 gboolean incoming, 667 gpointer user_data); 668 669 GLIB_AVAILABLE_IN_ALL 670 guint g_dbus_connection_add_filter (GDBusConnection *connection, 671 GDBusMessageFilterFunction filter_function, 672 gpointer user_data, 673 GDestroyNotify user_data_free_func); 674 675 GLIB_AVAILABLE_IN_ALL 676 void g_dbus_connection_remove_filter (GDBusConnection *connection, 677 guint filter_id); 678 679 /* ---------------------------------------------------------------------------------------------------- */ 680 681 682 G_END_DECLS 683 684 #endif /* __G_DBUS_CONNECTION_H__ */ 685