## EggDBusObjectProxy EggDBusObjectProxy — Proxy for remote objects |

## Synopsis

                        EggDBusObjectProxy;
    EggDBusConnection * egg_dbus_object_proxy_get_connection
                                                            (EggDBusObjectProxy *object_proxy);
    const gchar *       egg_dbus_object_proxy_get_name      (EggDBusObjectProxy *object_proxy);
    const gchar *       egg_dbus_object_proxy_get_object_path
                                                            (EggDBusObjectProxy *object_proxy);
    gchar *             egg_dbus_object_proxy_get_name_owner
                                                            (EggDBusObjectProxy *object_proxy);
    guint               egg_dbus_object_proxy_introspect    (EggDBusObjectProxy *object_proxy,
                                                             EggDBusCallFlags call_flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    EggDBusInterfaceNodeInfo * egg_dbus_object_proxy_introspect_finish
                                                            (EggDBusObjectProxy *object_proxy,
                                                             GAsyncResult *res,
                                                             GError **error);
    EggDBusInterfaceNodeInfo * egg_dbus_object_proxy_introspect_sync
                                                            (EggDBusObjectProxy *object_proxy,
                                                             EggDBusCallFlags call_flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                egg_dbus_object_proxy_invalidate_properties
                                                            (EggDBusObjectProxy *object_proxy);
    EggDBusInterfaceProxy * egg_dbus_object_proxy_query_interface
                                                            (EggDBusObjectProxy *object_proxy,
                                                             GType interface_type);

## Object Hierarchy

      GObject
       +----EggDBusObjectProxy

## Properties

      "connection"               EggDBusConnection*    : Read / Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct Only
      "name-owner"               gchar*                : Read
      "object-path"              EggDBusObjectPath*    : Read / Write / Construct Only

## Description

Instances of the EggDBusObjectProxy class represents remote objects. You can't instantiate this class directly, you have to use `egg_dbus_connection_get_object_proxy()`. The tripple consisting of a connection, bus name and object path uniquely identifies a remote object.

You can get the connection name, object path for a EggDBusObjectProxy instance from the "connection", "name" and "object-path" properties. Also, the current owner of the name the object proxy is associated with can be obtained from the "name-owner" property.

Note that an EggDBusObjectProxy instance may refer to a non-existant remote object. For example names on the message bus can come and go (can be checked with "name-owner") and the remote object itself may be destroyed (for example if the object represents a piece of hardware on the system, the object may disappear when the hardware is unplugged). One way (if the remote service supports introspection) to find out if a remote object exists is to use the `egg_dbus_object_proxy_introspect()` method. If the call succeeds and the result includes one or more interfaces, the object is alive:

    EggDBusInterfaceNodeInfo *node_info;
    GError *error;

    error = NULL;
    node_info = egg_dbus_object_proxy_introspect_sync (slash_object_proxy,
                                                       EGG_DBUS_CALL_FLAGS_NONE,
                                                       NULL,
                                                       &error);
    if (node_info == NULL)
      {
        /* handle error */
      }
    else
      {
        if (node_info->num_interfaces > 0)
          {
            /* object is alive, look at node_info for more information */
          }
        egg_dbus_interface_node_info_free (node_info);
      }

To use a D-Bus interface on a EggDBusObjectProxy instance you will need a EggDBusInterfaceProxy instance for the D-Bus interface in question. Interface proxies can be obtained using the `egg_dbus_object_proxy_query_interface()` method. Typically language bindings will provide a way to obtain it; for generated C/GObject code, a macro is provided. For example, to invoke the `Ping` method on the `org.freedesktop.DBus.Peer` interface on a EggDBusObjectProxy, the EggDBusPeer interface proxy is used:

    EggDBusPeer *peer;
    GError *error;

    peer = EGG_DBUS_QUERY_INTERFACE_PEER (object_proxy);

    error = NULL;
    if (!egg_dbus_peer_ping_sync (peer,
                                  EGG_DBUS_CALL_FLAGS_NONE,
                                  NULL, /* GCancellable */
                                  &error))
      {
        g_warning ("Error: %s", error->message);
        g_error_free (error);
        goto error;
      }

See the EggDBusInterfaceProxy class for more details on using D-Bus interfaces.

## Details

### EggDBusObjectProxy

    typedef struct _EggDBusObjectProxy EggDBusObjectProxy;

### egg_dbus_object_proxy_get_connection ()

    EggDBusConnection * egg_dbus_object_proxy_get_connection
                                                            (EggDBusObjectProxy *object_proxy);

C getter for the "connection" property.

`object_proxy` : | A EggDBusObjectProxy.
Returns : | The EggDBusConnection that `object_proxy` is associated with. Do not free, the connection object is owned by `object_proxy`.

### egg_dbus_object_proxy_get_name ()

    const gchar *       egg_dbus_object_proxy_get_name      (EggDBusObjectProxy *object_proxy);

C getter for the "name" property.

`object_proxy` : | A EggDBusObjectProxy.
Returns : | The bus name that `object_proxy` is associated with. Do not free, the string is owned by `object_proxy`.

### egg_dbus_object_proxy_get_object_path ()

    const gchar *       egg_dbus_object_proxy_get_object_path
                                                            (EggDBusObjectProxy *object_proxy);

C getter for the "object-path" property.

`object_proxy` : | A EggDBusObjectProxy.
Returns : | The object path that `object_proxy` is associated with. Do not free, the string is owned by `object_proxy`.

### egg_dbus_object_proxy_get_name_owner ()

    gchar *             egg_dbus_object_proxy_get_name_owner
                                                            (EggDBusObjectProxy *object_proxy);

C getter for the "name-owner" property.

`object_proxy` : | A EggDBusObjectProxy.
Returns : | The unique name, if any, that owns the name that `object_proxy` is associated with. Free with `g_free()`.

### egg_dbus_object_proxy_introspect ()

    guint               egg_dbus_object_proxy_introspect    (EggDBusObjectProxy *object_proxy,
                                                             EggDBusCallFlags call_flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously introspects `object_proxy`. Note that this may fail if the remote object doesn't implement the `org.freedesktop.DBus.Introspectable` D-Bus interface.

When the asynchronous operation is finished, `callback` will be invoked; use `egg_dbus_object_proxy_introspect_finish()` to finish the operation.

Note that introspection data is never cached.

`object_proxy` : | A EggDBusObjectProxy.
`call_flags` : | Flags from EggDBusCallFlags detailing how the D-Bus message should be sent.
`cancellable` : | A GCancellable or `NULL`.
`callback` : | Callback to invoke when the asynchronous operation finishes.
`user_data` : | User data to pass to `callback`.
Returns : | A pending call id (never zero) that can be used with `egg_dbus_connection_pending_call_cancel()` or `egg_dbus_connection_pending_call_block()`.

### egg_dbus_object_proxy_introspect_finish ()

    EggDBusInterfaceNodeInfo * egg_dbus_object_proxy_introspect_finish
                                                            (EggDBusObjectProxy *object_proxy,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes introspecting `object_proxy`.

`object_proxy` : | A EggDBusObjectProxy.
`res` : | A GAsyncResult obtained from the GAsyncReadyCallback function passed to `egg_dbus_object_proxy_introspect()`.
`error` : | Return location for error.
Returns : | `NULL` if `error` is set, otherwise a EggDBusInterfaceNodeInfo structure that should be freed with `egg_dbus_interface_node_info_free()`.

### egg_dbus_object_proxy_introspect_sync ()

    EggDBusInterfaceNodeInfo * egg_dbus_object_proxy_introspect_sync
                                                            (EggDBusObjectProxy *object_proxy,
                                                             EggDBusCallFlags call_flags,
                                                             GCancellable *cancellable,
                                                             GError **error);

Syncrhonously introspects `object_proxy`. Note that this may fail if the remote object doesn't implement the `org.freedesktop.DBus.Introspectable` D-Bus interface.

Note that introspection data is never cached.

`object_proxy` : | A EggDBusObjectProxy.
`call_flags` : | Flags from EggDBusCallFlags detailing how the D-Bus message should be sent.
`cancellable` : | A GCancellable or `NULL`.
`error` : | Return location for error.
Returns : | `NULL` if `error` is set, otherwise a EggDBusInterfaceNodeInfo structure that should be freed with `egg_dbus_interface_node_info_free()`.

### egg_dbus_object_proxy_invalidate_properties ()

    void                egg_dbus_object_proxy_invalidate_properties
                                                            (EggDBusObjectProxy *object_proxy);

Invalidate the property caches for all interface proxies for `object_proxy`.

Typically, this is not necessary but it's useful when the remote end doesn't use a standard set of signals to indicate property changes.

`object_proxy` : | A EggDBusObjectProxy.

### egg_dbus_object_proxy_query_interface ()

    EggDBusInterfaceProxy * egg_dbus_object_proxy_query_interface
                                                            (EggDBusObjectProxy *object_proxy,
                                                             GType interface_type);

Gets an interface proxy for accessing a D-Bus interface (as specified by `interface_type`) on the remote object represented by `object_proxy`.

Note that there is no guarantee that `object_proxy` actually implements the D-Bus interface specified by `interface_type`.

`object_proxy` : | A EggDBusObjectProxy.
`interface_type` : | A GType for an interface that extends EggDBusInterface.
Returns : | An instance that implements `interface_type` and is derived from EggDBusInterfaceProxy. Do not ref or unref the returned instance; it is owned by `object_proxy`.

## Property Details

### The `"connection"` property

      "connection"               EggDBusConnection*    : Read / Write / Construct Only

The connection that the EggDBusObjectProxy instance is associated with.

### The `"name"` property

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

The name on the bus that the EggDBusObjectProxy instance is associated with.

Default value: NULL

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

      "name-owner"               gchar*                : Read

The unique name of the owner of "name", if any.

If "name" is a well-known name (e.g. `org.freedesktop.DeviceKit`), this property contains the unique name (e.g. `1:6`) of the process that currently owns the name. It is `NULL` if no process currently provides the name. If a process starts owning the name, the property will reflect that.

If "name" itself is a unique name (e.g. of the form `:1.42`), then this property is equal to that name only if the remote end with the given name is connected to the bus. If the remote end disconnects, the property changes to `NULL`. If this is the case then the object proxy is pretty much useless as unique names are never recycled.

Connect to the "notify" signal to track changes to this property.

Default value: NULL

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

      "object-path"              EggDBusObjectPath*    : Read / Write / Construct Only

The object path that the EggDBusObjectProxy instance is associated with.

## See Also

EggDBusConnection