GDBusMethodInvocation: GIO Reference Manual

## GDBusMethodInvocation GDBusMethodInvocation — Object for handling remote calls |

## Functions

const gchar * | g_dbus_method_invocation_get_sender ()
const gchar * | g_dbus_method_invocation_get_object_path ()
const gchar * | g_dbus_method_invocation_get_interface_name ()
const gchar * | g_dbus_method_invocation_get_method_name ()
const GDBusMethodInfo * | g_dbus_method_invocation_get_method_info ()
const GDBusPropertyInfo * | g_dbus_method_invocation_get_property_info ()
GDBusConnection * | g_dbus_method_invocation_get_connection ()
GDBusMessage * | g_dbus_method_invocation_get_message ()
GVariant * | g_dbus_method_invocation_get_parameters ()
gpointer | g_dbus_method_invocation_get_user_data ()
void | g_dbus_method_invocation_return_value ()
void | g_dbus_method_invocation_return_error ()
void | g_dbus_method_invocation_return_error_valist ()
void | g_dbus_method_invocation_return_error_literal ()
void | g_dbus_method_invocation_return_gerror ()
void | g_dbus_method_invocation_return_dbus_error ()
void | g_dbus_method_invocation_take_error ()
void | g_dbus_method_invocation_return_value_with_unix_fd_list ()

## Types and Values

| GDBusMethodInvocation

## Object Hierarchy

        GObject
        ╰── GDBusMethodInvocation

## Includes

    #include <gio/gio.h>

## Description

Instances of the GDBusMethodInvocation 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 GDBusMethodInvocation object is to receive it as an argument to the `handle_method_call()` function in a GDBusInterfaceVTable that was passed to `g_dbus_connection_register_object()`.

## Functions

### g_dbus_method_invocation_get_sender ()

    const gchar *
    g_dbus_method_invocation_get_sender (GDBusMethodInvocation *invocation);

Gets the bus name that invoked the method.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

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

Since: 2.26

### g_dbus_method_invocation_get_object_path ()

    const gchar *
    g_dbus_method_invocation_get_object_path
                                   (GDBusMethodInvocation *invocation);

Gets the object path the method was invoked on.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

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

Since: 2.26

### g_dbus_method_invocation_get_interface_name ()

    const gchar *
    g_dbus_method_invocation_get_interface_name
                                   (GDBusMethodInvocation *invocation);

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 GDBusInterfaceVTable for more information.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

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

Since: 2.26

### g_dbus_method_invocation_get_method_name ()

    const gchar *
    g_dbus_method_invocation_get_method_name
                                   (GDBusMethodInvocation *invocation);

Gets the name of the method that was invoked.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

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

Since: 2.26

### g_dbus_method_invocation_get_method_info ()

    const GDBusMethodInfo *
    g_dbus_method_invocation_get_method_info
                                   (GDBusMethodInvocation *invocation);

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 `NULL` will be returned. See `g_dbus_method_invocation_get_property_info()` and GDBusInterfaceVTable for more information.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

A GDBusMethodInfo or `NULL`. Do not free, it is owned by `invocation` .

Since: 2.26

### g_dbus_method_invocation_get_property_info ()

    const GDBusPropertyInfo *
    g_dbus_method_invocation_get_property_info
                                   (GDBusMethodInvocation *invocation);

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 GDBusInterfaceVTable for more information.

If the call was GetAll, `NULL` will be returned.

#### Parameters

invocation | A GDBusMethodInvocation |

#### Returns

a GDBusPropertyInfo or `NULL`.

[transfer none]

Since: 2.38

### g_dbus_method_invocation_get_connection ()

    GDBusConnection *
    g_dbus_method_invocation_get_connection
                                   (GDBusMethodInvocation *invocation);

Gets the GDBusConnection the method was invoked on.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

A GDBusConnection. Do not free, it is owned by `invocation` .

[transfer none]

Since: 2.26

### g_dbus_method_invocation_get_message ()

    GDBusMessage *
    g_dbus_method_invocation_get_message (GDBusMethodInvocation *invocation);

Gets the GDBusMessage 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.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

GDBusMessage. Do not free, it is owned by `invocation` .

[transfer none]

Since: 2.26

### g_dbus_method_invocation_get_parameters ()

    GVariant *
    g_dbus_method_invocation_get_parameters
                                   (GDBusMethodInvocation *invocation);

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.

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

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

[transfer none]

Since: 2.26

### g_dbus_method_invocation_get_user_data ()

    gpointer
    g_dbus_method_invocation_get_user_data
                                   (GDBusMethodInvocation *invocation);

Gets the `user_data` gpointer passed to `g_dbus_connection_register_object()`.

[skip]

#### Parameters

invocation | A GDBusMethodInvocation. |

#### Returns

A gpointer.

Since: 2.26

### g_dbus_method_invocation_return_value ()

    void
    g_dbus_method_invocation_return_value (GDBusMethodInvocation *invocation,
                                           GVariant *parameters);

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 `NULL` or an empty tuple.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    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 @invocation here; returning a value does that *<!-- -->/

This method will take ownership of `invocation` . See GDBusInterfaceVTable 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

invocation | A GDBusMethodInvocation. | [transfer full]
parameters | A GVariant tuple with out parameters for the method or `NULL` if not passing any parameters. | [nullable]

Since: 2.26

### g_dbus_method_invocation_return_error ()

    void
    g_dbus_method_invocation_return_error (GDBusMethodInvocation *invocation,
                                           GQuark domain,
                                           gint code,
                                           const gchar *format,
                                           ...);

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 GDBusInterfaceVTable 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

invocation | A GDBusMethodInvocation. | [transfer full]
domain | A GQuark for the GError error domain. |
code | The error code. |
format | printf()-style format. |
... | Parameters for `format` . |

Since: 2.26

### g_dbus_method_invocation_return_error_valist ()

    void
    g_dbus_method_invocation_return_error_valist
                                   (GDBusMethodInvocation *invocation,
                                    GQuark domain,
                                    gint code,
                                    const gchar *format,
                                    va_list var_args);

Like `g_dbus_method_invocation_return_error()` but intended for language bindings.

This method will take ownership of `invocation` . See GDBusInterfaceVTable for more information about the ownership of `invocation` .

#### Parameters

invocation | A GDBusMethodInvocation. | [transfer full]
domain | A GQuark for the GError error domain. |
code | The error code. |
format | printf()-style format. |
var_args | va_list of parameters for `format` . |

Since: 2.26

### g_dbus_method_invocation_return_error_literal ()

    void
    g_dbus_method_invocation_return_error_literal
                                   (GDBusMethodInvocation *invocation,
                                    GQuark domain,
                                    gint code,
                                    const gchar *message);

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

This method will take ownership of `invocation` . See GDBusInterfaceVTable for more information about the ownership of `invocation` .

#### Parameters

invocation | A GDBusMethodInvocation. | [transfer full]
domain | A GQuark for the GError error domain. |
code | The error code. |
message | The error message. |

Since: 2.26

### g_dbus_method_invocation_return_gerror ()

    void
    g_dbus_method_invocation_return_gerror
                                   (GDBusMethodInvocation *invocation,
                                    const GError *error);

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 GDBusInterfaceVTable for more information about the ownership of `invocation` .

#### Parameters

invocation | A GDBusMethodInvocation. | [transfer full]
error | A GError. |

Since: 2.26

### g_dbus_method_invocation_return_dbus_error ()

    void
    g_dbus_method_invocation_return_dbus_error
                                   (GDBusMethodInvocation *invocation,
                                    const gchar *error_name,
                                    const gchar *error_message);

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

This method will take ownership of `invocation` . See GDBusInterfaceVTable for more information about the ownership of `invocation` .

#### Parameters

invocation | A GDBusMethodInvocation. | [transfer full]
error_name | A valid D-Bus error name. |
error_message | A valid D-Bus error message. |

Since: 2.26

### g_dbus_method_invocation_take_error ()

    void
    g_dbus_method_invocation_take_error (GDBusMethodInvocation *invocation,
                                         GError *error);

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 GDBusInterfaceVTable for more information about the ownership of `invocation` .

[skip]

#### Parameters

invocation | A GDBusMethodInvocation. | [transfer full]
error | A GError. | [transfer full]

Since: 2.30

### g_dbus_method_invocation_return_value_with_unix_fd_list ()

    void
    g_dbus_method_invocation_return_value_with_unix_fd_list
                                   (GDBusMethodInvocation *invocation,
                                    GVariant *parameters,
                                    GUnixFDList *fd_list);

Like `g_dbus_method_invocation_return_value()` but also takes a GUnixFDList.

This method is only available on UNIX.

This method will take ownership of `invocation` . See GDBusInterfaceVTable for more information about the ownership of `invocation` .

#### Parameters

invocation | A GDBusMethodInvocation. | [transfer full]
parameters | A GVariant tuple with out parameters for the method or `NULL` if not passing any parameters. | [nullable]
fd_list | A GUnixFDList or `NULL`. | [nullable]

Since: 2.30

## Types and Values

### GDBusMethodInvocation

    typedef struct _GDBusMethodInvocation GDBusMethodInvocation;

The GDBusMethodInvocation structure contains only private data and should only be accessed using the provided API.

Since: 2.26