1 /* GDBus - GLib D-Bus Library
3 * Copyright (C) 2008-2010 Red Hat, Inc.
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.
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.
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/>.
18 * Author: David Zeuthen <davidz@redhat.com>
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"
34 #include "gunixfdlist.h"
40 * SECTION:gdbusmethodinvocation
41 * @short_description: Object for handling remote calls
44 * Instances of the #GDBusMethodInvocation class are used when
45 * handling D-Bus method calls. It provides a way to asynchronously
46 * return results and errors.
48 * The normal way to obtain a #GDBusMethodInvocation object is to receive
49 * it as an argument to the handle_method_call() function in a
50 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
53 typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass;
56 * GDBusMethodInvocationClass:
58 * Class structure for #GDBusMethodInvocation.
62 struct _GDBusMethodInvocationClass
65 GObjectClass parent_class;
69 * GDBusMethodInvocation:
71 * The #GDBusMethodInvocation structure contains only private data and
72 * should only be accessed using the provided API.
76 struct _GDBusMethodInvocation
79 GObject parent_instance;
81 /* construct-only properties */
84 gchar *interface_name;
86 GDBusMethodInfo *method_info;
87 GDBusPropertyInfo *property_info;
88 GDBusConnection *connection;
89 GDBusMessage *message;
94 G_DEFINE_TYPE (GDBusMethodInvocation, g_dbus_method_invocation, G_TYPE_OBJECT);
97 g_dbus_method_invocation_finalize (GObject *object)
99 GDBusMethodInvocation *invocation = G_DBUS_METHOD_INVOCATION (object);
101 g_free (invocation->sender);
102 g_free (invocation->object_path);
103 g_free (invocation->interface_name);
104 g_free (invocation->method_name);
105 if (invocation->method_info)
106 g_dbus_method_info_unref (invocation->method_info);
107 g_object_unref (invocation->connection);
108 g_object_unref (invocation->message);
109 g_variant_unref (invocation->parameters);
111 G_OBJECT_CLASS (g_dbus_method_invocation_parent_class)->finalize (object);
115 g_dbus_method_invocation_class_init (GDBusMethodInvocationClass *klass)
117 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
119 gobject_class->finalize = g_dbus_method_invocation_finalize;
123 g_dbus_method_invocation_init (GDBusMethodInvocation *invocation)
128 * g_dbus_method_invocation_get_sender:
129 * @invocation: A #GDBusMethodInvocation.
131 * Gets the bus name that invoked the method.
133 * Returns: A string. Do not free, it is owned by @invocation.
138 g_dbus_method_invocation_get_sender (GDBusMethodInvocation *invocation)
140 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
141 return invocation->sender;
145 * g_dbus_method_invocation_get_object_path:
146 * @invocation: A #GDBusMethodInvocation.
148 * Gets the object path the method was invoked on.
150 * Returns: A string. Do not free, it is owned by @invocation.
155 g_dbus_method_invocation_get_object_path (GDBusMethodInvocation *invocation)
157 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
158 return invocation->object_path;
162 * g_dbus_method_invocation_get_interface_name:
163 * @invocation: A #GDBusMethodInvocation.
165 * Gets the name of the D-Bus interface the method was invoked on.
167 * If this method call is a property Get, Set or GetAll call that has
168 * been redirected to the method call handler then
169 * "org.freedesktop.DBus.Properties" will be returned. See
170 * #GDBusInterfaceVTable for more information.
172 * Returns: A string. Do not free, it is owned by @invocation.
177 g_dbus_method_invocation_get_interface_name (GDBusMethodInvocation *invocation)
179 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
180 return invocation->interface_name;
184 * g_dbus_method_invocation_get_method_info:
185 * @invocation: A #GDBusMethodInvocation.
187 * Gets information about the method call, if any.
189 * If this method invocation is a property Get, Set or GetAll call that
190 * has been redirected to the method call handler then %NULL will be
191 * returned. See g_dbus_method_invocation_get_property_info() and
192 * #GDBusInterfaceVTable for more information.
194 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
198 const GDBusMethodInfo *
199 g_dbus_method_invocation_get_method_info (GDBusMethodInvocation *invocation)
201 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
202 return invocation->method_info;
206 * g_dbus_method_invocation_get_property_info:
207 * @invocation: A #GDBusMethodInvocation
209 * Gets information about the property that this method call is for, if
212 * This will only be set in the case of an invocation in response to a
213 * property Get or Set call that has been directed to the method call
214 * handler for an object on account of its property_get() or
215 * property_set() vtable pointers being unset.
217 * See #GDBusInterfaceVTable for more information.
219 * If the call was GetAll, %NULL will be returned.
221 * Returns: (transfer none): a #GDBusPropertyInfo or %NULL
225 const GDBusPropertyInfo *
226 g_dbus_method_invocation_get_property_info (GDBusMethodInvocation *invocation)
228 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
229 return invocation->property_info;
233 * g_dbus_method_invocation_get_method_name:
234 * @invocation: A #GDBusMethodInvocation.
236 * Gets the name of the method that was invoked.
238 * Returns: A string. Do not free, it is owned by @invocation.
243 g_dbus_method_invocation_get_method_name (GDBusMethodInvocation *invocation)
245 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
246 return invocation->method_name;
250 * g_dbus_method_invocation_get_connection:
251 * @invocation: A #GDBusMethodInvocation.
253 * Gets the #GDBusConnection the method was invoked on.
255 * Returns: (transfer none):A #GDBusConnection. Do not free, it is owned by @invocation.
260 g_dbus_method_invocation_get_connection (GDBusMethodInvocation *invocation)
262 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
263 return invocation->connection;
267 * g_dbus_method_invocation_get_message:
268 * @invocation: A #GDBusMethodInvocation.
270 * Gets the #GDBusMessage for the method invocation. This is useful if
271 * you need to use low-level protocol features, such as UNIX file
272 * descriptor passing, that cannot be properly expressed in the
275 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
276 * for an example of how to use this low-level API to send and receive
277 * UNIX file descriptors.
279 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
284 g_dbus_method_invocation_get_message (GDBusMethodInvocation *invocation)
286 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
287 return invocation->message;
291 * g_dbus_method_invocation_get_parameters:
292 * @invocation: A #GDBusMethodInvocation.
294 * Gets the parameters of the method invocation. If there are no input
295 * parameters then this will return a GVariant with 0 children rather than NULL.
297 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
302 g_dbus_method_invocation_get_parameters (GDBusMethodInvocation *invocation)
304 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
305 return invocation->parameters;
309 * g_dbus_method_invocation_peek_unix_fd:
310 * @invocation: A #GDBusMethodInvocation.
313 * Gets the fd associated with @index in the method invocation.
315 * If there is no file descriptor at the given index, -1 is returned.
317 * The returned file descriptor is owned by the message and must not be
318 * closed by the caller. Use dup() if you want your own copy.
320 * Returns: the file descriptor, or -1
324 g_dbus_method_invocation_peek_unix_fd (GDBusMethodInvocation *invocation,
327 GUnixFDList *fd_list;
329 fd_list = g_dbus_message_get_unix_fd_list (invocation->message);
336 fds = g_unix_fd_list_peek_fds (fd_list, &n_fds);
338 if (index_ < (guint) n_fds)
347 * g_dbus_method_invocation_get_user_data: (skip)
348 * @invocation: A #GDBusMethodInvocation.
350 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
352 * Returns: A #gpointer.
357 g_dbus_method_invocation_get_user_data (GDBusMethodInvocation *invocation)
359 g_return_val_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation), NULL);
360 return invocation->user_data;
364 * _g_dbus_method_invocation_new:
365 * @sender: (allow-none): The bus name that invoked the method or %NULL if @connection is not a bus connection.
366 * @object_path: The object path the method was invoked on.
367 * @interface_name: The name of the D-Bus interface the method was invoked on.
368 * @method_name: The name of the method that was invoked.
369 * @method_info: (allow-none): Information about the method call or %NULL.
370 * @property_info: (allow-none): Information about the property or %NULL.
371 * @connection: The #GDBusConnection the method was invoked on.
372 * @message: The D-Bus message as a #GDBusMessage.
373 * @parameters: The parameters as a #GVariant tuple.
374 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
376 * Creates a new #GDBusMethodInvocation object.
378 * Returns: A #GDBusMethodInvocation. Free with g_object_unref().
382 GDBusMethodInvocation *
383 _g_dbus_method_invocation_new (const gchar *sender,
384 const gchar *object_path,
385 const gchar *interface_name,
386 const gchar *method_name,
387 const GDBusMethodInfo *method_info,
388 const GDBusPropertyInfo *property_info,
389 GDBusConnection *connection,
390 GDBusMessage *message,
391 GVariant *parameters,
394 GDBusMethodInvocation *invocation;
396 g_return_val_if_fail (sender == NULL || g_dbus_is_name (sender), NULL);
397 g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
398 g_return_val_if_fail (interface_name == NULL || g_dbus_is_interface_name (interface_name), NULL);
399 g_return_val_if_fail (g_dbus_is_member_name (method_name), NULL);
400 g_return_val_if_fail (G_IS_DBUS_CONNECTION (connection), NULL);
401 g_return_val_if_fail (G_IS_DBUS_MESSAGE (message), NULL);
402 g_return_val_if_fail (g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE), NULL);
404 invocation = G_DBUS_METHOD_INVOCATION (g_object_new (G_TYPE_DBUS_METHOD_INVOCATION, NULL));
405 invocation->sender = g_strdup (sender);
406 invocation->object_path = g_strdup (object_path);
407 invocation->interface_name = g_strdup (interface_name);
408 invocation->method_name = g_strdup (method_name);
410 invocation->method_info = g_dbus_method_info_ref ((GDBusMethodInfo *)method_info);
412 invocation->property_info = g_dbus_property_info_ref ((GDBusPropertyInfo *)property_info);
413 invocation->connection = g_object_ref (connection);
414 invocation->message = g_object_ref (message);
415 invocation->parameters = g_variant_ref (parameters);
416 invocation->user_data = user_data;
421 /* ---------------------------------------------------------------------------------------------------- */
424 g_dbus_method_invocation_return_value_internal (GDBusMethodInvocation *invocation,
425 GVariant *parameters,
426 GUnixFDList *fd_list)
431 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
432 g_return_if_fail ((parameters == NULL) || g_variant_is_of_type (parameters, G_VARIANT_TYPE_TUPLE));
434 if (parameters == NULL)
435 parameters = g_variant_new_tuple (NULL, 0);
437 /* if we have introspection data, check that the signature of @parameters is correct */
438 if (invocation->method_info != NULL)
442 type = _g_dbus_compute_complete_signature (invocation->method_info->out_args);
444 if (!g_variant_is_of_type (parameters, type))
446 gchar *type_string = g_variant_type_dup_string (type);
448 g_warning ("Type of return value is incorrect: expected '%s', got '%s''",
449 type_string, g_variant_get_type_string (parameters));
450 g_variant_type_free (type);
451 g_free (type_string);
454 g_variant_type_free (type);
457 /* property_info is only non-NULL if set that way from
458 * GDBusConnection, so this must be the case of async property
459 * handling on either 'Get', 'Set' or 'GetAll'.
461 if (invocation->property_info != NULL)
463 if (g_str_equal (invocation->method_name, "Get"))
467 if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE ("(v)")))
469 g_warning ("Type of return value for property 'Get' call should be '(v)' but got '%s'",
470 g_variant_get_type_string (parameters));
474 /* Go deeper and make sure that the value inside of the
475 * variant matches the property type.
477 g_variant_get (parameters, "(v)", &nested);
478 if (!g_str_equal (g_variant_get_type_string (nested), invocation->property_info->signature))
480 g_warning ("Value returned from property 'Get' call for '%s' should be '%s' but is '%s'",
481 invocation->property_info->name, invocation->property_info->signature,
482 g_variant_get_type_string (nested));
483 g_variant_unref (nested);
486 g_variant_unref (nested);
489 else if (g_str_equal (invocation->method_name, "GetAll"))
491 if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE ("(a{sv})")))
493 g_warning ("Type of return value for property 'GetAll' call should be '(a{sv})' but got '%s'",
494 g_variant_get_type_string (parameters));
498 /* Could iterate the list of properties and make sure that all
499 * of them are actually on the interface and with the correct
500 * types, but let's not do that for now...
504 else if (g_str_equal (invocation->method_name, "Set"))
506 if (!g_variant_is_of_type (parameters, G_VARIANT_TYPE_UNIT))
508 g_warning ("Type of return value for property 'Set' call should be '()' but got '%s'",
509 g_variant_get_type_string (parameters));
515 g_assert_not_reached ();
518 if (G_UNLIKELY (_g_dbus_debug_return ()))
520 _g_dbus_debug_print_lock ();
521 g_print ("========================================================================\n"
522 "GDBus-debug:Return:\n"
523 " >>>> METHOD RETURN\n"
524 " in response to %s.%s()\n"
527 " reply-serial %d\n",
528 invocation->interface_name, invocation->method_name,
529 invocation->object_path,
531 g_dbus_message_get_serial (invocation->message));
532 _g_dbus_debug_print_unlock ();
535 reply = g_dbus_message_new_method_reply (invocation->message);
536 g_dbus_message_set_body (reply, parameters);
540 g_dbus_message_set_unix_fd_list (reply, fd_list);
544 if (!g_dbus_connection_send_message (g_dbus_method_invocation_get_connection (invocation), reply, G_DBUS_SEND_MESSAGE_FLAGS_NONE, NULL, &error))
546 g_warning ("Error sending message: %s", error->message);
547 g_error_free (error);
549 g_object_unref (reply);
552 g_object_unref (invocation);
556 * g_dbus_method_invocation_return_value:
557 * @invocation: (transfer full): A #GDBusMethodInvocation.
558 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
560 * Finishes handling a D-Bus method call by returning @parameters.
561 * If the @parameters GVariant is floating, it is consumed.
563 * It is an error if @parameters is not of the right format.
565 * This method will free @invocation, you cannot use it afterwards.
570 g_dbus_method_invocation_return_value (GDBusMethodInvocation *invocation,
571 GVariant *parameters)
573 g_dbus_method_invocation_return_value_internal (invocation, parameters, NULL);
578 * g_dbus_method_invocation_return_value_with_unix_fd_list:
579 * @invocation: (transfer full): A #GDBusMethodInvocation.
580 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
581 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
583 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
585 * This method is only available on UNIX.
587 * This method will free @invocation, you cannot use it afterwards.
592 g_dbus_method_invocation_return_value_with_unix_fd_list (GDBusMethodInvocation *invocation,
593 GVariant *parameters,
594 GUnixFDList *fd_list)
596 g_dbus_method_invocation_return_value_internal (invocation, parameters, fd_list);
600 /* ---------------------------------------------------------------------------------------------------- */
603 * g_dbus_method_invocation_return_error:
604 * @invocation: (transfer full): A #GDBusMethodInvocation.
605 * @domain: A #GQuark for the #GError error domain.
606 * @code: The error code.
607 * @format: printf()-style format.
608 * @...: Parameters for @format.
610 * Finishes handling a D-Bus method call by returning an error.
612 * See g_dbus_error_encode_gerror() for details about what error name
613 * will be returned on the wire. In a nutshell, if the given error is
614 * registered using g_dbus_error_register_error() the name given
615 * during registration is used. Otherwise, a name of the form
616 * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
617 * transparent mapping of #GError between applications using GDBus.
619 * If you are writing an application intended to be portable,
620 * always register errors with g_dbus_error_register_error()
621 * or use g_dbus_method_invocation_return_dbus_error().
623 * This method will free @invocation, you cannot use it afterwards.
628 g_dbus_method_invocation_return_error (GDBusMethodInvocation *invocation,
636 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
637 g_return_if_fail (format != NULL);
639 va_start (var_args, format);
640 g_dbus_method_invocation_return_error_valist (invocation,
649 * g_dbus_method_invocation_return_error_valist:
650 * @invocation: (transfer full): A #GDBusMethodInvocation.
651 * @domain: A #GQuark for the #GError error domain.
652 * @code: The error code.
653 * @format: printf()-style format.
654 * @var_args: #va_list of parameters for @format.
656 * Like g_dbus_method_invocation_return_error() but intended for
659 * This method will free @invocation, you cannot use it afterwards.
664 g_dbus_method_invocation_return_error_valist (GDBusMethodInvocation *invocation,
670 gchar *literal_message;
672 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
673 g_return_if_fail (format != NULL);
675 literal_message = g_strdup_vprintf (format, var_args);
676 g_dbus_method_invocation_return_error_literal (invocation,
680 g_free (literal_message);
684 * g_dbus_method_invocation_return_error_literal:
685 * @invocation: (transfer full): A #GDBusMethodInvocation.
686 * @domain: A #GQuark for the #GError error domain.
687 * @code: The error code.
688 * @message: The error message.
690 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
692 * This method will free @invocation, you cannot use it afterwards.
697 g_dbus_method_invocation_return_error_literal (GDBusMethodInvocation *invocation,
700 const gchar *message)
704 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
705 g_return_if_fail (message != NULL);
707 error = g_error_new_literal (domain, code, message);
708 g_dbus_method_invocation_return_gerror (invocation, error);
709 g_error_free (error);
713 * g_dbus_method_invocation_return_gerror:
714 * @invocation: (transfer full): A #GDBusMethodInvocation.
717 * Like g_dbus_method_invocation_return_error() but takes a #GError
718 * instead of the error domain, error code and message.
720 * This method will free @invocation, you cannot use it afterwards.
725 g_dbus_method_invocation_return_gerror (GDBusMethodInvocation *invocation,
728 gchar *dbus_error_name;
730 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
731 g_return_if_fail (error != NULL);
733 dbus_error_name = g_dbus_error_encode_gerror (error);
735 g_dbus_method_invocation_return_dbus_error (invocation,
738 g_free (dbus_error_name);
742 * g_dbus_method_invocation_take_error: (skip)
743 * @invocation: (transfer full): A #GDBusMethodInvocation.
744 * @error: (transfer full): A #GError.
746 * Like g_dbus_method_invocation_return_gerror() but takes ownership
747 * of @error so the caller does not need to free it.
749 * This method will free @invocation, you cannot use it afterwards.
754 g_dbus_method_invocation_take_error (GDBusMethodInvocation *invocation,
757 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
758 g_return_if_fail (error != NULL);
759 g_dbus_method_invocation_return_gerror (invocation, error);
760 g_error_free (error);
764 * g_dbus_method_invocation_return_dbus_error:
765 * @invocation: (transfer full): A #GDBusMethodInvocation.
766 * @error_name: A valid D-Bus error name.
767 * @error_message: A valid D-Bus error message.
769 * Finishes handling a D-Bus method call by returning an error.
771 * This method will free @invocation, you cannot use it afterwards.
776 g_dbus_method_invocation_return_dbus_error (GDBusMethodInvocation *invocation,
777 const gchar *error_name,
778 const gchar *error_message)
782 g_return_if_fail (G_IS_DBUS_METHOD_INVOCATION (invocation));
783 g_return_if_fail (error_name != NULL && g_dbus_is_name (error_name));
784 g_return_if_fail (error_message != NULL);
786 if (G_UNLIKELY (_g_dbus_debug_return ()))
788 _g_dbus_debug_print_lock ();
789 g_print ("========================================================================\n"
790 "GDBus-debug:Return:\n"
791 " >>>> METHOD ERROR %s\n"
793 " in response to %s.%s()\n"
796 " reply-serial %d\n",
799 invocation->interface_name, invocation->method_name,
800 invocation->object_path,
802 g_dbus_message_get_serial (invocation->message));
803 _g_dbus_debug_print_unlock ();
806 reply = g_dbus_message_new_method_error_literal (invocation->message,
809 g_dbus_connection_send_message (g_dbus_method_invocation_get_connection (invocation), reply, G_DBUS_SEND_MESSAGE_FLAGS_NONE, NULL, NULL);
810 g_object_unref (reply);
812 g_object_unref (invocation);