EggDBusObjectProxy

EggDBusObjectProxy — Proxy for remote objects

Functions

Properties

EggDBusConnection * connection Read / Write / Construct Only
char * name Read / Write / Construct Only
char * name-owner Read
EggDBusObjectPath * object-path Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── EggDBusObjectProxy

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.

Functions

egg_dbus_object_proxy_get_connection ()

EggDBusConnection *
egg_dbus_object_proxy_get_connection (EggDBusObjectProxy *object_proxy);

C getter for the “connection” property.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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 .

Types and Values

EggDBusObjectProxy

typedef struct _EggDBusObjectProxy EggDBusObjectProxy;

Property Details

The “connection” property

  “connection”               EggDBusConnection *

The connection that the EggDBusObjectProxy instance is associated with.

Owner: EggDBusObjectProxy

Flags: Read / Write / Construct Only


The “name” property

  “name”                     char *

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

Owner: EggDBusObjectProxy

Flags: Read / Write / Construct Only

Default value: NULL


The “name-owner” property

  “name-owner”               char *

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.

Owner: EggDBusObjectProxy

Flags: Read

Default value: NULL


The “object-path” property

  “object-path”              EggDBusObjectPath *

The object path that the EggDBusObjectProxy instance is associated with.

Owner: EggDBusObjectProxy

Flags: Read / Write / Construct Only

See Also

EggDBusConnection