manpagez: man pages & more
html files: eggdbus
Home | html | info | man

EggDBusObjectProxy

EggDBusObjectProxy — Proxy for remote objects

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
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.