* many improvements to avahi-client (especially error handling)

* Document AVahi error handling a little


git-svn-id: file:///home/lennart/svn/public/avahi/trunk@358 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe

4 files changed, 67 insertions, 40 deletions

diff --git a/avahi-common/dbus.c b/avahi-common/dbus.c
index 7c627a6..e2b3a3f 100644
--- a/avahi-common/dbus.c
+++ b/avahi-common/dbus.c
@@ -31,52 +31,48 @@
 #include <avahi-common/dbus.h>
 
 static const char * const table[- AVAHI_ERR_MAX] = {
-        NULL, /* OK */
-        AVAHI_DBUS_ERR_FAILURE,
-        AVAHI_DBUS_ERR_BAD_STATE,
-        AVAHI_DBUS_ERR_INVALID_HOST_NAME,
-        AVAHI_DBUS_ERR_INVALID_DOMAIN_NAME,
-        AVAHI_DBUS_ERR_NO_NETWORK,
-        AVAHI_DBUS_ERR_INVALID_TTL,
-        AVAHI_DBUS_ERR_IS_PATTERN,
-        AVAHI_DBUS_ERR_LOCAL_COLLISION,
-        AVAHI_DBUS_ERR_INVALID_RECORD,
-        AVAHI_DBUS_ERR_INVALID_SERVICE_NAME,
-        AVAHI_DBUS_ERR_INVALID_SERVICE_TYPE,
-        AVAHI_DBUS_ERR_INVALID_PORT,
-        AVAHI_DBUS_ERR_INVALID_KEY,
-        AVAHI_DBUS_ERR_INVALID_ADDRESS,
-        AVAHI_DBUS_ERR_TIMEOUT,
-        AVAHI_DBUS_ERR_TOO_MANY_CLIENTS,
-        AVAHI_DBUS_ERR_TOO_MANY_OBJECTS,
-        AVAHI_DBUS_ERR_TOO_MANY_ENTRIES,
-        AVAHI_DBUS_ERR_OS,
-        AVAHI_DBUS_ERR_ACCESS_DENIED,
-        AVAHI_DBUS_ERR_INVALID_OPERATION,
-        AVAHI_DBUS_ERR_DBUS_ERROR,
-        AVAHI_DBUS_ERR_NOT_CONNECTED,
-        AVAHI_DBUS_ERR_NO_MEMORY,
-        AVAHI_DBUS_ERR_INVALID_OBJECT,
-        AVAHI_DBUS_ERR_NO_DAEMON
-    };
+    NULL, /* OK */
+    AVAHI_DBUS_ERR_FAILURE,
+    AVAHI_DBUS_ERR_BAD_STATE,
+    AVAHI_DBUS_ERR_INVALID_HOST_NAME,
+    AVAHI_DBUS_ERR_INVALID_DOMAIN_NAME,
+    AVAHI_DBUS_ERR_NO_NETWORK,
+    AVAHI_DBUS_ERR_INVALID_TTL,
+    AVAHI_DBUS_ERR_IS_PATTERN,
+    AVAHI_DBUS_ERR_LOCAL_COLLISION,
+    AVAHI_DBUS_ERR_INVALID_RECORD,
+    AVAHI_DBUS_ERR_INVALID_SERVICE_NAME,
+    AVAHI_DBUS_ERR_INVALID_SERVICE_TYPE,
+    AVAHI_DBUS_ERR_INVALID_PORT,
+    AVAHI_DBUS_ERR_INVALID_KEY,
+    AVAHI_DBUS_ERR_INVALID_ADDRESS,
+    AVAHI_DBUS_ERR_TIMEOUT,
+    AVAHI_DBUS_ERR_TOO_MANY_CLIENTS,
+    AVAHI_DBUS_ERR_TOO_MANY_OBJECTS,
+    AVAHI_DBUS_ERR_TOO_MANY_ENTRIES,
+    AVAHI_DBUS_ERR_OS,
+    AVAHI_DBUS_ERR_ACCESS_DENIED,
+    AVAHI_DBUS_ERR_INVALID_OPERATION,
+    AVAHI_DBUS_ERR_DBUS_ERROR,
+    AVAHI_DBUS_ERR_NOT_CONNECTED,
+    AVAHI_DBUS_ERR_NO_MEMORY,
+    AVAHI_DBUS_ERR_INVALID_OBJECT,
+    AVAHI_DBUS_ERR_NO_DAEMON
+};
 
-int
-avahi_error_dbus_to_number (const char *s)
-{
+int avahi_error_dbus_to_number(const char *s) {
     int e;
 
     assert(s);
 
     for (e = -1; e > AVAHI_ERR_MAX; e--)
-        if (strcmp (s, table[-e]) == 0)
+        if (strcmp(s, table[-e]) == 0)
             return e;
 
     return AVAHI_ERR_DBUS_ERROR;
 }
 
-const char *
-avahi_error_number_to_dbus (int error)
-{
+const char *avahi_error_number_to_dbus(int error) {
     assert(error > AVAHI_ERR_MAX);
     assert(error < 1);
 
diff --git a/avahi-common/dbus.h b/avahi-common/dbus.h
index 0164bdb..bcbbb99 100644
--- a/avahi-common/dbus.h
+++ b/avahi-common/dbus.h
@@ -27,7 +27,9 @@
 #include <avahi-common/cdecl.h>
 #include <dbus/dbus.h>
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
+#endif
 
 #define AVAHI_DBUS_NAME "org.freedesktop.Avahi"
 #define AVAHI_DBUS_INTERFACE_SERVER AVAHI_DBUS_NAME".Server"
@@ -64,13 +66,14 @@ AVAHI_C_DECL_BEGIN
 #define AVAHI_DBUS_ERR_INVALID_OBJECT "org.freedesktop.Avahi.InvalidObjectError"
 #define AVAHI_DBUS_ERR_NO_DAEMON "org.freedesktop.Avahi.NoDaemonError"
 
-
 /** Convert a DBus error string into an Avahi error number */
-int avahi_error_dbus_to_number (const char *s);
+int avahi_error_dbus_to_number(const char *s);
 
 /** Convert an Avahi error number into a DBus error string.  Result should not be freed */
-const char * avahi_error_number_to_dbus (int error);
+const char * avahi_error_number_to_dbus(int error);
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
+#endif
 
 #endif
diff --git a/avahi-common/error.h b/avahi-common/error.h
index b367ffb..dc3f333 100644
--- a/avahi-common/error.h
+++ b/avahi-common/error.h
@@ -26,7 +26,24 @@
 
 #include <avahi-common/cdecl.h>
 
+/** \mainpage
+ *
+ * \section Error Reporting
+ *
+ * Some notes on the Avahai erro handling:
+ *
+ * \li Error codes are negative integers and defined in the enum AVAHI_ERR_xx 
+ * \li If a function returns some kind of non-negative integer value on success, a failure is indicated by returning the error code directly.
+ * \li If a function returns a pointer of some kind on success, a failure is indicated by returning NULL
+ * \li The last error number may be retrieved by calling avahi_server_errno() (for the server API) or avahi_client_errno() (for the client API)
+ * \li Just like the libc errno the Avahi errno is NOT reset to AVAHI_OK if a function call succeeds.
+ * \li You may convert a numeric error code into a human readable string using avahi_strerror.c
+ * 
+ */
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
+#endif
 
 /** Error codes used by avahi */
 enum { 
@@ -61,8 +78,7 @@ enum {
     /****
      ****    IF YOU ADD A NEW ERROR CODE HERE, PLEASE DON'T FORGET TO ADD
      ****    IT TO THE STRING ARRAY IN avahi_strerror() IN error.c AND
-     ****    TO THE ARRAY IN respond_error() IN dbus-protocol.c
-     ****    AND FINALLY TO dbus.h!
+     ****    TO THE ARRAY IN dbus.c AND FINALLY TO dbus.h!
      ****
      ****    Also remember to update the MAX value below.
      ****/
@@ -73,6 +89,8 @@ enum {
 /** Return a human readable error string for the specified error code */
 const char *avahi_strerror(int error);
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
+#endif
 
 #endif
diff --git a/avahi-common/gccmacro.h b/avahi-common/gccmacro.h
index 24f206f..33ff847 100644
--- a/avahi-common/gccmacro.h
+++ b/avahi-common/gccmacro.h
@@ -24,6 +24,12 @@
 
 /** \file gccmacro.h Defines some macros for GCC extensions */
 
+#include <avahi-common/cdecl.h>
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+AVAHI_C_DECL_BEGIN
+#endif
+
 #ifdef __GNUC__
 #if __GNUC__ >= 4
 #define AVAHI_GCC_SENTINEL __attribute__ ((sentinel))
@@ -55,4 +61,8 @@
 #define AVAHI_GCC_NORETURN
 #endif
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+AVAHI_C_DECL_END
+#endif
+
 #endif