GDBusMethodInvocation

## GDBusMethodInvocation GDBusMethodInvocation — Object for handling remote calls |

## Synopsis

    #include <gio/gio.h>

                        GDBusMethodInvocation;
    const gchar *       g_dbus_method_invocation_get_sender (GDBusMethodInvocation *invocation);
    const gchar *       g_dbus_method_invocation_get_object_path
                                                            (GDBusMethodInvocation *invocation);
    const gchar *       g_dbus_method_invocation_get_interface_name
                                                            (GDBusMethodInvocation *invocation);
    const gchar *       g_dbus_method_invocation_get_method_name
                                                            (GDBusMethodInvocation *invocation);
    const GDBusMethodInfo * g_dbus_method_invocation_get_method_info
                                                            (GDBusMethodInvocation *invocation);
    GDBusConnection *   g_dbus_method_invocation_get_connection
                                                            (GDBusMethodInvocation *invocation);
    GDBusMessage *      g_dbus_method_invocation_get_message
                                                            (GDBusMethodInvocation *invocation);
    GVariant *          g_dbus_method_invocation_get_parameters
                                                            (GDBusMethodInvocation *invocation);
    gpointer            g_dbus_method_invocation_get_user_data
                                                            (GDBusMethodInvocation *invocation);
    void                g_dbus_method_invocation_return_value
                                                            (GDBusMethodInvocation *invocation,
                                                             GVariant *parameters);
    void                g_dbus_method_invocation_return_error
                                                            (GDBusMethodInvocation *invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             ...);
    void                g_dbus_method_invocation_return_error_valist
                                                            (GDBusMethodInvocation *invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             va_list var_args);
    void                g_dbus_method_invocation_return_error_literal
                                                            (GDBusMethodInvocation *invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *message);
    void                g_dbus_method_invocation_return_gerror
                                                            (GDBusMethodInvocation *invocation,
                                                             const GError *error);
    void                g_dbus_method_invocation_return_dbus_error
                                                            (GDBusMethodInvocation *invocation,
                                                             const gchar *error_name,
                                                             const gchar *error_message);
    void                g_dbus_method_invocation_take_error (GDBusMethodInvocation *invocation,
                                                             GError *error);
    void                g_dbus_method_invocation_return_value_with_unix_fd_list
                                                            (GDBusMethodInvocation *invocation,
                                                             GVariant *parameters,
                                                             GUnixFDList *fd_list);

## Object Hierarchy

      GObject
       +----GDBusMethodInvocation

## 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()`.

## Details

### GDBusMethodInvocation

    typedef struct _GDBusMethodInvocation GDBusMethodInvocation;

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

Since 2.26

### g_dbus_method_invocation_get_sender ()

    const gchar *       g_dbus_method_invocation_get_sender (GDBusMethodInvocation *invocation);

Gets the bus name that invoked the method.

`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.

`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.

`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.

`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.

`invocation` : | A GDBusMethodInvocation.
Returns : | A GDBusMethodInfo or `NULL`. Do not free, it is owned by `invocation`.

Since 2.26

### g_dbus_method_invocation_get_connection ()

    GDBusConnection *   g_dbus_method_invocation_get_connection
                                                            (GDBusMethodInvocation *invocation);

Gets the GDBusConnection the method was invoked on.

`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 Example 6, “D-Bus server example” and Example 8, “D-Bus UNIX File Descriptor example” for an example of how to use this low-level API to send and receive UNIX file descriptors.

`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.

`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()`.

`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.

This method will free `invocation`, you cannot use it afterwards.

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

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 free `invocation`, you cannot use it afterwards.

`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 free `invocation`, you cannot use it afterwards.

`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 free `invocation`, you cannot use it afterwards.

`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 free `invocation`, you cannot use it afterwards.

`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 free `invocation`, you cannot use it afterwards.

`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 free `invocation`, you cannot use it afterwards.

`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 free `invocation`, you cannot use it afterwards.

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

Since 2.30