2005-01-18 Havoc Pennington <hp@redhat.com>

        * Throughout, grand renaming to strip out the use of "service",
	just say "name" instead (or "bus name" when ambiguous).  Did not
	change the internal code of the message bus itself, only the
	programmer-facing API and messages.

	* doc/dbus-specification.xml: further update the message bus section

	* bus/config-parser.c (all_are_equiv): fix bug using freed string
	in error case

1 files changed, 54 insertions, 53 deletions

diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index 8bb48667..e4c761c2 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -728,7 +728,7 @@ dbus_message_new (int message_type)
  * that if multiple methods with the given name exist it is undefined
  * which one will be invoked.
   *
- * @param destination service that the message should be sent to or #NULL
+ * @param destination name that the message should be sent to or #NULL
  * @param path object path the message should be sent to
  * @param interface interface to invoke method on
  * @param method method to invoke
@@ -747,7 +747,7 @@ dbus_message_new_method_call (const char *destination,
   _dbus_return_val_if_fail (path != NULL, NULL);
   _dbus_return_val_if_fail (method != NULL, NULL);
   _dbus_return_val_if_fail (destination == NULL ||
-                            _dbus_check_is_valid_service (destination), NULL);
+                            _dbus_check_is_valid_bus_name (destination), NULL);
   _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
   _dbus_return_val_if_fail (interface == NULL ||
                             _dbus_check_is_valid_interface (interface), NULL);
@@ -2190,41 +2190,41 @@ dbus_message_get_no_reply (DBusMessage *message)
 }
 
 /**
- * Sets a flag indicating that the addressed service will be
- * auto-activated before the message is delivered. When this flag is
- * set, the message is held until the service is succesfully activated
- * or fails to activate. In case of failure, the reply will be an
- * activation error. If this flag is not set (the default
+ * Sets a flag indicating that an owner for the destination name will
+ * be automatically started before the message is delivered. When this
+ * flag is set, the message is held until a name owner finishes
+ * starting up, or fails to start up. In case of failure, the reply
+ * will be an error.
  *
  * @param message the message
- * @param auto_activation #TRUE if auto-activation is desired
+ * @param auto_start #TRUE if auto-starting is desired
  */
 void
-dbus_message_set_auto_activation (DBusMessage *message,
-				  dbus_bool_t  auto_activation)
+dbus_message_set_auto_start (DBusMessage *message,
+                             dbus_bool_t  auto_start)
 {
   _dbus_return_if_fail (message != NULL);
   _dbus_return_if_fail (!message->locked);
 
   _dbus_header_toggle_flag (&message->header,
-                            DBUS_HEADER_FLAG_AUTO_ACTIVATION,
-                            auto_activation);
+                            DBUS_HEADER_FLAG_AUTO_START,
+                            auto_start);
 }
 
 /**
- * Returns #TRUE if the message will cause the addressed service to be
- * auto-activated.
+ * Returns #TRUE if the message will cause an owner for
+ * destination name to be auto-started.
  *
  * @param message the message
- * @returns #TRUE if the message will use auto-activation
+ * @returns #TRUE if the message will use auto-start
  */
 dbus_bool_t
-dbus_message_get_auto_activation (DBusMessage *message)
+dbus_message_get_auto_start (DBusMessage *message)
 {
   _dbus_return_val_if_fail (message != NULL, FALSE);
 
   return _dbus_header_get_flag (&message->header,
-                                DBUS_HEADER_FLAG_AUTO_ACTIVATION);
+                                DBUS_HEADER_FLAG_AUTO_START);
 }
 
 
@@ -2462,10 +2462,13 @@ dbus_message_get_error_name (DBusMessage *message)
 }
 
 /**
- * Sets the message's destination service.
+ * Sets the message's destination. The destination is the name of
+ * another connection on the bus and may be either the unique name
+ * assigned by the bus to each connection, or a well-known name
+ * specified in advance.
  *
  * @param message the message
- * @param destination the destination service name or #NULL to unset
+ * @param destination the destination name or #NULL to unset
  * @returns #FALSE if not enough memory
  */
 dbus_bool_t
@@ -2475,7 +2478,7 @@ dbus_message_set_destination (DBusMessage  *message,
   _dbus_return_val_if_fail (message != NULL, FALSE);
   _dbus_return_val_if_fail (!message->locked, FALSE);
   _dbus_return_val_if_fail (destination == NULL ||
-                            _dbus_check_is_valid_service (destination),
+                            _dbus_check_is_valid_bus_name (destination),
                             FALSE);
 
   return set_or_delete_string_field (message,
@@ -2485,11 +2488,10 @@ dbus_message_set_destination (DBusMessage  *message,
 }
 
 /**
- * Gets the destination service of a message or #NULL if there is
- * none set.
+ * Gets the destination of a message or #NULL if there is none set.
  *
  * @param message the message
- * @returns the message destination service (should not be freed) or #NULL
+ * @returns the message destination (should not be freed) or #NULL
  */
 const char*
 dbus_message_get_destination (DBusMessage *message)
@@ -2520,7 +2522,7 @@ dbus_message_set_sender (DBusMessage  *message,
   _dbus_return_val_if_fail (message != NULL, FALSE);
   _dbus_return_val_if_fail (!message->locked, FALSE);
   _dbus_return_val_if_fail (sender == NULL ||
-                            _dbus_check_is_valid_service (sender),
+                            _dbus_check_is_valid_bus_name (sender),
                             FALSE);
 
   return set_or_delete_string_field (message,
@@ -2530,11 +2532,12 @@ dbus_message_set_sender (DBusMessage  *message,
 }
 
 /**
- * Gets the service which originated this message,
- * or #NULL if unknown or inapplicable.
+ * Gets the unique name of the connection which originated this
+ * message, or #NULL if unknown or inapplicable. The sender is filled
+ * in by the message bus.
  *
  * @param message the message
- * @returns the service name or #NULL
+ * @returns the unique name of the sender or #NULL
  */
 const char*
 dbus_message_get_sender (DBusMessage *message)
@@ -2706,67 +2709,65 @@ dbus_message_is_error (DBusMessage *message,
 }
 
 /**
- * Checks whether the message was sent to the given service.  If the
- * message has no service specified or has a different name, returns
- * #FALSE.
+ * Checks whether the message was sent to the given name.  If the
+ * message has no destination specified or has a different
+ * destination, returns #FALSE.
  *
  * @param message the message
- * @param service the service to check (must not be #NULL)
+ * @param name the name to check (must not be #NULL)
  *
- * @returns #TRUE if the message has the given destination service
+ * @returns #TRUE if the message has the given destination name
  */
 dbus_bool_t
 dbus_message_has_destination (DBusMessage  *message,
-                              const char   *service)
+                              const char   *name)
 {
   const char *s;
 
   _dbus_return_val_if_fail (message != NULL, FALSE);
-  _dbus_return_val_if_fail (service != NULL, FALSE);
-  /* don't check that service name is valid since it would be expensive,
-   * and not catch many common errors
+  _dbus_return_val_if_fail (name != NULL, FALSE);
+  /* don't check that name is valid since it would be expensive, and
+   * not catch many common errors
    */
 
   s = dbus_message_get_destination (message);
 
-  if (s && strcmp (s, service) == 0)
+  if (s && strcmp (s, name) == 0)
     return TRUE;
   else
     return FALSE;
 }
 
 /**
- * Checks whether the message has the given service as its sender.  If
- * the message has no sender specified or has a different sender,
- * returns #FALSE. Note that if a peer application owns multiple
- * services, its messages will have only one of those services as the
- * sender (usually the base service). So you can't use this
- * function to prove the sender didn't own service Foo, you can
- * only use it to prove that it did.
+ * Checks whether the message has the given unique name as its sender.
+ * If the message has no sender specified or has a different sender,
+ * returns #FALSE. Note that a peer application will always have the
+ * unique name of the connection as the sender. So you can't use this
+ * function to see whether a sender owned a well-known name.
  *
- * @todo this function is probably useless unless we make a hard guarantee
- * that the sender field in messages will always be the base service name
+ * Messages from the bus itself will have #DBUS_SERVICE_ORG_FREEDESKTOP_DBUS
+ * as the sender.
  *
  * @param message the message
- * @param service the service to check (must not be #NULL)
+ * @param name the name to check (must not be #NULL)
  *
- * @returns #TRUE if the message has the given origin service
+ * @returns #TRUE if the message has the given sender
  */
 dbus_bool_t
 dbus_message_has_sender (DBusMessage  *message,
-                         const char   *service)
+                         const char   *name)
 {
   const char *s;
 
   _dbus_return_val_if_fail (message != NULL, FALSE);
-  _dbus_return_val_if_fail (service != NULL, FALSE);
-  /* don't check that service name is valid since it would be expensive,
-   * and not catch many common errors
+  _dbus_return_val_if_fail (name != NULL, FALSE);
+  /* don't check that name is valid since it would be expensive, and
+   * not catch many common errors
    */
 
   s = dbus_message_get_sender (message);
 
-  if (s && strcmp (s, service) == 0)
+  if (s && strcmp (s, name) == 0)
     return TRUE;
   else
     return FALSE;