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