From 16beda3dbbca708a64d40394c8ff23b86a4dba43 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Sat, 20 Dec 2008 16:39:26 -0500 Subject: fix up docs for EggDBusObjectProxy --- src/eggdbus/eggdbusobjectproxy.c | 122 ++++++++++++++++++++++++++++++++++++++- src/tests/testclient.c | 2 +- 2 files changed, 120 insertions(+), 4 deletions(-) diff --git a/src/eggdbus/eggdbusobjectproxy.c b/src/eggdbus/eggdbusobjectproxy.c index 2afaadd..df16ada 100644 --- a/src/eggdbus/eggdbusobjectproxy.c +++ b/src/eggdbus/eggdbusobjectproxy.c @@ -43,7 +43,72 @@ * @short_description: Proxy for remote objects * @see_also: #EggDBusConnection * - * Instances of #EggDBusObjectProxy represents a remote object. + * 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 + * #EggDBusObjectProxy:connection, #EggDBusObjectProxy:name and #EggDBusObjectProxy:object-path + * properties. Also, the current owner of the name the object proxy is + * associated with can be obtained from the #EggDBusObjectProxy: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 #EggDBusObjectProxy: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 generated. 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_invoke_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. */ typedef struct @@ -359,6 +424,11 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass) g_type_class_add_private (klass, sizeof (EggDBusObjectProxyPrivate)); + /** + * EggDBusObjectProxy:name: + * + * The name on the bus that the #EggDBusObjectProxy instance is associated with. + */ g_object_class_install_property (gobject_class, PROP_NAME, g_param_spec_string ("name", @@ -387,7 +457,7 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass) * :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 + * %NULL. If this is the case then the object proxy is pretty much useless * as unique names are never recycled. * * Connect to the #GObject::notify signal to track changes to this @@ -404,6 +474,11 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass) G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * EggDBusObjectProxy:object-path: + * + * The object path that the #EggDBusObjectProxy instance is associated with. + */ g_object_class_install_property (gobject_class, PROP_OBJECT_PATH, g_param_spec_boxed ("object-path", @@ -416,11 +491,16 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass) G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + /** + * EggDBusObjectProxy:connection: + * + * The connection that the #EggDBusObjectProxy instance is associated with. + */ g_object_class_install_property (gobject_class, PROP_CONNECTION, g_param_spec_object ("connection", "Connection", - "The connection that owns the object_proxy", + "The connection that owns the object proxy", EGG_DBUS_TYPE_CONNECTION, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | @@ -442,6 +522,15 @@ _egg_dbus_object_proxy_new (EggDBusConnection *connection, NULL)); } +/** + * egg_dbus_object_proxy_get_connection: + * @object_proxy: A #EggDBusObjectProxy. + * + * C getter for the #EggDBusObjectProxy:connection property. + * + * Returns: The #EggDBusConnection that @object_proxy is associated with. Do not free, the + * connection object is owned by @object_proxy. + **/ EggDBusConnection * egg_dbus_object_proxy_get_connection (EggDBusObjectProxy *object_proxy) { @@ -452,6 +541,15 @@ egg_dbus_object_proxy_get_connection (EggDBusObjectProxy *object_proxy) return priv->connection; } +/** + * egg_dbus_object_proxy_get_name: + * @object_proxy: A #EggDBusObjectProxy. + * + * C getter for the #EggDBusObjectProxy:name property. + * + * Returns: The bus name that @object_proxy is associated with. Do not free, the + * string is owned by @object_proxy. + **/ const gchar * egg_dbus_object_proxy_get_name (EggDBusObjectProxy *object_proxy) { @@ -462,6 +560,15 @@ egg_dbus_object_proxy_get_name (EggDBusObjectProxy *object_proxy) return priv->name; } +/** + * egg_dbus_object_proxy_get_object_path: + * @object_proxy: A #EggDBusObjectProxy. + * + * C getter for the #EggDBusObjectProxy:object-path property. + * + * Returns: The object path that @object_proxy is associated with. Do not free, the + * string is owned by @object_proxy. + **/ const gchar * egg_dbus_object_proxy_get_object_path (EggDBusObjectProxy *object_proxy) { @@ -472,6 +579,15 @@ egg_dbus_object_proxy_get_object_path (EggDBusObjectProxy *object_proxy) return priv->object_path; } +/** + * egg_dbus_object_proxy_get_name_owner: + * @object_proxy: A #EggDBusObjectProxy. + * + * C getter for the #EggDBusObjectProxy:name-owner property. + * + * Returns: The unique name, if any, that owns the name that @object_proxy is associated + * with. Free with g_free(). + **/ gchar * egg_dbus_object_proxy_get_name_owner (EggDBusObjectProxy *object_proxy) { diff --git a/src/tests/testclient.c b/src/tests/testclient.c index 8d298fd..3fd68d7 100644 --- a/src/tests/testclient.c +++ b/src/tests/testclient.c @@ -3066,7 +3066,7 @@ test_register_interface (void) EggDBusObjectProxy *slash_object_proxy; EggDBusObjectProxy *slash_foo_object_proxy; EggDBusObjectProxy *slash_foo_bar0_object_proxy; - EggDBusInterfaceNodeInfo*node_info; + EggDBusInterfaceNodeInfo *node_info; GError *error; gchar *s; -- cgit v1.2.3