GDBusProxy: GIO Reference Manual

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

## Functions

void | g_dbus_proxy_new ()
GDBusProxy * | g_dbus_proxy_new_finish ()
GDBusProxy * | g_dbus_proxy_new_sync ()
void | g_dbus_proxy_new_for_bus ()
GDBusProxy * | g_dbus_proxy_new_for_bus_finish ()
GDBusProxy * | g_dbus_proxy_new_for_bus_sync ()
GDBusProxyFlags | g_dbus_proxy_get_flags ()
GDBusConnection * | g_dbus_proxy_get_connection ()
const gchar * | g_dbus_proxy_get_name ()
gchar * | g_dbus_proxy_get_name_owner ()
const gchar * | g_dbus_proxy_get_object_path ()
const gchar * | g_dbus_proxy_get_interface_name ()
gint | g_dbus_proxy_get_default_timeout ()
void | g_dbus_proxy_set_default_timeout ()
GVariant * | g_dbus_proxy_get_cached_property ()
void | g_dbus_proxy_set_cached_property ()
gchar ** | g_dbus_proxy_get_cached_property_names ()
void | g_dbus_proxy_set_interface_info ()
GDBusInterfaceInfo * | g_dbus_proxy_get_interface_info ()
void | g_dbus_proxy_call ()
GVariant * | g_dbus_proxy_call_finish ()
GVariant * | g_dbus_proxy_call_sync ()
void | g_dbus_proxy_call_with_unix_fd_list ()
GVariant * | g_dbus_proxy_call_with_unix_fd_list_finish ()
GVariant * | g_dbus_proxy_call_with_unix_fd_list_sync ()

## Properties

GBusType | g-bus-type | Write / Construct Only
GDBusConnection * | g-connection | Read / Write / Construct Only
int | g-default-timeout | Read / Write / Construct
GDBusProxyFlags | g-flags | Read / Write / Construct Only
GDBusInterfaceInfo * | g-interface-info | Read / Write
char * | g-interface-name | Read / Write / Construct Only
char * | g-name | Read / Write / Construct Only
char * | g-name-owner | Read
char * | g-object-path | Read / Write / Construct Only

## Signals

void | g-properties-changed | Run Last
void | g-signal | Has Details

## Types and Values

enum | GDBusProxyFlags
| GDBusProxy
struct | GDBusProxyClass

## Object Hierarchy

        GFlags
        ╰── GDBusProxyFlags
        GObject
        ╰── GDBusProxy

## Implemented Interfaces

GDBusProxy implements GDBusInterface, GInitable and GAsyncInitable.

## Includes

    #include <gio/gio.h>

## 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 get 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.

The unique name owner of the proxy's 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).

If the proxy is for a stateless D-Bus service, where the name owner may be started and stopped between calls, the “g-name-owner” tracking of GDBusProxy will cause the proxy to drop signal and property changes from the service after it has restarted for the first time. When interacting with a stateless D-Bus service, do not use GDBusProxy — use direct D-Bus method calls and signal connections.

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. This example shows 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 context of the thread where the instance was constructed.

An example using a proxy for a well-known name can be found in gdbus-example-watch-proxy.c

## Functions

### 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 both `G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` and `G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS` are set, this constructor is guaranteed to complete immediately without blocking.

If `name` is a well-known name and the `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` and `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION` flags aren'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.

GDBusProxy is used in this example.

#### Parameters

connection | A GDBusConnection. |
flags | Flags used when constructing the proxy. |
info | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. | [nullable]
name | A bus name (well-known or unique) or `NULL` if `connection` is not a message bus connection. | [nullable]
object_path | An object path. |
interface_name | A D-Bus interface name. |
cancellable | A GCancellable or `NULL`. | [nullable]
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.

#### Parameters

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

[transfer full]

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 both `G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES` and `G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS` are set, this constructor is guaranteed to return immediately without blocking.

If `name` is a well-known name and the `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` and `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION` flags aren'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.

GDBusProxy is used in this example.

#### Parameters

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

#### Returns

A GDBusProxy or `NULL` if error is set. Free with `g_object_unref()`.

[transfer full]

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.

GDBusProxy is used in this example.

#### Parameters

bus_type | A GBusType. |
flags | Flags used when constructing the proxy. |
info | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. | [nullable]
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`. | [nullable]
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.

#### Parameters

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

[transfer full]

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.

GDBusProxy is used in this example.

#### Parameters

bus_type | A GBusType. |
flags | Flags used when constructing the proxy. |
info | A GDBusInterfaceInfo specifying the minimal interface that `proxy` conforms to or `NULL`. | [nullable]
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`. | [nullable]
error | Return location for error or `NULL`. |

#### Returns

A GDBusProxy or `NULL` if error is set. Free with `g_object_unref()`.

[transfer full]

Since: 2.26

### g_dbus_proxy_get_flags ()

    GDBusProxyFlags
    g_dbus_proxy_get_flags (GDBusProxy *proxy);

Gets the flags that `proxy` was constructed with.

#### Parameters

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.

#### Parameters

proxy | A GDBusProxy. |

#### Returns

A GDBusConnection owned by `proxy` . Do not free.

[transfer none][not nullable]

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.

When connected to a message bus, this will usually be non-`NULL`. However, it may be `NULL` for a proxy that communicates using a peer-to-peer pattern.

#### Parameters

proxy | A GDBusProxy. |

#### Returns

A string owned by `proxy` . Do not free.

[nullable]

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.

#### Parameters

proxy | A GDBusProxy. |

#### Returns

The name owner or `NULL` if no name owner exists. Free with `g_free()`.

[transfer full][nullable]

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.

#### Parameters

proxy | A GDBusProxy. |

#### Returns

A string owned by `proxy` . Do not free.

[not nullable]

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.

#### Parameters

proxy | A GDBusProxy. |

#### Returns

A string owned by `proxy` . Do not free.

[not nullable]

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

[transfer full][nullable]

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

#### Parameters

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

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

#### Parameters

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][nullable][array zero-terminated=1]

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.

#### Parameters

proxy | A GDBusProxy |
info | Minimum interface this proxy conforms to or `NULL` to unset. | [transfer none][nullable]

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.

#### Parameters

proxy | A GDBusProxy |

#### Returns

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

[transfer none][nullable]

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

#### Parameters

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. | [nullable]
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`. | [nullable]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result of the method invocation. | [nullable]
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()`.

#### Parameters

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.

#### Parameters

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. | [nullable]
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`. | [nullable]
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.

#### Parameters

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. | [nullable]
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`. | [nullable]
cancellable | A GCancellable or `NULL`. | [nullable]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result of the method invocation. | [nullable]
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()`.

#### Parameters

proxy | A GDBusProxy. |
out_fd_list | Return location for a GUnixFDList or `NULL`. | [out][optional]
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.

#### Parameters

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. | [nullable]
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`. | [nullable]
out_fd_list | Return location for a GUnixFDList or `NULL`. | [out][optional]
cancellable | A GCancellable or `NULL`. | [nullable]
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

## Types and Values

### enum GDBusProxyFlags

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

#### Members

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 the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization or a method call. This flag is only meaningful 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. |
G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION | If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization, but allow it to be autostarted by a method call. This flag is only meaningful in proxies for well-known names, and only if `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is not also specified. |
G_DBUS_PROXY_FLAGS_NO_MATCH_RULE | Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). (Since: 2.72) |

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.

#### Members

`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

## Property Details

### The `“g-bus-type”` property

      “g-bus-type”               GBusType

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.

Owner: GDBusProxy

Flags: Write / Construct Only

Default value: G_BUS_TYPE_NONE

Since: 2.26

### The `“g-connection”` property

      “g-connection”             GDBusConnection *

The GDBusConnection the proxy is for.

Owner: GDBusProxy

Flags: Read / Write / Construct Only

Since: 2.26

### The `“g-default-timeout”` property

      “g-default-timeout”        int

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.

Owner: GDBusProxy

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: -1

Since: 2.26

### The `“g-flags”` property

      “g-flags”                  GDBusProxyFlags

Flags from the GDBusProxyFlags enumeration.

Owner: GDBusProxy

Flags: Read / Write / Construct Only

Since: 2.26

### The `“g-interface-info”` property

      “g-interface-info”         GDBusInterfaceInfo *

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.

Owner: GDBusProxy

Flags: Read / Write

Since: 2.26

### The `“g-interface-name”` property

      “g-interface-name”         char *

The D-Bus interface name the proxy is for.

Owner: GDBusProxy

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26

### The `“g-name”` property

      “g-name”                   char *

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

Owner: GDBusProxy

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26

### The `“g-name-owner”` property

      “g-name-owner”             char *

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.

Owner: GDBusProxy

Flags: Read

Default value: NULL

Since: 2.26

### The `“g-object-path”` property

      “g-object-path”            char *

The object path the proxy is for.

Owner: GDBusProxy

Flags: Read / Write / Construct Only

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)

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.

#### Parameters

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

Flags: Run Last

Since: 2.26

### The `“g-signal”` signal

    void
    user_function (GDBusProxy *proxy,
                   char       *sender_name,
                   char       *signal_name,
                   GVariant   *parameters,
                   gpointer    user_data)

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

Since 2.72 this signal supports detailed connections. You can connect to the detailed signal `g-signal::x` in order to receive callbacks only when signal `x` is received from the remote object.

#### Parameters

proxy | The GDBusProxy emitting the signal. |
sender_name | The sender of the signal or `NULL` if the connection is not a bus connection. | [nullable]
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. |

Flags: Has Details

Since: 2.26