## EggDBusMethodInvocation EggDBusMethodInvocation — Handling remote method calls |

## Synopsis

                        EggDBusMethodInvocation;
    EggDBusMethodInvocation * egg_dbus_method_invocation_new
                                                            (EggDBusMessage *request_message,
                                                             gpointer source_tag);
    gpointer            egg_dbus_method_invocation_get_source_tag
                                                            (EggDBusMethodInvocation *method_invocation);
    EggDBusMessage *    egg_dbus_method_invocation_create_reply_message
                                                            (EggDBusMethodInvocation *method_invocation);
    const gchar *       egg_dbus_method_invocation_get_caller
                                                            (EggDBusMethodInvocation *method_invocation);
    EggDBusConnection * egg_dbus_method_invocation_get_connection
                                                            (EggDBusMethodInvocation *method_invocation);
    void                egg_dbus_method_invocation_add_destroy_notify
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             gpointer data,
                                                             GDestroyNotify func);
    void                egg_dbus_method_invocation_return_error
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             ...);
    void                egg_dbus_method_invocation_return_error_valist
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             va_list var_args);
    void                egg_dbus_method_invocation_return_error_literal
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *message);
    void                egg_dbus_method_invocation_return_gerror
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GError *error);
    void                egg_dbus_method_invocation_return_dbus_error
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             const gchar *name,
                                                             const gchar *format,
                                                             ...);
    void                egg_dbus_method_invocation_return_dbus_error_valist
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             const gchar *name,
                                                             const gchar *format,
                                                             va_list var_args);
    void                egg_dbus_method_invocation_return_dbus_error_literal
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             const gchar *name,
                                                             const gchar *message);

## Object Hierarchy

      GObject
       +----EggDBusMethodInvocation

## Description

Instances of the EggDBusMethodInvocation class are used when handling D-Bus method calls. It provides a way to get information (such as the UNIX process identifier if applicable) about the remote end invoking the method. It also provides a mechanism to return errors.

## Details

### EggDBusMethodInvocation

    typedef struct _EggDBusMethodInvocation EggDBusMethodInvocation;

### egg_dbus_method_invocation_new ()

    EggDBusMethodInvocation * egg_dbus_method_invocation_new
                                                            (EggDBusMessage *request_message,
                                                             gpointer source_tag);

Creates a new EggDBusMethodInvocation. This method is only useful for language bindings.

`request_message` : | The message encapsulating the method call request.
`source_tag` : | An user provided tag.
Returns : | A EggDBusMethodInvocation. Free with `g_object_unref()`.

### egg_dbus_method_invocation_get_source_tag ()

    gpointer            egg_dbus_method_invocation_get_source_tag
                                                            (EggDBusMethodInvocation *method_invocation);

Gets the user provided tag for `method_invocation`. This method is only useful for language bindings.

`method_invocation` : | A EggDBusMethodInvocation.
Returns : | The user provided tag set when `method_invocation` was constructed.

### egg_dbus_method_invocation_create_reply_message ()

    EggDBusMessage *    egg_dbus_method_invocation_create_reply_message
                                                            (EggDBusMethodInvocation *method_invocation);

Creates a EggDBusMessage in reply to the EggDBusMessage passed when `method_invocation` was created. This method is only useful for language bindings.

`method_invocation` : | A EggDBusMethodInvocation.
Returns : | A new EggDBusMessage. Free with `g_object_unref()`.

### egg_dbus_method_invocation_get_caller ()

    const gchar *       egg_dbus_method_invocation_get_caller
                                                            (EggDBusMethodInvocation *method_invocation);

Gets the unique bus name of the caller of the method.

`method_invocation` : | A EggDBusMethodInvocation.
Returns : | The unique bus name of the caller. Do not free, the returned string is owned by `method_invocation`.

### egg_dbus_method_invocation_get_connection ()

    EggDBusConnection * egg_dbus_method_invocation_get_connection
                                                            (EggDBusMethodInvocation *method_invocation);

Gets the EggDBusConnection that `method_invocation` is associated with.

`method_invocation` : | A EggDBusMethodInvocation.
Returns : | A EggDBusConnection. Do not free, the returned object is owned by `method_invocation`.

### egg_dbus_method_invocation_add_destroy_notify ()

    void                egg_dbus_method_invocation_add_destroy_notify
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             gpointer data,
                                                             GDestroyNotify func);

Makes `method_invocation` call `func` with a a single parameter, `data`, upon finalization.

`method_invocation` : | A EggDBusMethodInvocation.
`data` : | Data to free.
`func` : | Free function.

### egg_dbus_method_invocation_return_error ()

    void                egg_dbus_method_invocation_return_error
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             ...);

Use this to return an error when handling a D-Bus method call. The error will be propagated to the remote caller.

This completes the method invocation and you don't have to call the corresponding ``_finish()`` method in your D-Bus method call handler.

`method_invocation` : | A EggDBusMethodInvocation.
`domain` : | Error domain.
`code` : | Error code.
`format` : | `printf()` style format for human readable message.
`...` : | Arguments for `format`.

### egg_dbus_method_invocation_return_error_valist ()

    void                egg_dbus_method_invocation_return_error_valist
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *format,
                                                             va_list var_args);

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

`method_invocation` : | A EggDBusMethodInvocation.
`domain` : | Error domain.
`code` : | Error code.
`format` : | `printf()` style format for human readable message.
`var_args` : | Arguments for `format`.

### egg_dbus_method_invocation_return_error_literal ()

    void                egg_dbus_method_invocation_return_error_literal
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GQuark domain,
                                                             gint code,
                                                             const gchar *message);

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

`method_invocation` : | A EggDBusMethodInvocation.
`domain` : | Error domain.
`code` : | Error code.
`message` : | Human readable error message.

### egg_dbus_method_invocation_return_gerror ()

    void                egg_dbus_method_invocation_return_gerror
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             GError *error);

Like `egg_dbus_method_invocation_return_error()` but takes a a GError instead.

`method_invocation` : | A EggDBusMethodInvocation.
`error` : | A GError.

### egg_dbus_method_invocation_return_dbus_error ()

    void                egg_dbus_method_invocation_return_dbus_error
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             const gchar *name,
                                                             const gchar *format,
                                                             ...);

Use this to return a raw D-Bus error when handling a D-Bus method call. The error will be propagated to the remote caller.

This completes the method invocation and you don't have to call the corresponding ``_finish()`` method in your D-Bus method call handler.

`method_invocation` : | A EggDBusMethodInvocation.
`name` : | A D-Bus error name such as `org.freedesktop.DBus.Error.UnknownMethod`.
`format` : | `printf()` style format for human readable message.
`...` : | Arguments for `format`.

### egg_dbus_method_invocation_return_dbus_error_valist ()

    void                egg_dbus_method_invocation_return_dbus_error_valist
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             const gchar *name,
                                                             const gchar *format,
                                                             va_list var_args);

Like `egg_dbus_method_invocation_return_dbus_error()` but intended for langauge bindings.

`method_invocation` : | A EggDBusMethodInvocation.
`name` : | A D-Bus error name such as `org.freedesktop.DBus.Error.UnknownMethod`.
`format` : | `printf()` style format for human readable message.
`var_args` : | Arguments for `format`.

### egg_dbus_method_invocation_return_dbus_error_literal ()

    void                egg_dbus_method_invocation_return_dbus_error_literal
                                                            (EggDBusMethodInvocation *method_invocation,
                                                             const gchar *name,
                                                             const gchar *message);

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

`method_invocation` : | A EggDBusMethodInvocation.
`name` : | A D-Bus error name such as `org.freedesktop.DBus.Error.UnknownMethod`.
`message` : | Human readable message to pass.