 |
 |
 |
EggDBus Reference Manual |  |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | ||||
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);
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
egg_dbus_object_proxy_get_connection ()
EggDBusConnection * egg_dbus_object_proxy_get_connection (EggDBusObjectProxy *object_proxy);
C getter for the "connection" property.
|
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.
|
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.
|
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.
|
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.
|
A EggDBusObjectProxy. |
|
Flags from EggDBusCallFlags detailing how the D-Bus message should be sent. |
|
A GCancellable or NULL.
|
|
Callback to invoke when the asynchronous operation finishes. |
|
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.
|
A EggDBusObjectProxy. |
|
A GAsyncResult obtained from the GAsyncReadyCallback function passed to
egg_dbus_object_proxy_introspect().
|
|
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.
|
A EggDBusObjectProxy. |
|
Flags from EggDBusCallFlags detailing how the D-Bus message should be sent. |
|
A GCancellable or NULL.
|
|
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.
|
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.
|
A EggDBusObjectProxy. |
|
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.