GDBusProxy

## GDBusProxy GDBusProxy — Client-side D-Bus interface proxy |

## Synopsis

    #include <gio/gio.h>

    enum                GDBusProxyFlags;
                        GDBusProxy;
    struct              GDBusProxyClass;
    void                g_dbus_proxy_new                    (GDBusConnection *connection,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDBusProxy *        g_dbus_proxy_new_finish             (GAsyncResult *res,
                                                             GError **error);
    GDBusProxy *        g_dbus_proxy_new_sync               (GDBusConnection *connection,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_dbus_proxy_new_for_bus            (GBusType bus_type,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDBusProxy *        g_dbus_proxy_new_for_bus_finish     (GAsyncResult *res,
                                                             GError **error);
    GDBusProxy *        g_dbus_proxy_new_for_bus_sync       (GBusType bus_type,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDBusProxyFlags     g_dbus_proxy_get_flags              (GDBusProxy *proxy);
    GDBusConnection *   g_dbus_proxy_get_connection         (GDBusProxy *proxy);
    const gchar *       g_dbus_proxy_get_name               (GDBusProxy *proxy);
    gchar *             g_dbus_proxy_get_name_owner         (GDBusProxy *proxy);
    const gchar *       g_dbus_proxy_get_object_path        (GDBusProxy *proxy);
    const gchar *       g_dbus_proxy_get_interface_name     (GDBusProxy *proxy);
    gint                g_dbus_proxy_get_default_timeout    (GDBusProxy *proxy);
    void                g_dbus_proxy_set_default_timeout    (GDBusProxy *proxy,
                                                             gint timeout_msec);
    GVariant *          g_dbus_proxy_get_cached_property    (GDBusProxy *proxy,
                                                             const gchar *property_name);
    void                g_dbus_proxy_set_cached_property    (GDBusProxy *proxy,
                                                             const gchar *property_name,
                                                             GVariant *value);
    gchar **            g_dbus_proxy_get_cached_property_names
                                                            (GDBusProxy *proxy);
    void                g_dbus_proxy_set_interface_info     (GDBusProxy *proxy,
                                                             GDBusInterfaceInfo *info);
    GDBusInterfaceInfo * g_dbus_proxy_get_interface_info    (GDBusProxy *proxy);
    void                g_dbus_proxy_call                   (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GVariant *          g_dbus_proxy_call_finish            (GDBusProxy *proxy,
                                                             GAsyncResult *res,
                                                             GError **error);
    GVariant *          g_dbus_proxy_call_sync              (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_dbus_proxy_call_with_unix_fd_list (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GUnixFDList *fd_list,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GVariant *          g_dbus_proxy_call_with_unix_fd_list_finish
                                                            (GDBusProxy *proxy,
                                                             GUnixFDList **out_fd_list,
                                                             GAsyncResult *res,
                                                             GError **error);
    GVariant *          g_dbus_proxy_call_with_unix_fd_list_sync
                                                            (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GUnixFDList *fd_list,
                                                             GUnixFDList **out_fd_list,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GFlags
       +----GDBusProxyFlags

      GObject
       +----GDBusProxy

## Implemented Interfaces

GDBusProxy implements GDBusInterface, GInitable and GAsyncInitable.

## Properties

      "g-bus-type"               GBusType              : Write / Construct Only
      "g-connection"             GDBusConnection*      : Read / Write / Construct Only
      "g-default-timeout"        gint                  : Read / Write / Construct
      "g-flags"                  GDBusProxyFlags       : Read / Write / Construct Only
      "g-interface-info"         GDBusInterfaceInfo*   : Read / Write
      "g-interface-name"         gchar*                : Read / Write / Construct Only
      "g-name"                   gchar*                : Read / Write / Construct Only
      "g-name-owner"             gchar*                : Read
      "g-object-path"            gchar*                : Read / Write / Construct Only

## Signals

      "g-properties-changed"                           : Run Last
      "g-signal"                                       : Run Last

## Description

GDBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A GDBusProxy can be constructed for both well-known and unique names.

By default, GDBusProxy will cache all properties (and listen to changes) of the remote object, and proxy all signals that gets emitted. This behaviour can be changed by passing suitable GDBusProxyFlags when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears.

If a GDBusProxy is used for a well-known name, the owner of the name is tracked and can be read from "g-name-owner". Connect to the "notify" signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set).

The generic "g-properties-changed" and "g-signal" signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass GDBusProxy, and have more natural properties and signals in your derived class. See the section called “Using gdbus-codegen” for how this can easily be done using the gdbus-codegen tool.

A GDBusProxy instance can be used from multiple threads but note that all signals (e.g. "g-signal", "g-properties-changed" and "notify") are emitted in the thread-default main loop of the thread where the instance was constructed.

Example 14. GDBusProxy for a well-known-name

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    #include <gio/gio.h>

    static gchar *opt_name         = NULL;
    static gchar *opt_object_path  = NULL;
    static gchar *opt_interface    = NULL;
    static gboolean opt_system_bus = FALSE;
    static gboolean opt_no_auto_start = FALSE;
    static gboolean opt_no_properties = FALSE;

    static GOptionEntry opt_entries[] =
    {
      { "name", 'n', 0, G_OPTION_ARG_STRING, &opt_name, "Name of the remote object to watch", NULL },
      { "object-path", 'o', 0, G_OPTION_ARG_STRING, &opt_object_path, "Object path of the remote object", NULL },
      { "interface", 'i', 0, G_OPTION_ARG_STRING, &opt_interface, "D-Bus interface of remote object", NULL },
      { "system-bus", 's', 0, G_OPTION_ARG_NONE, &opt_system_bus, "Use the system-bus instead of the session-bus", NULL },
      { "no-auto-start", 'a', 0, G_OPTION_ARG_NONE, &opt_no_auto_start, "Don't instruct the bus to launch an owner for the name", NULL},
      { "no-properties", 'p', 0, G_OPTION_ARG_NONE, &opt_no_properties, "Do not load properties", NULL},
      { NULL}
    };

    static GMainLoop *loop = NULL;

    static void
    print_properties (GDBusProxy *proxy)
    {
      gchar **property_names;
      guint n;

      g_print ("    properties:\n");

      property_names = g_dbus_proxy_get_cached_property_names (proxy);
      for (n = 0; property_names != NULL && property_names[n] != NULL; n++)
        {
          const gchar *key = property_names[n];
          GVariant *value;
          gchar *value_str;
          value = g_dbus_proxy_get_cached_property (proxy, key);
          value_str = g_variant_print (value, TRUE);
          g_print ("      %s -> %s\n", key, value_str);
          g_variant_unref (value);
          g_free (value_str);
        }
      g_strfreev (property_names);
    }

    static void
    on_properties_changed (GDBusProxy          *proxy,
                           GVariant            *changed_properties,
                           const gchar* const  *invalidated_properties,
                           gpointer             user_data)
    {
      /* Note that we are guaranteed that changed_properties and
       * invalidated_properties are never NULL
       */

      if (g_variant_n_children (changed_properties) > 0)
        {
          GVariantIter *iter;
          const gchar *key;
          GVariant *value;

          g_print (" *** Properties Changed:\n");
          g_variant_get (changed_properties,
                         "a{sv}",
                         &iter);
          while (g_variant_iter_loop (iter, "{&sv}", &key, &value))
            {
              gchar *value_str;
              value_str = g_variant_print (value, TRUE);
              g_print ("      %s -> %s\n", key, value_str);
              g_free (value_str);
            }
          g_variant_iter_free (iter);
        }

      if (g_strv_length ((GStrv) invalidated_properties) > 0)
        {
          guint n;
          g_print (" *** Properties Invalidated:\n");
          for (n = 0; invalidated_properties[n] != NULL; n++)
            {
              const gchar *key = invalidated_properties[n];
              g_print ("      %s\n", key);
            }
        }
    }

    static void
    on_signal (GDBusProxy *proxy,
               gchar      *sender_name,
               gchar      *signal_name,
               GVariant   *parameters,
               gpointer    user_data)
    {
      gchar *parameters_str;

      parameters_str = g_variant_print (parameters, TRUE);
      g_print (" *** Received Signal: %s: %s\n",
               signal_name,
               parameters_str);
      g_free (parameters_str);
    }

    static void
    print_proxy (GDBusProxy *proxy)
    {
      gchar *name_owner;

      name_owner = g_dbus_proxy_get_name_owner (proxy);
      if (name_owner != NULL)
        {
          g_print ("+++ Proxy object points to remote object owned by %s\n"
                   "    bus:          %s\n"
                   "    name:         %s\n"
                   "    object path:  %s\n"
                   "    interface:    %s\n",
                   name_owner,
                   opt_system_bus ? "System Bus" : "Session Bus",
                   opt_name,
                   opt_object_path,
                   opt_interface);
          print_properties (proxy);
        }
      else
        {
          g_print ("--- Proxy object is inert - there is no name owner for the name\n"
                   "    bus:          %s\n"
                   "    name:         %s\n"
                   "    object path:  %s\n"
                   "    interface:    %s\n",
                   opt_system_bus ? "System Bus" : "Session Bus",
                   opt_name,
                   opt_object_path,
                   opt_interface);
        }
      g_free (name_owner);
    }

    static void
    on_name_owner_notify (GObject    *object,
                          GParamSpec *pspec,
                          gpointer    user_data)
    {
      GDBusProxy *proxy = G_DBUS_PROXY (object);
      print_proxy (proxy);
    }

    int
    main (int argc, char *argv[])
    {
      GOptionContext *opt_context;
      GError *error;
      GDBusProxyFlags flags;
      GDBusProxy *proxy;

      loop = NULL;
      proxy = NULL;

      opt_context = g_option_context_new ("g_bus_watch_proxy() example");
      g_option_context_set_summary (opt_context,
                                    "Example: to watch the object of gdbus-example-server, use:\n"
                                    "\n"
                                    "  ./gdbus-example-watch-proxy -n org.gtk.GDBus.TestServer  \\\n"
                                    "                              -o /org/gtk/GDBus/TestObject \\\n"
                                    "                              -i org.gtk.GDBus.TestInterface");
      g_option_context_add_main_entries (opt_context, opt_entries, NULL);
      error = NULL;
      if (!g_option_context_parse (opt_context, &argc, &argv, &error))
        {
          g_printerr ("Error parsing options: %s\n", error->message);
          goto out;
        }
      if (opt_name == NULL || opt_object_path == NULL || opt_interface == NULL)
        {
          g_printerr ("Incorrect usage, try --help.\n");
          goto out;
        }

      flags = G_DBUS_PROXY_FLAGS_NONE;
      if (opt_no_properties)
        flags |= G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES;
      if (opt_no_auto_start)
        flags |= G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START;

      loop = g_main_loop_new (NULL, FALSE);

      error = NULL;
      proxy = g_dbus_proxy_new_for_bus_sync (opt_system_bus ? G_BUS_TYPE_SYSTEM : G_BUS_TYPE_SESSION,
                                             flags,
                                             NULL, /* GDBusInterfaceInfo */
                                             opt_name,
                                             opt_object_path,
                                             opt_interface,
                                             NULL, /* GCancellable */
                                             &error);
      if (proxy == NULL)
        {
          g_printerr ("Error creating proxy: %s\n", error->message);
          g_error_free (error);
          goto out;
        }

      g_signal_connect (proxy,
                        "g-properties-changed",
                        G_CALLBACK (on_properties_changed),
                        NULL);
      g_signal_connect (proxy,
                        "g-signal",
                        G_CALLBACK (on_signal),
                        NULL);
      g_signal_connect (proxy,
                        "notify::g-name-owner",
                        G_CALLBACK (on_name_owner_notify),
                        NULL);
      print_proxy (proxy);

      g_main_loop_run (loop);

     out:
      if (proxy != NULL)
        g_object_unref (proxy);
      if (loop != NULL)
        g_main_loop_unref (loop);
      g_option_context_free (opt_context);
      g_free (opt_name);
      g_free (opt_object_path);
      g_free (opt_interface);

      return 0;
    }

## Details

### enum GDBusProxyFlags

    typedef enum {
      G_DBUS_PROXY_FLAGS_NONE = 0,
      G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES = (1<<0),
      G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS = (1<<1),
      G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START = (1<<2),
      G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES = (1<<3)
    } GDBusProxyFlags;

Flags used when constructing an instance of a GDBusProxy derived class.

`G_DBUS_PROXY_FLAGS_NONE` | No flags set.
`G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` | Don't load properties.
`G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS` | Don't connect to signals on the remote object.
`G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` | If not set and the proxy if for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in proxies for well-known names.
`G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES` | If set, the property value for any invalidated property will be (asynchronously) retrieved upon receiving the PropertiesChanged D-Bus signal and the property will not cause emission of the "g-properties-changed" signal. When the value is received the "g-properties-changed" signal is emitted for the property along with the retrieved value. Since 2.32.

Since 2.26

### GDBusProxy

    typedef struct _GDBusProxy GDBusProxy;

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

Since 2.26

### struct GDBusProxyClass

    struct GDBusProxyClass {
      /* Signals */
      void (*g_properties_changed) (GDBusProxy          *proxy,
                                    GVariant            *changed_properties,
                                    const gchar* const  *invalidated_properties);
      void (*g_signal)             (GDBusProxy          *proxy,
                                    const gchar         *sender_name,
                                    const gchar         *signal_name,
                                    GVariant            *parameters);
    };

Class structure for GDBusProxy.

`g_properties_changed` () | Signal class handler for the "g-properties-changed" signal.
`g_signal` () | Signal class handler for the "g-signal" signal.

Since 2.26

### g_dbus_proxy_new ()

    void                g_dbus_proxy_new                    (GDBusConnection *connection,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Creates a proxy for accessing `interface_name` on the remote object at `object_path` owned by `name` at `connection` and asynchronously loads D-Bus properties unless the `G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` flag is used. Connect to the "g-properties-changed" signal to get notified about property changes.

If the `G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS` flag is not set, also sets up match rules for signals. Connect to the "g-signal" signal to handle signals from the remote object.

If `name` is a well-known name and the `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` flag isn't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, `callback` will be invoked and you can use `g_dbus_proxy_new_finish()` to get the result.

See `g_dbus_proxy_new_sync()` and for a synchronous version of this constructor.

See Example 14, “GDBusProxy for a well-known-name” for an example of how GDBusProxy can be used.

`connection` : | A GDBusConnection.
`flags` : | Flags used when constructing the proxy.
`info` : | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. [allow-none]
`name` : | A bus name (well-known or unique) or `NULL` if `connection` is not a message bus connection. [allow-none]
`object_path` : | An object path.
`interface_name` : | A D-Bus interface name.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | Callback function to invoke when the proxy is ready.
`user_data` : | User data to pass to `callback`.

Since 2.26

### g_dbus_proxy_new_finish ()

    GDBusProxy *        g_dbus_proxy_new_finish             (GAsyncResult *res,
                                                             GError **error);

Finishes creating a GDBusProxy.

`res` : | A GAsyncResult obtained from the GAsyncReadyCallback function passed to `g_dbus_proxy_new()`.
`error` : | Return location for error or `NULL`.
Returns : | A GDBusProxy or `NULL` if `error` is set. Free with `g_object_unref()`.

Since 2.26

### g_dbus_proxy_new_sync ()

    GDBusProxy *        g_dbus_proxy_new_sync               (GDBusConnection *connection,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Creates a proxy for accessing `interface_name` on the remote object at `object_path` owned by `name` at `connection` and synchronously loads D-Bus properties unless the `G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` flag is used.

If the `G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS` flag is not set, also sets up match rules for signals. Connect to the "g-signal" signal to handle signals from the remote object.

If `name` is a well-known name and the `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` flag isn't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See `g_dbus_proxy_new()` and `g_dbus_proxy_new_finish()` for the asynchronous version.

See Example 14, “GDBusProxy for a well-known-name” for an example of how GDBusProxy can be used.

`connection` : | A GDBusConnection.
`flags` : | Flags used when constructing the proxy.
`info` : | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. [allow-none]
`name` : | A bus name (well-known or unique) or `NULL` if `connection` is not a message bus connection. [allow-none]
`object_path` : | An object path.
`interface_name` : | A D-Bus interface name.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`. [allow-none]
Returns : | A GDBusProxy or `NULL` if error is set. Free with `g_object_unref()`.

Since 2.26

### g_dbus_proxy_new_for_bus ()

    void                g_dbus_proxy_new_for_bus            (GBusType bus_type,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Like `g_dbus_proxy_new()` but takes a GBusType instead of a GDBusConnection.

See Example 14, “GDBusProxy for a well-known-name” for an example of how GDBusProxy can be used.

`bus_type` : | A GBusType.
`flags` : | Flags used when constructing the proxy.
`info` : | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. [allow-none]
`name` : | A bus name (well-known or unique).
`object_path` : | An object path.
`interface_name` : | A D-Bus interface name.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | Callback function to invoke when the proxy is ready.
`user_data` : | User data to pass to `callback`.

Since 2.26

### g_dbus_proxy_new_for_bus_finish ()

    GDBusProxy *        g_dbus_proxy_new_for_bus_finish     (GAsyncResult *res,
                                                             GError **error);

Finishes creating a GDBusProxy.

`res` : | A GAsyncResult obtained from the GAsyncReadyCallback function passed to `g_dbus_proxy_new_for_bus()`.
`error` : | Return location for error or `NULL`.
Returns : | A GDBusProxy or `NULL` if `error` is set. Free with `g_object_unref()`.

Since 2.26

### g_dbus_proxy_new_for_bus_sync ()

    GDBusProxy *        g_dbus_proxy_new_for_bus_sync       (GBusType bus_type,
                                                             GDBusProxyFlags flags,
                                                             GDBusInterfaceInfo *info,
                                                             const gchar *name,
                                                             const gchar *object_path,
                                                             const gchar *interface_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Like `g_dbus_proxy_new_sync()` but takes a GBusType instead of a GDBusConnection.

See Example 14, “GDBusProxy for a well-known-name” for an example of how GDBusProxy can be used.

`bus_type` : | A GBusType.
`flags` : | Flags used when constructing the proxy.
`info` : | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. [allow-none]
`name` : | A bus name (well-known or unique).
`object_path` : | An object path.
`interface_name` : | A D-Bus interface name.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | A GDBusProxy or `NULL` if error is set. Free with `g_object_unref()`.

Since 2.26

### g_dbus_proxy_get_flags ()

    GDBusProxyFlags     g_dbus_proxy_get_flags              (GDBusProxy *proxy);

Gets the flags that `proxy` was constructed with.

`proxy` : | A GDBusProxy.
Returns : | Flags from the GDBusProxyFlags enumeration.

Since 2.26

### g_dbus_proxy_get_connection ()

    GDBusConnection *   g_dbus_proxy_get_connection         (GDBusProxy *proxy);

Gets the connection `proxy` is for.

`proxy` : | A GDBusProxy.
Returns : | A GDBusConnection owned by `proxy`. Do not free. [transfer none]

Since 2.26

### g_dbus_proxy_get_name ()

    const gchar *       g_dbus_proxy_get_name               (GDBusProxy *proxy);

Gets the name that `proxy` was constructed for.

`proxy` : | A GDBusProxy.
Returns : | A string owned by `proxy`. Do not free.

Since 2.26

### g_dbus_proxy_get_name_owner ()

    gchar *             g_dbus_proxy_get_name_owner         (GDBusProxy *proxy);

The unique name that owns the name that `proxy` is for or `NULL` if no-one currently owns that name. You may connect to the "notify" signal to track changes to the "g-name-owner" property.

`proxy` : | A GDBusProxy.
Returns : | The name owner or `NULL` if no name owner exists. Free with `g_free()`.

Since 2.26

### g_dbus_proxy_get_object_path ()

    const gchar *       g_dbus_proxy_get_object_path        (GDBusProxy *proxy);

Gets the object path `proxy` is for.

`proxy` : | A GDBusProxy.
Returns : | A string owned by `proxy`. Do not free.

Since 2.26

### g_dbus_proxy_get_interface_name ()

    const gchar *       g_dbus_proxy_get_interface_name     (GDBusProxy *proxy);

Gets the D-Bus interface name `proxy` is for.

`proxy` : | A GDBusProxy.
Returns : | A string owned by `proxy`. Do not free.

Since 2.26

### g_dbus_proxy_get_default_timeout ()

    gint                g_dbus_proxy_get_default_timeout    (GDBusProxy *proxy);

Gets the timeout to use if -1 (specifying default timeout) is passed as `timeout_msec` in the `g_dbus_proxy_call()` and `g_dbus_proxy_call_sync()` functions.

See the "g-default-timeout" property for more details.

`proxy` : | A GDBusProxy.
Returns : | Timeout to use for `proxy`.

Since 2.26

### g_dbus_proxy_set_default_timeout ()

    void                g_dbus_proxy_set_default_timeout    (GDBusProxy *proxy,
                                                             gint timeout_msec);

Sets the timeout to use if -1 (specifying default timeout) is passed as `timeout_msec` in the `g_dbus_proxy_call()` and `g_dbus_proxy_call_sync()` functions.

See the "g-default-timeout" property for more details.

`proxy` : | A GDBusProxy.
`timeout_msec` : | Timeout in milliseconds.

Since 2.26

### g_dbus_proxy_get_cached_property ()

    GVariant *          g_dbus_proxy_get_cached_property    (GDBusProxy *proxy,
                                                             const gchar *property_name);

Looks up the value for a property from the cache. This call does no blocking IO.

If `proxy` has an expected interface (see "g-interface-info") and `property_name` is referenced by it, then `value` is checked against the type of the property.

`proxy` : | A GDBusProxy.
`property_name` : | Property name.
Returns : | A reference to the GVariant instance that holds the value for `property_name` or `NULL` if the value is not in the cache. The returned reference must be freed with `g_variant_unref()`.

Since 2.26

### g_dbus_proxy_set_cached_property ()

    void                g_dbus_proxy_set_cached_property    (GDBusProxy *proxy,
                                                             const gchar *property_name,
                                                             GVariant *value);

If `value` is not `NULL`, sets the cached value for the property with name `property_name` to the value in `value`.

If `value` is `NULL`, then the cached value is removed from the property cache.

If `proxy` has an expected interface (see "g-interface-info") and `property_name` is referenced by it, then `value` is checked against the type of the property.

If the `value` GVariant is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.

    1
    2
    3
    4
    5
    g_dbus_proxy_set_cached_property (proxy,
                                      "SomeProperty",
                                      g_variant_new ("(si)",
                                                    "A String",
                                                    42));

Normally you will not need to use this method since `proxy` is tracking changes using the `org.freedesktop.DBus.Properties.PropertiesChanged` D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property `ChatroomParticipants` which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals `ChatroomParticipantJoined(String name)` and `ChatroomParticipantParted(String name)`.

`proxy` : | A GDBusProxy
`property_name` : | Property name.
`value` : | Value for the property or `NULL` to remove it from the cache. [allow-none]

Since 2.26

### g_dbus_proxy_get_cached_property_names ()

    gchar **            g_dbus_proxy_get_cached_property_names
                                                            (GDBusProxy *proxy);

Gets the names of all cached properties on `proxy`.

`proxy` : | A GDBusProxy.
Returns : | A `NULL`-terminated array of strings or `NULL` if `proxy` has no cached properties. Free the returned array with `g_strfreev()`. [transfer full]

Since 2.26

### g_dbus_proxy_set_interface_info ()

    void                g_dbus_proxy_set_interface_info     (GDBusProxy *proxy,
                                                             GDBusInterfaceInfo *info);

Ensure that interactions with `proxy` conform to the given interface. See the "g-interface-info" property for more details.

`proxy` : | A GDBusProxy
`info` : | Minimum interface this proxy conforms to or `NULL` to unset. [allow-none]

Since 2.26

### g_dbus_proxy_get_interface_info ()

    GDBusInterfaceInfo * g_dbus_proxy_get_interface_info    (GDBusProxy *proxy);

Returns the GDBusInterfaceInfo, if any, specifying the interface that `proxy` conforms to. See the "g-interface-info" property for more details.

`proxy` : | A GDBusProxy
Returns : | A GDBusInterfaceInfo or `NULL`. Do not unref the returned object, it is owned by `proxy`.

Since 2.26

### g_dbus_proxy_call ()

    void                g_dbus_proxy_call                   (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously invokes the `method_name` method on `proxy`.

If `method_name` contains any dots, then `name` is split into interface and method name parts. This allows using `proxy` for invoking methods on other interfaces.

If the GDBusConnection associated with `proxy` is closed then the operation will fail with `G_IO_ERROR_CLOSED`. If `cancellable` is canceled, the operation will fail with `G_IO_ERROR_CANCELLED`. If `parameters` contains a value not compatible with the D-Bus protocol, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

If the `parameters` GVariant is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    g_dbus_proxy_call (proxy,
                       "TwoStrings",
                       g_variant_new ("(ss)",
                                      "Thing One",
                                      "Thing Two"),
                       G_DBUS_CALL_FLAGS_NONE,
                       -1,
                       NULL,
                       (GAsyncReadyCallback) two_strings_done,
                       &data);

If `proxy` has an expected interface (see "g-interface-info") and `method_name` is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `g_dbus_proxy_call_finish()` to get the result of the operation. See `g_dbus_proxy_call_sync()` for the synchronous version of this method.

If `callback` is `NULL` then the D-Bus method call message will be sent with the `G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED` flag set.

`proxy` : | A GDBusProxy.
`method_name` : | Name of method to invoke.
`parameters` : | A GVariant tuple with parameters for the signal or `NULL` if not passing parameters. [allow-none]
`flags` : | Flags from the GDBusCallFlags enumeration.
`timeout_msec` : | The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result of the method invocation. [allow-none]
`user_data` : | The data to pass to `callback`.

Since 2.26

### g_dbus_proxy_call_finish ()

    GVariant *          g_dbus_proxy_call_finish            (GDBusProxy *proxy,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `g_dbus_proxy_call()`.

`proxy` : | A GDBusProxy.
`res` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_proxy_call()`.
`error` : | Return location for error or `NULL`.
Returns : | `NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since 2.26

### g_dbus_proxy_call_sync ()

    GVariant *          g_dbus_proxy_call_sync              (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GCancellable *cancellable,
                                                             GError **error);

Synchronously invokes the `method_name` method on `proxy`.

If `method_name` contains any dots, then `name` is split into interface and method name parts. This allows using `proxy` for invoking methods on other interfaces.

If the GDBusConnection associated with `proxy` is disconnected then the operation will fail with `G_IO_ERROR_CLOSED`. If `cancellable` is canceled, the operation will fail with `G_IO_ERROR_CANCELLED`. If `parameters` contains a value not compatible with the D-Bus protocol, the operation fails with `G_IO_ERROR_INVALID_ARGUMENT`.

If the `parameters` GVariant is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    g_dbus_proxy_call_sync (proxy,
                            "TwoStrings",
                            g_variant_new ("(ss)",
                                           "Thing One",
                                           "Thing Two"),
                            G_DBUS_CALL_FLAGS_NONE,
                            -1,
                            NULL,
                            &error);

The calling thread is blocked until a reply is received. See `g_dbus_proxy_call()` for the asynchronous version of this method.

If `proxy` has an expected interface (see "g-interface-info") and `method_name` is referenced by it, then the return value is checked against the return type.

`proxy` : | A GDBusProxy.
`method_name` : | Name of method to invoke.
`parameters` : | A GVariant tuple with parameters for the signal or `NULL` if not passing parameters. [allow-none]
`flags` : | Flags from the GDBusCallFlags enumeration.
`timeout_msec` : | The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since 2.26

### g_dbus_proxy_call_with_unix_fd_list ()

    void                g_dbus_proxy_call_with_unix_fd_list (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GUnixFDList *fd_list,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Like `g_dbus_proxy_call()` but also takes a GUnixFDList object.

This method is only available on UNIX.

`proxy` : | A GDBusProxy.
`method_name` : | Name of method to invoke.
`parameters` : | A GVariant tuple with parameters for the signal or `NULL` if not passing parameters. [allow-none]
`flags` : | Flags from the GDBusCallFlags enumeration.
`timeout_msec` : | The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
`fd_list` : | A GUnixFDList or `NULL`. [allow-none]
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result of the method invocation. [allow-none]
`user_data` : | The data to pass to `callback`.

Since 2.30

### g_dbus_proxy_call_with_unix_fd_list_finish ()

    GVariant *          g_dbus_proxy_call_with_unix_fd_list_finish
                                                            (GDBusProxy *proxy,
                                                             GUnixFDList **out_fd_list,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `g_dbus_proxy_call_with_unix_fd_list()`.

`proxy` : | A GDBusProxy.
`out_fd_list` : | Return location for a GUnixFDList or `NULL`. [out][allow-none]
`res` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `g_dbus_proxy_call_with_unix_fd_list()`.
`error` : | Return location for error or `NULL`.
Returns : | `NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since 2.30

### g_dbus_proxy_call_with_unix_fd_list_sync ()

    GVariant *          g_dbus_proxy_call_with_unix_fd_list_sync
                                                            (GDBusProxy *proxy,
                                                             const gchar *method_name,
                                                             GVariant *parameters,
                                                             GDBusCallFlags flags,
                                                             gint timeout_msec,
                                                             GUnixFDList *fd_list,
                                                             GUnixFDList **out_fd_list,
                                                             GCancellable *cancellable,
                                                             GError **error);

Like `g_dbus_proxy_call_sync()` but also takes and returns GUnixFDList objects.

This method is only available on UNIX.

`proxy` : | A GDBusProxy.
`method_name` : | Name of method to invoke.
`parameters` : | A GVariant tuple with parameters for the signal or `NULL` if not passing parameters. [allow-none]
`flags` : | Flags from the GDBusCallFlags enumeration.
`timeout_msec` : | The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
`fd_list` : | A GUnixFDList or `NULL`. [allow-none]
`out_fd_list` : | Return location for a GUnixFDList or `NULL`. [out][allow-none]
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `NULL` if `error` is set. Otherwise a GVariant tuple with return values. Free with `g_variant_unref()`.

Since 2.30

## Property Details

### The `"g-bus-type"` property

      "g-bus-type"               GBusType              : Write / Construct Only

If this property is not `G_BUS_TYPE_NONE`, then "g-connection" must be `NULL` and will be set to the GDBusConnection obtained by calling `g_bus_get()` with the value of this property.

Default value: G_BUS_TYPE_NONE

Since 2.26

### The `"g-connection"` property

      "g-connection"             GDBusConnection*      : Read / Write / Construct Only

The GDBusConnection the proxy is for.

Since 2.26

### The `"g-default-timeout"` property

      "g-default-timeout"        gint                  : Read / Write / Construct

The timeout to use if -1 (specifying default timeout) is passed as `timeout_msec` in the `g_dbus_proxy_call()` and `g_dbus_proxy_call_sync()` functions.

This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to `G_MAXINT`, then no timeout is used.

Allowed values: >= -1

Default value: -1

Since 2.26

### The `"g-flags"` property

      "g-flags"                  GDBusProxyFlags       : Read / Write / Construct Only

Flags from the GDBusProxyFlags enumeration.

Since 2.26

### The `"g-interface-info"` property

      "g-interface-info"         GDBusInterfaceInfo*   : Read / Write

Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given GDBusInterfaceInfo is said to be the expected interface.

The checks performed are:

- When completing a method call, if the type signature of the reply message isn't what's expected, the reply is discarded and the GError is set to `G_IO_ERROR_INVALID_ARGUMENT`.

- Received signals that have a type signature mismatch are dropped and a warning is logged via `g_warning()`.

- Properties received via the initial ``GetAll()`` call or via the `::PropertiesChanged` signal (on the org.freedesktop.DBus.Properties interface) or set using `g_dbus_proxy_set_cached_property()` with a type signature mismatch are ignored and a warning is logged via `g_warning()`.

Note that these checks are never done on methods, signals and properties that are not referenced in the given GDBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

Since 2.26

### The `"g-interface-name"` property

      "g-interface-name"         gchar*                : Read / Write / Construct Only

The D-Bus interface name the proxy is for.

Default value: NULL

Since 2.26

### The `"g-name"` property

      "g-name"                   gchar*                : Read / Write / Construct Only

The well-known or unique name that the proxy is for.

Default value: NULL

Since 2.26

### The `"g-name-owner"` property

      "g-name-owner"             gchar*                : Read

The unique name that owns "g-name" or `NULL` if no-one currently owns that name. You may connect to "notify" signal to track changes to this property.

Default value: NULL

Since 2.26

### The `"g-object-path"` property

      "g-object-path"            gchar*                : Read / Write / Construct Only

The object path the proxy is for.

Default value: NULL

Since 2.26

## Signal Details

### The `"g-properties-changed"` signal

    void                user_function                      (GDBusProxy *proxy,
                                                            GVariant   *changed_properties,
                                                            GStrv       invalidated_properties,
                                                            gpointer    user_data)                   : Run Last

Emitted when one or more D-Bus properties on `proxy` changes. The local cache has already been updated when this signal fires. Note that both `changed_properties` and `invalidated_properties` are guaranteed to never be `NULL` (either may be empty though).

If the proxy has the flag `G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES` set, then `invalidated_properties` will always be empty.

This signal corresponds to the `PropertiesChanged` D-Bus signal on the `org.freedesktop.DBus.Properties` interface.

`proxy` : | The GDBusProxy emitting the signal.
`changed_properties` : | A GVariant containing the properties that changed
`invalidated_properties` : | A `NULL` terminated array of properties that was invalidated
`user_data` : | user data set when the signal handler was connected.

Since 2.26

### The `"g-signal"` signal

    void                user_function                      (GDBusProxy *proxy,
                                                            gchar      *sender_name,
                                                            gchar      *signal_name,
                                                            GVariant   *parameters,
                                                            gpointer    user_data)        : Run Last

Emitted when a signal from the remote object and interface that `proxy` is for, has been received.

`proxy` : | The GDBusProxy emitting the signal.
`sender_name` : | The sender of the signal or `NULL` if the connection is not a bus connection. [allow-none]
`signal_name` : | The name of the signal.
`parameters` : | A GVariant tuple with parameters for the signal.
`user_data` : | user data set when the signal handler was connected.

Since 2.26