Working - simple message passing with serverClient signal send-receive

[platform/upstream/dbus.git] / dbus / dbus-address.c

diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c
index c6354f1..90484dc 100644 (file)
--- a/dbus/dbus-address.c
+++ b/dbus/dbus-address.c
@@ -1,4 +1,4 @@
-/* -*- mode: C; c-file-style: "gnu" -*- */
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 /* dbus-address.c  Server address parser.
  *
  * Copyright (C) 2003  CodeFactory AB
@@ -18,7 +18,7 @@
  * 
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  *
  */
 
@@ -49,8 +49,20 @@ struct DBusAddressEntry
 };
 
 
+/**
+ *
+ * Sets #DBUS_ERROR_BAD_ADDRESS.
+ * If address_problem_type and address_problem_field are not #NULL,
+ * sets an error message about how the field is no good. Otherwise, sets
+ * address_problem_other as the error message.
+ * 
+ * @param error the error to set
+ * @param address_problem_type the address type of the bad address or #NULL
+ * @param address_problem_field the missing field of the bad address or #NULL
+ * @param address_problem_other any other error message or #NULL
+ */
 void
-_dbus_set_bad_address (DBusError *error,
+_dbus_set_bad_address (DBusError  *error,
                        const char *address_problem_type,
                        const char *address_problem_field,
                        const char *address_problem_other)
@@ -65,6 +77,10 @@ _dbus_set_bad_address (DBusError *error,
                     address_problem_other);
 }
 
+/**
+ * #TRUE if the byte need not be escaped when found in a dbus address.
+ * All other bytes are required to be escaped in a valid address.
+ */
 #define _DBUS_ADDRESS_OPTIONALLY_ESCAPED_BYTE(b)        \
          (((b) >= 'a' && (b) <= 'z') ||                 \
           ((b) >= 'A' && (b) <= 'Z') ||                 \
@@ -73,6 +89,7 @@ _dbus_set_bad_address (DBusError *error,
           (b) == '_' ||                                 \
           (b) == '/' ||                                 \
           (b) == '\\' ||                                \
+          (b) == '*' ||                                \
           (b) == '.')
 
 /**
@@ -198,7 +215,9 @@ create_entry (void)
 }
 
 /**
- * Returns the method string of an address entry.
+ * Returns the method string of an address entry.  For example, given
+ * the address entry "tcp:host=example.com" it would return the string
+ * "tcp"
  *
  * @param entry the entry.
  * @returns a string describing the method. This string
@@ -211,8 +230,12 @@ dbus_address_entry_get_method (DBusAddressEntry *entry)
 }
 
 /**
- * Returns a value from a key of an entry.
+ * Returns a value from a key of an entry. For example,
+ * given the address "tcp:host=example.com,port=8073" if you asked
+ * for the key "host" you would get the value "example.com"
  *
+ * The returned value is already unescaped.
+ * 
  * @param entry the entry.
  * @param key the key.
  * @returns the key value. This string must not be freed.
@@ -326,6 +349,9 @@ append_unescaped_value (DBusString       *unescaped,
  * method:key=value,key=value;method:key=value
  *
  * See the D-Bus specification for complete docs on the format.
+ *
+ * When connecting to an address, the first address entries
+ * in the semicolon-separated list should be tried first.
  * 
  * @param address the address.
  * @param entry return location to an array of entries.
@@ -351,6 +377,13 @@ dbus_parse_address (const char         *address,
   entries = NULL;
   pos = 0;
   len = _dbus_string_get_length (&str);
+
+  if (len == 0)
+  {
+    dbus_set_error (error, DBUS_ERROR_BAD_ADDRESS,
+                    "Empty address '%s'", address);
+    goto error;
+  }
   
   while (pos < len)
     {
@@ -573,7 +606,8 @@ dbus_address_escape_value (const char *value)
 
 /**
  * Unescapes the given string as a value in a key=value pair
- * for a D-Bus address.
+ * for a D-Bus address. Note that dbus_address_entry_get_value()
+ * returns an already-unescaped value.
  *
  * @param value the escaped value
  * @param error error to set if the unescaping fails
@@ -615,6 +649,9 @@ dbus_address_unescape_value (const char *value,
 /** @} */ /* End of public API */
 
 #ifdef DBUS_BUILD_TESTS
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include "dbus-test.h"
 #include <stdlib.h>
 
@@ -655,19 +692,16 @@ static const char* invalid_escaped_values[] = {
   "%",
   "$",
   " ",
-  "*"
 };
 
 dbus_bool_t
 _dbus_address_test (void)
 {
   DBusAddressEntry **entries;
-  int len;  
-  DBusError error;
+  int len;
+  DBusError error = DBUS_ERROR_INIT;
   int i;
 
-  dbus_error_init (&error);
-
   i = 0;
   while (i < _DBUS_N_ELEMENTS (escape_tests))
     {
@@ -739,6 +773,11 @@ _dbus_address_test (void)
   dbus_address_entries_free (entries);
 
   /* Different possible errors */
+  if (dbus_parse_address ("", &entries, &len, &error))
+    _dbus_assert_not_reached ("Parsed incorrect address.");
+  else
+    dbus_error_free (&error);
+
   if (dbus_parse_address ("foo", &entries, &len, &error))
     _dbus_assert_not_reached ("Parsed incorrect address.");
   else
@@ -782,4 +821,6 @@ _dbus_address_test (void)
   return TRUE;
 }
 
+#endif /* !DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif