summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHavoc Pennington <hp@redhat.com>2005-08-01 18:59:02 +0000
committerHavoc Pennington <hp@redhat.com>2005-08-01 18:59:02 +0000
commitc76d24b0072dbe707889bae403668dde0fcd8f9f (patch)
tree0fe76dfaf0549b7605d2f074fedd1a17faa89ad7
parent9a4c459076d118f2dd7eeb8dc81ad88c495b65bc (diff)
some docs cleanups
-rw-r--r--dbus/dbus-address.c2
-rw-r--r--dbus/dbus-auth.c4
-rw-r--r--dbus/dbus-bus.c68
-rw-r--r--doc/TODO3
4 files changed, 60 insertions, 17 deletions
diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c
index d5c38a84..b6bea780 100644
--- a/dbus/dbus-address.c
+++ b/dbus/dbus-address.c
@@ -308,7 +308,7 @@ append_unescaped_value (DBusString *unescaped,
*
* method:key=value,key=value;method:key=value
*
- * @todo document address format in the specification
+ * See the D-BUS specification for complete docs on the format.
*
* @param address the address.
* @param entry return location to an array of entries.
diff --git a/dbus/dbus-auth.c b/dbus/dbus-auth.c
index ced93303..660dc435 100644
--- a/dbus/dbus-auth.c
+++ b/dbus/dbus-auth.c
@@ -42,10 +42,6 @@
* challenge/response, but we don't currently allow that in our
* protocol.
*
- * @todo DBusAuth really needs to be rewritten as an explicit state
- * machine. Right now it's too hard to prove to yourself by inspection
- * that it works.
- *
* @todo right now sometimes both ends will block waiting for input
* from the other end, e.g. if there's an error during
* DBUS_COOKIE_SHA1.
diff --git a/dbus/dbus-bus.c b/dbus/dbus-bus.c
index c112d2ab..ad20795c 100644
--- a/dbus/dbus-bus.c
+++ b/dbus/dbus-bus.c
@@ -55,10 +55,6 @@
* Block of message-bus-related data we attach to each
* #DBusConnection used with these convenience functions.
*
- *
- * @todo get rid of most of these; they should be done
- * with DBusGProxy and the Qt equivalent, i.e. the same
- * way any other interface would be used.
*/
typedef struct
{
@@ -623,14 +619,61 @@ dbus_bus_get_unix_user (DBusConnection *connection,
/**
- * Asks the bus to assign the given name to this connection.
+ * Asks the bus to assign the given name to this connection by invoking
+ * the RequestName method on the bus. This method is fully documented
+ * in the D-BUS specification. For quick reference, the flags and
+ * result codes are discussed here, but the specification is the
+ * canonical version of this information.
+ *
+ * The #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT flag indicates that
+ * if the name is successfully requested, other applications
+ * will not be able to take over the name. i.e. the name's
+ * owner (the application calling this function) must let go of
+ * the name, it will not lose it involuntarily.
+ *
+ * The #DBUS_NAME_FLAG_REPLACE_EXISTING flag indicates that the caller
+ * would like to take over the name from the current owner.
+ * If the current name owner used #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT
+ * then this flag indicates that the caller would like to be placed
+ * in the queue to own the name when the current owner lets go.
*
- * @todo these docs are not complete, need to document the
- * return value and flags
+ * If no flags are given, an application will receive the requested
+ * name only if the name is currently unowned; and it will give
+ * up the name if another application asks to take it over using
+ * #DBUS_NAME_FLAG_REPLACE_EXISTING.
+ *
+ * This function returns a result code. The possible result codes
+ * are as follows.
*
- * @todo if we get an error reply, it has to be converted into
- * DBusError and returned
+ * #DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER means that the name had no
+ * existing owner, and the caller is now the primary owner; or that
+ * the name had an owner, and the caller specified
+ * #DBUS_NAME_FLAG_REPLACE_EXISTING, and the current owner did not
+ * specify #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.
+ *
+ * #DBUS_REQUEST_NAME_REPLY_IN_QUEUE happens only if the current owner
+ * specified #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT and the caller specified
+ * #DBUS_NAME_FLAG_REPLACE_EXISTING. In this case the caller ends up in
+ * a queue to own the name after the current owner gives it up.
+ *
+ * #DBUS_REQUEST_NAME_REPLY_EXISTS happens if the name has an owner
+ * #already and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.
*
+ * #DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER happens if an application
+ * requests a name it already owns.
+ *
+ * When a service represents an application, say "text editor," then
+ * it should specify #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT if it wants
+ * the first editor started to be the user's editor vs. the last one
+ * started. Then any editor that can be the user's editor should
+ * specify #DBUS_NAME_FLAG_REPLACE_EXISTING to either take over
+ * (last-started-wins) or be queued up (first-started-wins) according
+ * to whether #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT was given.
+ *
+ * @todo this all seems sort of broken. Shouldn't the flags be a property
+ * of the name, not the app requesting the name? What are the use-cases
+ * other than the "text editor" thing and how are we supporting them?
+ *
* @param connection the connection
* @param name the name to request
* @param flags flags
@@ -771,15 +814,16 @@ dbus_bus_name_has_owner (DBusConnection *connection,
* The returned result will be one of be one of
* #DBUS_START_REPLY_SUCCESS or #DBUS_START_REPLY_ALREADY_RUNNING if
* successful. Pass #NULL if you don't care about the result.
+ *
+ * The flags parameter is for future expansion, currently you should
+ * specify 0.
*
* @param connection the connection
* @param name the name we want the new service to request
- * @param flags the flags
+ * @param flags the flags (should always be 0 for now)
* @param result a place to store the result or #NULL
* @param error location to store any errors
* @returns #TRUE if the activation succeeded, #FALSE if not
- *
- * @todo document what the flags do
*/
dbus_bool_t
dbus_bus_start_service_by_name (DBusConnection *connection,
diff --git a/doc/TODO b/doc/TODO
index aacf93d8..c2bb699a 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -23,6 +23,9 @@ Important for 1.0
- publish the introspection dtd at its URL
+ - RequestName flags seem a bit strange; see the docs for dbus_bus_request_name()
+ and think about use cases in better detail.
+
Important for 1.0 GLib Bindings
===