gio/gdbusmethodinvocation.c

   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, see <http://www.gnu.org/licenses/>.
  17  *
  18  * Author: David Zeuthen <davidz@redhat.com>
  19  */
  20
  21 #include "config.h"
  22
  23 #include <stdlib.h>
  24
  25 #include "gdbusutils.h"
  26 #include "gdbusconnection.h"
  27 #include "gdbusmessage.h"
  28 #include "gdbusmethodinvocation.h"
  29 #include "gdbusintrospection.h"
  30 #include "gdbuserror.h"
  31 #include "gdbusprivate.h"
  32 #include "gioerror.h"
  33
  34 #ifdef G_OS_UNIX
  35 #include "gunixfdlist.h"
  36 #endif
  37
  38 #include "glibintl.h"
  39
  40 /**
  41  * SECTION:gdbusmethodinvocation
  42  * @short_description: Object for handling remote calls
  43  * @include: gio/gio.h
  44  *
  45  * Instances of the #GDBusMethodInvocation class are used when
  46  * handling D-Bus method calls. It provides a way to asynchronously
  47  * return results and errors.
  48  *
  49  * The normal way to obtain a #GDBusMethodInvocation object is to receive
  50  * it as an argument to the handle_method_call() function in a
  51  * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
  52  */
  53
  54 typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass;
  55
  56 /**
  57  * GDBusMethodInvocationClass:
  58  *
  59  * Class structure for #GDBusMethodInvocation.
  60  *
  61  * Since: 2.26
  62  */
  63 struct _GDBusMethodInvocationClass
  64 {
  65   /*< private >*/
  66   GObjectClass parent_class;
  67 };
  68
  69 /**
  70  * GDBusMethodInvocation:
  71  *
  72  * The #GDBusMethodInvocation structure contains only private data and
  73  * should only be accessed using the provided API.
  74  *
  75  * Since: 2.26
  76  */
  77 struct _GDBusMethodInvocation
  78 {
  79   /*< private >*/
  80   GObject parent_instance;
  81
  82   /* construct-only properties */
  83   gchar           *sender;
  84   gchar           *object_path;
  85   gchar           *interface_name;
  86   gchar           *method_name;
  87   GDBusMethodInfo *method_info;
  88   GDBusPropertyInfo *property_info;
  89   GDBusConnection *connection;
  90   GDBusMessage    *message;
  91   GVariant        *parameters;
  92   gpointer         user_data;
  93 };
  94
  95 G_DEFINE_TYPE (GDBusMethodInvocation, g_dbus_method_invocation, G_TYPE_OBJECT);
  96
  97 static void
  98 g_dbus_method_invocation_finalize (GObject *object)
  99 {
 100   GDBusMethodInvocation *invocation = G_DBUS_METHOD_INVOCATION (object);
 101
 102   g_free (invocation->sender);
 103   g_free (invocation->object_path);
 104   g_free (invocation->interface_name);
 105   g_free (invocation->method_name);
 106   if (invocation->method_info)
 107       g_dbus_method_info_unref (invocation->method_info);
 108   g_object_unref (invocation->connection);
 109   g_object_unref (invocation->message);
 110   g_variant_unref (invocation->parameters);
 111
 112   G_OBJECT_CLASS (g_dbus_method_invocation_parent_class)->finalize (object);
 113 }
 114
 115 static void
 116 g_dbus_method_invocation_class_init (GDBusMethodInvocationClass *klass)
 117 {
 118   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 119
 120   gobject_class->finalize = g_dbus_method_invocation_finalize;
 121 }
 122
 123 static void
 124 g_dbus_method_invocation_init (GDBusMethodInvocation *invocation)
 125 {
 126 }
 127
 128 /**
 129  * g_dbus_method_invocation_get_sender:
 130  * @invocation: A #GDBusMethodInvocation.
 131  *
 132  * Gets the bus name that invoked the method.
 133  *
 134  * Returns: A string. Do not free, it is owned by @invocation.
 135  *
 136  * Since: 2.26
 137  */
 138 const gchar *
 139 g_dbus_method_invocation_get_sender (GDBusMethodInvocation *invocation)
 140 {
 141   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 142   return invocation->sender;
 143 }
 144
 145 /**
 146  * g_dbus_method_invocation_get_object_path:
 147  * @invocation: A #GDBusMethodInvocation.
 148  *
 149  * Gets the object path the method was invoked on.
 150  *
 151  * Returns: A string. Do not free, it is owned by @invocation.
 152  *
 153  * Since: 2.26
 154  */
 155 const gchar *
 156 g_dbus_method_invocation_get_object_path (GDBusMethodInvocation *invocation)
 157 {
 158   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 159   return invocation->object_path;
 160 }
 161
 162 /**
 163  * g_dbus_method_invocation_get_interface_name:
 164  * @invocation: A #GDBusMethodInvocation.
 165  *
 166  * Gets the name of the D-Bus interface the method was invoked on.
 167  *
 168  * If this method call is a property Get, Set or GetAll call that has
 169  * been redirected to the method call handler then
 170  * "org.freedesktop.DBus.Properties" will be returned.  See
 171  * #GDBusInterfaceVTable for more information.
 172  *
 173  * Returns: A string. Do not free, it is owned by @invocation.
 174  *
 175  * Since: 2.26
 176  */
 177 const gchar *
 178 g_dbus_method_invocation_get_interface_name (GDBusMethodInvocation *invocation)
 179 {
 180   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 181   return invocation->interface_name;
 182 }
 183
 184 /**
 185  * g_dbus_method_invocation_get_method_info:
 186  * @invocation: A #GDBusMethodInvocation.
 187  *
 188  * Gets information about the method call, if any.
 189  *
 190  * If this method invocation is a property Get, Set or GetAll call that
 191  * has been redirected to the method call handler then %NULL will be
 192  * returned.  See g_dbus_method_invocation_get_property_info() and
 193  * #GDBusInterfaceVTable for more information.
 194  *
 195  * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
 196  *
 197  * Since: 2.26
 198  */
 199 const GDBusMethodInfo *
 200 g_dbus_method_invocation_get_method_info (GDBusMethodInvocation *invocation)
 201 {
 202   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 203   return invocation->method_info;
 204 }
 205
 206 /**
 207  * g_dbus_method_invocation_get_property_info:
 208  * @invocation: A #GDBusMethodInvocation
 209  *
 210  * Gets information about the property that this method call is for, if
 211  * any.
 212  *
 213  * This will only be set in the case of an invocation in response to a
 214  * property Get or Set call that has been directed to the method call
 215  * handler for an object on account of its property_get() or
 216  * property_set() vtable pointers being unset.
 217  *
 218  * See #GDBusInterfaceVTable for more information.
 219  *
 220  * If the call was GetAll, %NULL will be returned.
 221  *
 222  * Returns: (transfer none): a #GDBusPropertyInfo or %NULL
 223  *
 224  * Since: 2.38
 225  */
 226 const GDBusPropertyInfo *
 227 g_dbus_method_invocation_get_property_info (GDBusMethodInvocation *invocation)
 228 {
 229   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 230   return invocation->property_info;
 231 }
 232
 233 /**
 234  * g_dbus_method_invocation_get_method_name:
 235  * @invocation: A #GDBusMethodInvocation.
 236  *
 237  * Gets the name of the method that was invoked.
 238  *
 239  * Returns: A string. Do not free, it is owned by @invocation.
 240  *
 241  * Since: 2.26
 242  */
 243 const gchar *
 244 g_dbus_method_invocation_get_method_name (GDBusMethodInvocation *invocation)
 245 {
 246   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 247   return invocation->method_name;
 248 }
 249
 250 /**
 251  * g_dbus_method_invocation_get_connection:
 252  * @invocation: A #GDBusMethodInvocation.
 253  *
 254  * Gets the #GDBusConnection the method was invoked on.
 255  *
 256  * Returns: (transfer none):A #GDBusConnection. Do not free, it is owned by @invocation.
 257  *
 258  * Since: 2.26
 259  */
 260 GDBusConnection *
 261 g_dbus_method_invocation_get_connection (GDBusMethodInvocation *invocation)
 262 {
 263   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 264   return invocation->connection;
 265 }
 266
 267 /**
 268  * g_dbus_method_invocation_get_message:
 269  * @invocation: A #GDBusMethodInvocation.
 270  *
 271  * Gets the #GDBusMessage for the method invocation. This is useful if
 272  * you need to use low-level protocol features, such as UNIX file
 273  * descriptor passing, that cannot be properly expressed in the
 274  * #GVariant API.
 275  *
 276  * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
 277  * for an example of how to use this low-level API to send and receive
 278  * UNIX file descriptors.
 279  *
 280  * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
 281  *
 282  * Since: 2.26
 283  */
 284 GDBusMessage *
 285 g_dbus_method_invocation_get_message (GDBusMethodInvocation *invocation)
 286 {
 287   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 288   return invocation->message;
 289 }
 290
 291 /**
 292  * g_dbus_method_invocation_get_parameters:
 293  * @invocation: A #GDBusMethodInvocation.
 294  *
 295  * Gets the parameters of the method invocation. If there are no input
 296  * parameters then this will return a GVariant with 0 children rather than NULL.
 297  *
 298  * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
 299  *
 300  * Since: 2.26
 301  */
 302 GVariant *
 303 g_dbus_method_invocation_get_parameters (GDBusMethodInvocation *invocation)
 304 {
 305   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 306   return invocation->parameters;
 307 }
 308
 309 /**
 310  * g_dbus_method_invocation_get_user_data: (skip)
 311  * @invocation: A #GDBusMethodInvocation.
 312  *
 313  * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
 314  *
 315  * Returns: A #gpointer.
 316  *
 317  * Since: 2.26
 318  */
 319 gpointer
 320 g_dbus_method_invocation_get_user_data (GDBusMethodInvocation *invocation)
 321 {
 322   g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
 323   return invocation->user_data;
 324 }
 325
 326 /* < internal >
 327  * _g_dbus_method_invocation_new:
 328  * @sender: (nullable): The bus name that invoked the method or %NULL if @connection is not a bus connection.
 329  * @object_path: The object path the method was invoked on.
 330  * @interface_name: The name of the D-Bus interface the method was invoked on.
 331  * @method_name: The name of the method that was invoked.
 332  * @method_info: (nullable): Information about the method call or %NULL.
 333  * @property_info: (nullable): Information about the property or %NULL.
 334  * @connection: The #GDBusConnection the method was invoked on.
 335  * @message: The D-Bus message as a #GDBusMessage.
 336  * @parameters: The parameters as a #GVariant tuple.
 337  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
 338  *
 339  * Creates a new #GDBusMethodInvocation object.
 340  *
 341  * Returns: A #GDBusMethodInvocation. Free with g_object_unref().
 342  *
 343  * Since: 2.26
 344  */
 345 GDBusMethodInvocation *
 346 _g_dbus_method_invocation_new (const gchar             *sender,
 347                                const gchar             *object_path,
 348                                const gchar             *interface_name,
 349                                const gchar             *method_name,
 350                                const GDBusMethodInfo   *method_info,
 351                                const GDBusPropertyInfo *property_info,
 352                                GDBusConnection         *connection,
 353                                GDBusMessage            *message,
 354                                GVariant                *parameters,
 355                                gpointer                 user_data)
 356 {
 357   GDBusMethodInvocation *invocation;
 358
 359   g_return_val_if_fail (sender == NULL || g_dbus_is_name (sender), NULL);
 360   g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
 361   g_return_val_if_fail (interface_name == NULL || g_dbus_is_interface_name (interface_name), NULL);
 362   g_return_val_if_fail (g_dbus_is_member_name (method_name), NULL);
 363   g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection), NULL);
 364   g_return_val_if_fail (G_IS_DBUS_MESSAGE (message), NULL);
 365   g_return_val_if_fail (g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE), NULL);
 366
 367   invocation = G_DBUS_METHOD_INVOCATION (g_object_new (G_TYPE_DBUS_METHOD_INVOCATION, NULL));
 368   invocation->sender = g_strdup (sender);
 369   invocation->object_path = g_strdup (object_path);
 370   invocation->interface_name = g_strdup (interface_name);
 371   invocation->method_name = g_strdup (method_name);
 372   if (method_info)
 373     invocation->method_info = g_dbus_method_info_ref ((GDBusMethodInfo *)method_info);
 374   if (property_info)
 375     invocation->property_info = g_dbus_property_info_ref ((GDBusPropertyInfo *)property_info);
 376   invocation->connection = g_object_ref (connection);
 377   invocation->message = g_object_ref (message);
 378   invocation->parameters = g_variant_ref (parameters);
 379   invocation->user_data = user_data;
 380
 381   return invocation;
 382 }
 383
 384 /* ---------------------------------------------------------------------------------------------------- */
 385
 386 static void
 387 g_dbus_method_invocation_return_value_internal (GDBusMethodInvocation *invocation,
 388                                                 GVariant              *parameters,
 389                                                 GUnixFDList           *fd_list)
 390 {
 391   GDBusMessage *reply;
 392   GError *error;
 393
 394   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 395   g_return_if_fail ((parameters == NULL) || g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE));
 396
 397   if (g_dbus_message_get_flags (invocation->message) & G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED)
 398     {
 399       if (parameters != NULL)
 400         {
 401           g_variant_ref_sink (parameters);
 402           g_variant_unref (parameters);
 403         }
 404       goto out;
 405     }
 406
 407   if (parameters == NULL)
 408     parameters = g_variant_new_tuple (NULL, 0);
 409
 410   /* if we have introspection data, check that the signature of @parameters is correct */
 411   if (invocation->method_info != NULL)
 412     {
 413       GVariantType *type;
 414
 415       type = _g_dbus_compute_complete_signature (invocation->method_info->out_args);
 416
 417       if (!g_variant_is_of_type (parameters, type))
 418         {
 419           gchar *type_string = g_variant_type_dup_string (type);
 420
 421           g_warning ("Type of return value is incorrect: expected '%s', got '%s''",
 422                      type_string, g_variant_get_type_string (parameters));
 423           g_variant_type_free (type);
 424           g_free (type_string);
 425           goto out;
 426         }
 427       g_variant_type_free (type);
 428     }
 429
 430   /* property_info is only non-NULL if set that way from
 431    * GDBusConnection, so this must be the case of async property
 432    * handling on either 'Get', 'Set' or 'GetAll'.
 433    */
 434   if (invocation->property_info != NULL)
 435     {
 436       if (g_str_equal (invocation->method_name, "Get"))
 437         {
 438           GVariant *nested;
 439
 440           if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE ("(v)")))
 441             {
 442               g_warning ("Type of return value for property 'Get' call should be '(v)' but got '%s'",
 443                          g_variant_get_type_string (parameters));
 444               goto out;
 445             }
 446
 447           /* Go deeper and make sure that the value inside of the
 448            * variant matches the property type.
 449            */
 450           g_variant_get (parameters, "(v)", &nested);
 451           if (!g_str_equal (g_variant_get_type_string (nested), invocation->property_info->signature))
 452             {
 453               g_warning ("Value returned from property 'Get' call for '%s' should be '%s' but is '%s'",
 454                          invocation->property_info->name, invocation->property_info->signature,
 455                          g_variant_get_type_string (nested));
 456               g_variant_unref (nested);
 457               goto out;
 458             }
 459           g_variant_unref (nested);
 460         }
 461
 462       else if (g_str_equal (invocation->method_name, "GetAll"))
 463         {
 464           if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE ("(a{sv})")))
 465             {
 466               g_warning ("Type of return value for property 'GetAll' call should be '(a{sv})' but got '%s'",
 467                          g_variant_get_type_string (parameters));
 468               goto out;
 469             }
 470
 471           /* Could iterate the list of properties and make sure that all
 472            * of them are actually on the interface and with the correct
 473            * types, but let's not do that for now...
 474            */
 475         }
 476
 477       else if (g_str_equal (invocation->method_name, "Set"))
 478         {
 479           if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE_UNIT))
 480             {
 481               g_warning ("Type of return value for property 'Set' call should be '()' but got '%s'",
 482                          g_variant_get_type_string (parameters));
 483               goto out;
 484             }
 485         }
 486
 487       else
 488         g_assert_not_reached ();
 489     }
 490
 491   if (G_UNLIKELY (_g_dbus_debug_return ()))
 492     {
 493       _g_dbus_debug_print_lock ();
 494       g_print ("========================================================================\n"
 495                "GDBus-debug:Return:\n"
 496                " >>>> METHOD RETURN\n"
 497                "      in response to %s.%s()\n"
 498                "      on object %s\n"
 499                "      to name %s\n"
 500                "      reply-serial %d\n",
 501                invocation->interface_name, invocation->method_name,
 502                invocation->object_path,
 503                invocation->sender,
 504                g_dbus_message_get_serial (invocation->message));
 505       _g_dbus_debug_print_unlock ();
 506     }
 507
 508   reply = g_dbus_message_new_method_reply (invocation->message);
 509   g_dbus_message_set_body (reply, parameters);
 510
 511 #ifdef G_OS_UNIX
 512   if (fd_list != NULL)
 513     g_dbus_message_set_unix_fd_list (reply, fd_list);
 514 #endif
 515
 516   error = NULL;
 517   if (!g_dbus_connection_send_message (g_dbus_method_invocation_get_connection (invocation), reply, G_DBUS_SEND_MESSAGE_FLAGS_NONE, NULL, &error))
 518     {
 519       if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CLOSED))
 520         g_warning ("Error sending message: %s", error->message);
 521       g_error_free (error);
 522     }
 523   g_object_unref (reply);
 524
 525  out:
 526   g_object_unref (invocation);
 527 }
 528
 529 /**
 530  * g_dbus_method_invocation_return_value:
 531  * @invocation: (transfer full): A #GDBusMethodInvocation.
 532  * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
 533  *
 534  * Finishes handling a D-Bus method call by returning @parameters.
 535  * If the @parameters GVariant is floating, it is consumed.
 536  *
 537  * It is an error if @parameters is not of the right format: it must be a tuple
 538  * containing the out-parameters of the D-Bus method. Even if the method has a
 539  * single out-parameter, it must be contained in a tuple. If the method has no
 540  * out-parameters, @parameters may be %NULL or an empty tuple.
 541  *
 542  * |[<!-- language="C" -->
 543  * GDBusMethodInvocation *invocation = some_invocation;
 544  * g_autofree gchar *result_string = NULL;
 545  * g_autoptr (GError) error = NULL;
 546  *
 547  * result_string = calculate_result (&error);
 548  *
 549  * if (error != NULL)
 550  *   g_dbus_method_invocation_return_gerror (invocation, error);
 551  * else
 552  *   g_dbus_method_invocation_return_value (invocation,
 553  *                                          g_variant_new ("(s)", result_string));
 554  *
 555  * /<!-- -->* Do not free @invocation here; returning a value does that *<!-- -->/
 556  * ]|
 557  *
 558  * This method will take ownership of @invocation. See
 559  * #GDBusInterfaceVTable for more information about the ownership of
 560  * @invocation.
 561  *
 562  * Since 2.48, if the method call requested for a reply not to be sent
 563  * then this call will sink @parameters and free @invocation, but
 564  * otherwise do nothing (as per the recommendations of the D-Bus
 565  * specification).
 566  *
 567  * Since: 2.26
 568  */
 569 void
 570 g_dbus_method_invocation_return_value (GDBusMethodInvocation *invocation,
 571                                        GVariant              *parameters)
 572 {
 573   g_dbus_method_invocation_return_value_internal (invocation, parameters, NULL);
 574 }
 575
 576 #ifdef G_OS_UNIX
 577 /**
 578  * g_dbus_method_invocation_return_value_with_unix_fd_list:
 579  * @invocation: (transfer full): A #GDBusMethodInvocation.
 580  * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
 581  * @fd_list: (nullable): A #GUnixFDList or %NULL.
 582  *
 583  * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
 584  *
 585  * This method is only available on UNIX.
 586  *
 587  * This method will take ownership of @invocation. See
 588  * #GDBusInterfaceVTable for more information about the ownership of
 589  * @invocation.
 590  *
 591  * Since: 2.30
 592  */
 593 void
 594 g_dbus_method_invocation_return_value_with_unix_fd_list (GDBusMethodInvocation *invocation,
 595                                                          GVariant              *parameters,
 596                                                          GUnixFDList           *fd_list)
 597 {
 598   g_dbus_method_invocation_return_value_internal (invocation, parameters, fd_list);
 599 }
 600 #endif
 601
 602 /* ---------------------------------------------------------------------------------------------------- */
 603
 604 /**
 605  * g_dbus_method_invocation_return_error:
 606  * @invocation: (transfer full): A #GDBusMethodInvocation.
 607  * @domain: A #GQuark for the #GError error domain.
 608  * @code: The error code.
 609  * @format: printf()-style format.
 610  * @...: Parameters for @format.
 611  *
 612  * Finishes handling a D-Bus method call by returning an error.
 613  *
 614  * See g_dbus_error_encode_gerror() for details about what error name
 615  * will be returned on the wire. In a nutshell, if the given error is
 616  * registered using g_dbus_error_register_error() the name given
 617  * during registration is used. Otherwise, a name of the form
 618  * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
 619  * transparent mapping of #GError between applications using GDBus.
 620  *
 621  * If you are writing an application intended to be portable,
 622  * always register errors with g_dbus_error_register_error()
 623  * or use g_dbus_method_invocation_return_dbus_error().
 624  *
 625  * This method will take ownership of @invocation. See
 626  * #GDBusInterfaceVTable for more information about the ownership of
 627  * @invocation.
 628  *
 629  * Since 2.48, if the method call requested for a reply not to be sent
 630  * then this call will free @invocation but otherwise do nothing (as per
 631  * the recommendations of the D-Bus specification).
 632  *
 633  * Since: 2.26
 634  */
 635 void
 636 g_dbus_method_invocation_return_error (GDBusMethodInvocation *invocation,
 637                                        GQuark                 domain,
 638                                        gint                   code,
 639                                        const gchar           *format,
 640                                        ...)
 641 {
 642   va_list var_args;
 643
 644   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 645   g_return_if_fail (format != NULL);
 646
 647   va_start (var_args, format);
 648   g_dbus_method_invocation_return_error_valist (invocation,
 649                                                 domain,
 650                                                 code,
 651                                                 format,
 652                                                 var_args);
 653   va_end (var_args);
 654 }
 655
 656 /**
 657  * g_dbus_method_invocation_return_error_valist:
 658  * @invocation: (transfer full): A #GDBusMethodInvocation.
 659  * @domain: A #GQuark for the #GError error domain.
 660  * @code: The error code.
 661  * @format: printf()-style format.
 662  * @var_args: #va_list of parameters for @format.
 663  *
 664  * Like g_dbus_method_invocation_return_error() but intended for
 665  * language bindings.
 666  *
 667  * This method will take ownership of @invocation. See
 668  * #GDBusInterfaceVTable for more information about the ownership of
 669  * @invocation.
 670  *
 671  * Since: 2.26
 672  */
 673 void
 674 g_dbus_method_invocation_return_error_valist (GDBusMethodInvocation *invocation,
 675                                               GQuark                 domain,
 676                                               gint                   code,
 677                                               const gchar           *format,
 678                                               va_list                var_args)
 679 {
 680   gchar *literal_message;
 681
 682   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 683   g_return_if_fail (format != NULL);
 684
 685   literal_message = g_strdup_vprintf (format, var_args);
 686   g_dbus_method_invocation_return_error_literal (invocation,
 687                                                  domain,
 688                                                  code,
 689                                                  literal_message);
 690   g_free (literal_message);
 691 }
 692
 693 /**
 694  * g_dbus_method_invocation_return_error_literal:
 695  * @invocation: (transfer full): A #GDBusMethodInvocation.
 696  * @domain: A #GQuark for the #GError error domain.
 697  * @code: The error code.
 698  * @message: The error message.
 699  *
 700  * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
 701  *
 702  * This method will take ownership of @invocation. See
 703  * #GDBusInterfaceVTable for more information about the ownership of
 704  * @invocation.
 705  *
 706  * Since: 2.26
 707  */
 708 void
 709 g_dbus_method_invocation_return_error_literal (GDBusMethodInvocation *invocation,
 710                                                GQuark                 domain,
 711                                                gint                   code,
 712                                                const gchar           *message)
 713 {
 714   GError *error;
 715
 716   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 717   g_return_if_fail (message != NULL);
 718
 719   error = g_error_new_literal (domain, code, message);
 720   g_dbus_method_invocation_return_gerror (invocation, error);
 721   g_error_free (error);
 722 }
 723
 724 /**
 725  * g_dbus_method_invocation_return_gerror:
 726  * @invocation: (transfer full): A #GDBusMethodInvocation.
 727  * @error: A #GError.
 728  *
 729  * Like g_dbus_method_invocation_return_error() but takes a #GError
 730  * instead of the error domain, error code and message.
 731  *
 732  * This method will take ownership of @invocation. See
 733  * #GDBusInterfaceVTable for more information about the ownership of
 734  * @invocation.
 735  *
 736  * Since: 2.26
 737  */
 738 void
 739 g_dbus_method_invocation_return_gerror (GDBusMethodInvocation *invocation,
 740                                         const GError          *error)
 741 {
 742   gchar *dbus_error_name;
 743
 744   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 745   g_return_if_fail (error != NULL);
 746
 747   dbus_error_name = g_dbus_error_encode_gerror (error);
 748
 749   g_dbus_method_invocation_return_dbus_error (invocation,
 750                                               dbus_error_name,
 751                                               error->message);
 752   g_free (dbus_error_name);
 753 }
 754
 755 /**
 756  * g_dbus_method_invocation_take_error: (skip)
 757  * @invocation: (transfer full): A #GDBusMethodInvocation.
 758  * @error: (transfer full): A #GError.
 759  *
 760  * Like g_dbus_method_invocation_return_gerror() but takes ownership
 761  * of @error so the caller does not need to free it.
 762  *
 763  * This method will take ownership of @invocation. See
 764  * #GDBusInterfaceVTable for more information about the ownership of
 765  * @invocation.
 766  *
 767  * Since: 2.30
 768  */
 769 void
 770 g_dbus_method_invocation_take_error (GDBusMethodInvocation *invocation,
 771                                      GError                *error)
 772 {
 773   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 774   g_return_if_fail (error != NULL);
 775   g_dbus_method_invocation_return_gerror (invocation, error);
 776   g_error_free (error);
 777 }
 778
 779 /**
 780  * g_dbus_method_invocation_return_dbus_error:
 781  * @invocation: (transfer full): A #GDBusMethodInvocation.
 782  * @error_name: A valid D-Bus error name.
 783  * @error_message: A valid D-Bus error message.
 784  *
 785  * Finishes handling a D-Bus method call by returning an error.
 786  *
 787  * This method will take ownership of @invocation. See
 788  * #GDBusInterfaceVTable for more information about the ownership of
 789  * @invocation.
 790  *
 791  * Since: 2.26
 792  */
 793 void
 794 g_dbus_method_invocation_return_dbus_error (GDBusMethodInvocation *invocation,
 795                                             const gchar           *error_name,
 796                                             const gchar           *error_message)
 797 {
 798   GDBusMessage *reply;
 799
 800   g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
 801   g_return_if_fail (error_name != NULL && g_dbus_is_name (error_name));
 802   g_return_if_fail (error_message != NULL);
 803
 804   if (g_dbus_message_get_flags (invocation->message) & G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED)
 805     goto out;
 806
 807   if (G_UNLIKELY (_g_dbus_debug_return ()))
 808     {
 809       _g_dbus_debug_print_lock ();
 810       g_print ("========================================================================\n"
 811                "GDBus-debug:Return:\n"
 812                " >>>> METHOD ERROR %s\n"
 813                "      message '%s'\n"
 814                "      in response to %s.%s()\n"
 815                "      on object %s\n"
 816                "      to name %s\n"
 817                "      reply-serial %d\n",
 818                error_name,
 819                error_message,
 820                invocation->interface_name, invocation->method_name,
 821                invocation->object_path,
 822                invocation->sender,
 823                g_dbus_message_get_serial (invocation->message));
 824       _g_dbus_debug_print_unlock ();
 825     }
 826
 827   reply = g_dbus_message_new_method_error_literal (invocation->message,
 828                                                    error_name,
 829                                                    error_message);
 830   g_dbus_connection_send_message (g_dbus_method_invocation_get_connection (invocation), reply, G_DBUS_SEND_MESSAGE_FLAGS_NONE, NULL, NULL);
 831   g_object_unref (reply);
 832
 833 out:
 834   g_object_unref (invocation);
 835 }