Class: Gio::DBusMethodInvocation

Inherits:

Object

Object
Gio::DBusMethodInvocation

show all

Defined in:: (unknown)

Overview

Instances of the GDBus::MethodInvocation class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors.

The normal way to obtain a GDBus::MethodInvocation object is to receive it as an argument to the handle_method_call() function in a GDBus::InterfaceVTable that was passed to g_dbus_connection_register_object().

Instance Method Summary collapse

#connection ⇒ Gio::DBusConnection

Gets the GDBus::Connection the method was invoked on.
#interface_name ⇒ String

Gets the name of the D-Bus interface the method was invoked on.
#message ⇒ Gio::DBusMessage

Gets the GDBus::Message for the method invocation.
#method_info ⇒ Gio::DBusMethodInfo

Gets information about the method call, if any.
#method_name ⇒ String

Gets the name of the method that was invoked.
#object_path ⇒ String

Gets the object path the method was invoked on.
#parameters ⇒ GLib::Variant

Gets the parameters of the method invocation.
#property_info ⇒ Gio::DBusPropertyInfo

Gets information about the property that this method call is for, if any.
#return_dbus_error(error_name, error_message) ⇒ nil

Finishes handling a D-Bus method call by returning an error.
#return_error(domain, code, format, array) ⇒ nil

Finishes handling a D-Bus method call by returning an error.
#return_error_literal(domain, code, message) ⇒ nil

Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
#return_error_valist(domain, code, format, var_args) ⇒ nil

Like g_dbus_method_invocation_return_error() but intended for language bindings.
#return_gerror(error) ⇒ nil

Like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message.
#return_value(parameters) ⇒ nil

Finishes handling a D-Bus method call by returning parameters.
#return_value_with_unix_fd_list(parameters, fd_list) ⇒ nil

Like g_dbus_method_invocation_return_value() but also takes a GUnix::FDList.
#sender ⇒ String

Gets the bus name that invoked the method.
#take_error(error) ⇒ nil

Like g_dbus_method_invocation_return_gerror() but takes ownership of error so the caller does not need to free it.
#user_data ⇒ GObject

Gets the user_data #gpointer passed to g_dbus_connection_register_object().

Instance Method Details

#connection ⇒ `Gio::DBusConnection`

Gets the GDBus::Connection the method was invoked on.

Returns:

(Gio::DBusConnection) —

A GDBus::Connection. Do not free, it is owned by invocation.

#interface_name ⇒ `String`

Gets the name of the D-Bus interface the method was invoked on.

If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then “org.freedesktop.DBus.Properties” will be returned. See GDBus::InterfaceVTable for more information.

Returns:

(String) —

A string. Do not free, it is owned by invocation.

#message ⇒ `Gio::DBusMessage`

Gets the GDBus::Message for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the #GVariant API.

See this [server] and [client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Returns:

(Gio::DBusMessage) —

GDBus::Message. Do not free, it is owned by invocation.

#method_info ⇒ `Gio::DBusMethodInfo`

Gets information about the method call, if any.

If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then nil will be returned. See g_dbus_method_invocation_get_property_info() and GDBus::InterfaceVTable for more information.

Returns:

(Gio::DBusMethodInfo) —

A GDBus::MethodInfo or nil. Do not free, it is owned by invocation.

#method_name ⇒ `String`

Gets the name of the method that was invoked.

Returns:

(String) —

A string. Do not free, it is owned by invocation.

#object_path ⇒ `String`

Gets the object path the method was invoked on.

Returns:

(String) —

A string. Do not free, it is owned by invocation.

#parameters ⇒ `GLib::Variant`

Gets the parameters of the method invocation. If there are no input parameters then this will return a GVariant with 0 children rather than NULL.

Returns:

(GLib::Variant) —

A #GVariant tuple. Do not unref this because it is owned by invocation.

#property_info ⇒ `Gio::DBusPropertyInfo`

Gets information about the property that this method call is for, if any.

This will only be set in the case of an invocation in response to a property Get or Set call that has been directed to the method call handler for an object on account of its property_get() or property_set() vtable pointers being unset.

See GDBus::InterfaceVTable for more information.

If the call was GetAll, nil will be returned.

Returns:

(Gio::DBusPropertyInfo) —

a GDBus::PropertyInfo or nil

#return_dbus_error(error_name, error_message) ⇒ `nil`

Finishes handling a D-Bus method call by returning an error.

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Parameters:

error_name (String) —

A valid D-Bus error name.
error_message (String) —

A valid D-Bus error message.

Returns:

(nil)

#return_error(domain, code, format, array) ⇒ `nil`

Finishes handling a D-Bus method call by returning an error.

See g_dbus_error_encode_gerror() for details about what error name will be returned on the wire. In a nutshell, if the given error is registered using g_dbus_error_register_error() the name given during registration is used. Otherwise, a name of the form ‘org.gtk.GDBus.UnmappedGError.Quark…` is used. This provides transparent mapping of #GError between applications using GDBus.

If you are writing an application intended to be portable, always register errors with g_dbus_error_register_error() or use g_dbus_method_invocation_return_dbus_error().

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Since 2.48, if the method call requested for a reply not to be sent then this call will free invocation but otherwise do nothing (as per the recommendations of the D-Bus specification).

Parameters:

domain (GLib::Quark) —

A #GQuark for the #GError error domain.
code (Integer) —

The error code.
format (String) —

printf()-style format.
array (Array) —

Parameters for format.

Returns:

(nil)

#return_error_literal(domain, code, message) ⇒ `nil`

Like g_dbus_method_invocation_return_error() but without printf()-style formatting.

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Parameters:

domain (GLib::Quark) —

A #GQuark for the #GError error domain.
code (Integer) —

The error code.
message (String) —

The error message.

Returns:

(nil)

#return_error_valist(domain, code, format, var_args) ⇒ `nil`

Like g_dbus_method_invocation_return_error() but intended for language bindings.

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Parameters:

domain (GLib::Quark) —

A #GQuark for the #GError error domain.
code (Integer) —

The error code.
format (String) —

printf()-style format.
var_args (Gio::va_list) —

#va_list of parameters for format.

Returns:

(nil)

#return_gerror(error) ⇒ `nil`

Like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message.

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Parameters:

error (GLib::Error) —

A #GError.

Returns:

(nil)

#return_value(parameters) ⇒ `nil`

Finishes handling a D-Bus method call by returning parameters. If the parameters GVariant is floating, it is consumed.

It is an error if parameters is not of the right format: it must be a tuple containing the out-parameters of the D-Bus method. Even if the method has a single out-parameter, it must be contained in a tuple. If the method has no out-parameters, parameters may be nil or an empty tuple.

GDBusMethodInvocation *invocation = some_invocation;
g_autofree gchar *result_string = NULL;
g_autoptr (GError) error = NULL;

result_string = calculate_result (&error);

if (error != NULL)
  g_dbus_method_invocation_return_gerror (invocation, error);
else
  g_dbus_method_invocation_return_value (invocation,
                                         g_variant_new ("(s)", result_string));

// Do not free <b>invocation</b> here; returning a value does that

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Since 2.48, if the method call requested for a reply not to be sent then this call will sink parameters and free invocation, but otherwise do nothing (as per the recommendations of the D-Bus specification).

Parameters:

parameters (GLib::Variant) —

A #GVariant tuple with out parameters for the method or nil if not passing any parameters.

Returns:

(nil)

#return_value_with_unix_fd_list(parameters, fd_list) ⇒ `nil`

Like g_dbus_method_invocation_return_value() but also takes a GUnix::FDList.

This method is only available on UNIX.

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Parameters:

parameters (GLib::Variant) —

A #GVariant tuple with out parameters for the method or nil if not passing any parameters.
fd_list (Gio::UnixFDList) —

A GUnix::FDList or nil.

Returns:

(nil)

#sender ⇒ `String`

Gets the bus name that invoked the method.

Returns:

(String) —

A string. Do not free, it is owned by invocation.

#take_error(error) ⇒ `nil`

Like g_dbus_method_invocation_return_gerror() but takes ownership of error so the caller does not need to free it.

This method will take ownership of invocation. See GDBus::InterfaceVTable for more information about the ownership of invocation.

Parameters:

error (GLib::Error) —

A #GError.

Returns:

(nil)

#user_data ⇒ `GObject`

Gets the user_data #gpointer passed to g_dbus_connection_register_object().

Returns:

(GObject) —

A #gpointer.

Class: Gio::DBusMethodInvocation

Overview

Instance Method Summary collapse

Instance Method Details

#connection ⇒ Gio::DBusConnection

#interface_name ⇒ String

#message ⇒ Gio::DBusMessage

#method_info ⇒ Gio::DBusMethodInfo

#method_name ⇒ String

#object_path ⇒ String

#parameters ⇒ GLib::Variant

#property_info ⇒ Gio::DBusPropertyInfo

#return_dbus_error(error_name, error_message) ⇒ nil

#return_error(domain, code, format, array) ⇒ nil

#return_error_literal(domain, code, message) ⇒ nil

#return_error_valist(domain, code, format, var_args) ⇒ nil

#return_gerror(error) ⇒ nil

#return_value(parameters) ⇒ nil

#return_value_with_unix_fd_list(parameters, fd_list) ⇒ nil

#sender ⇒ String

#take_error(error) ⇒ nil

#user_data ⇒ GObject

#connection ⇒ `Gio::DBusConnection`

#interface_name ⇒ `String`

#message ⇒ `Gio::DBusMessage`

#method_info ⇒ `Gio::DBusMethodInfo`

#method_name ⇒ `String`

#object_path ⇒ `String`

#parameters ⇒ `GLib::Variant`

#property_info ⇒ `Gio::DBusPropertyInfo`

#return_dbus_error(error_name, error_message) ⇒ `nil`

#return_error(domain, code, format, array) ⇒ `nil`

#return_error_literal(domain, code, message) ⇒ `nil`

#return_error_valist(domain, code, format, var_args) ⇒ `nil`

#return_gerror(error) ⇒ `nil`

#return_value(parameters) ⇒ `nil`

#return_value_with_unix_fd_list(parameters, fd_list) ⇒ `nil`

#sender ⇒ `String`

#take_error(error) ⇒ `nil`

#user_data ⇒ `GObject`