* doxygen documentation updates

* make AvahiPoll objects const
* make poll() functions pluggable in AvahiSimplePoll


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

6 files changed, 103 insertions, 19 deletions

diff --git a/avahi-common/alternative.h b/avahi-common/alternative.h
index 3d7b2fe..fa45d96 100644
--- a/avahi-common/alternative.h
+++ b/avahi-common/alternative.h
@@ -22,24 +22,28 @@
   USA.
 ***/
 
-#include <avahi-common/cdecl.h>
-
 /** \file alternative.h Functions to find alternative names for hosts and services in the case of name collision */
 
+#include <avahi-common/cdecl.h>
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
+#endif
 
 /** Find an alternative for the specified host name. If called with an
  * original host name, "2" is appended, Afterwards the number is
  * increased on each call. (i.e. "foo" becomes "foo2" becomes "foo3"
- * and so on.) g_free() the result. */
+ * and so on.) avahi_free() the result. */
 char *avahi_alternative_host_name(const char *s);
 
 /** Find an alternative for the specified service name. If called with
     an original service name, " #2" is appended. Afterwards the number
     is increased on each call (i.e. "foo" becomes "foo #2" becomes
-    "foo #3" and so on.) g_free() the result. */
+    "foo #3" and so on.) avahi_free() the result. */
 char *avahi_alternative_service_name(const char *s);
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
+#endif
 
 #endif
diff --git a/avahi-common/gccmacro.h b/avahi-common/gccmacro.h
index 42fb153..2ac6c1d 100644
--- a/avahi-common/gccmacro.h
+++ b/avahi-common/gccmacro.h
@@ -22,9 +22,12 @@
   USA.
 ***/
 
+/** \file gccmacro.h Defines some macros for GCC extensions */
+
 #ifdef __GNUC__
 #define AVAHI_GCC_SENTINEL __attribute__ ((sentinel))
 #else
+/** Macro for usage of GCC's sentinel compilation warnings */
 #define AVAHI_GCC_SENTINEL
 #endif
 
@@ -35,12 +38,16 @@
 #define AVAHI_GCC_PRINTF_ATTR(a,b)
 #endif
 
+/** Same as AVAHI_GCC_PRINTF_ATTR but hard coded to arguments 1 and 2 */
 #define AVAHI_GCC_PRINTF_ATTR12 AVAHI_GCC_PRINTF_ATTR(1,2)
+
+/** Same as AVAHI_GCC_PRINTF_ATTR but hard coded to arguments 2 and 3 */
 #define AVAHI_GCC_PRINTF_ATTR23 AVAHI_GCC_PRINTF_ATTR(2,3)
 
 #ifdef __GNUC__
 #define AVAHI_GCC_NORETURN __attribute__((noreturn))
 #else
+/** Macro for no-return functions */
 #define AVAHI_GCC_NORETURN
 #endif
 
diff --git a/avahi-common/simple-watch.c b/avahi-common/simple-watch.c
index 3caf371..5e03fe4 100644
--- a/avahi-common/simple-watch.c
+++ b/avahi-common/simple-watch.c
@@ -46,6 +46,7 @@ struct AvahiWatch {
 
 struct AvahiSimplePoll {
     AvahiPoll api;
+    AvahiPollFunc poll_func;
 
     struct pollfd* pollfds;
     int n_pollfds, max_pollfds, rebuild_pollfds;
@@ -62,7 +63,7 @@ struct AvahiSimplePoll {
     AVAHI_LLIST_HEAD(AvahiWatch, watches);
 };
 
-static AvahiWatch* watch_new(AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata) {
+static AvahiWatch* watch_new(const AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata) {
     AvahiWatch *w;
     AvahiSimplePoll *s;
     
@@ -142,7 +143,7 @@ static void watch_free(AvahiWatch *w) {
     w->simple_poll->req_cleanup = 1;
 }
 
-static void set_wakeup(AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata) {
+static void set_wakeup(const AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata) {
     AvahiSimplePoll *s;
 
     assert(api);
@@ -207,6 +208,8 @@ AvahiSimplePoll *avahi_simple_poll_new(void) {
     s->n_watches = 0;
     s->req_cleanup = 0;
 
+    avahi_simple_poll_set_func(s, NULL);
+
     AVAHI_LLIST_HEAD_INIT(AvahiWatch, s->watches);
 
     return s;
@@ -315,7 +318,7 @@ int avahi_simple_poll_iterate(AvahiSimplePoll *s, int timeout) {
             timeout = t;
     }
 
-    if ((r = poll(s->pollfds, s->n_pollfds, timeout)) < 0)
+    if ((r = s->poll_func(s->pollfds, s->n_pollfds, timeout)) < 0)
         return -1;
 
     /* Check whether the wakeup time has been reached now */
@@ -359,8 +362,14 @@ void avahi_simple_poll_quit(AvahiSimplePoll *w) {
     w->quit = 1;
 }
 
-AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s) {
+const AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s) {
     assert(s);
     
     return &s->api;
 }
+
+void avahi_simple_poll_set_func(AvahiSimplePoll *s, AvahiPollFunc func) {
+    assert(s);
+
+    s->poll_func = func ? func : (AvahiPollFunc) poll;
+}
diff --git a/avahi-common/simple-watch.h b/avahi-common/simple-watch.h
index 127ddc5..c8234f2 100644
--- a/avahi-common/simple-watch.h
+++ b/avahi-common/simple-watch.h
@@ -22,23 +22,56 @@
   USA.
 ***/
 
+/** \file simple-watch.h Simple poll() based main loop implementation */
+
+#include <sys/poll.h>
 #include <avahi-common/cdecl.h>
 
 #include "watch.h"
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
+#endif
 
+/** A main loop object. Main loops of this type aren't very flexible
+ * since they only support a single wakeup type. Nevertheless it
+ * should suffice for small test and example applications.  */
 typedef struct AvahiSimplePoll AvahiSimplePoll;
 
+/** Create a new main loop object */
 AvahiSimplePoll *avahi_simple_poll_new(void);
+
+/** Free a main loop object */
 void avahi_simple_poll_free(AvahiSimplePoll *s);
 
-AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s);
+/** Return the abstracted poll API object for this main loop
+ * object. The is will return the same pointer each time it is
+ * called. */
+const AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s);
 
+/** Run a single main loop iteration of this main loop. If sleep_time
+is < 0 this will block until any of the registered events happens,
+then it will execute the attached callback function. If sleep_time is
+0 the routine just checks if any event is pending. If yes the attached
+callback function is called, otherwise the function returns
+immediately. If sleep_time > 0 the function will block for at most the
+specified time in msecs. Returns -1 on error, 0 on success and 1 if a
+quit request has been scheduled. Usually this function should be called
+in a loop until it returns a non-zero value*/
 int avahi_simple_poll_iterate(AvahiSimplePoll *s, int sleep_time);
 
+/** Request that the main loop quits. If this is called the next
+ call to avahi_simple_poll_iterate() will return 1 */
 void avahi_simple_poll_quit(AvahiSimplePoll *s);
 
+/** Prototype for a poll() type function */
+typedef int (*AvahiPollFunc)(struct pollfd *ufds, unsigned int nfds, int timeout);
+
+/** Replace the internally used poll() function. By default the system's poll() will be used */
+void avahi_simple_poll_set_func(AvahiSimplePoll *s, AvahiPollFunc func);
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
+#endif
 
 #endif
diff --git a/avahi-common/watch-test.c b/avahi-common/watch-test.c
index af46805..a9e3e02 100644
--- a/avahi-common/watch-test.c
+++ b/avahi-common/watch-test.c
@@ -33,7 +33,7 @@
 #include "simple-watch.h"
 #include "timeval.h"
 
-static AvahiPoll *api = NULL;
+static const AvahiPoll *api = NULL;
 static AvahiSimplePoll *simple_poll = NULL;
 
 static void callback(AvahiWatch *w, int fd, AvahiWatchEvent event, void *userdata) {
diff --git a/avahi-common/watch.h b/avahi-common/watch.h
index 70dedb7..75f53b3 100644
--- a/avahi-common/watch.h
+++ b/avahi-common/watch.h
@@ -22,37 +22,68 @@
   USA.
 ***/
 
+/** \file watch.h Simplistic main loop abstraction */
+
 #include <sys/poll.h>
 #include <avahi-common/cdecl.h>
 
 #include "timeval.h"
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
+#endif
 
+/** An I/O watch object */
 typedef struct AvahiWatch AvahiWatch;
+
+/** An event polling abstraction object */
 typedef struct AvahiPoll AvahiPoll;
 
+/** Type of watch events */
 typedef enum {
-    AVAHI_WATCH_IN = POLLIN,
-    AVAHI_WATCH_OUT = POLLOUT,
-    AVAHI_WATCH_ERR = POLLERR,
-    AVAHI_WATCH_HUP = POLLHUP
+    AVAHI_WATCH_IN = POLLIN,      /** Input event */
+    AVAHI_WATCH_OUT = POLLOUT,    /** Output event */
+    AVAHI_WATCH_ERR = POLLERR,    /** Error event */
+    AVAHI_WATCH_HUP = POLLHUP     /** Hangup event */
 } AvahiWatchEvent;
 
+/** Called whenever an I/O event happens  on an I/O watch */
 typedef void (*AvahiWatchCallback)(AvahiWatch *w, int fd, AvahiWatchEvent event, void *userdata);
+
+/** Called when the wakeup time is reached */
 typedef void (*AvahiWakeupCallback)(AvahiPoll *api, void *userdata);
 
+/** Defines an abstracted event polling API. This may be used to
+ connect Avahi to other main loops. This is losely based on Unix
+ poll(2). A consumer will call watch_new() for all file descriptors it
+ wants to listen for events on. In addition he can call set_wakeup()
+ to define a single wakeup time.*/
 struct AvahiPoll {
-    void* userdata;
-    
-    AvahiWatch* (*watch_new)(AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata);
+
+    /** Some abstract user data usable by the implementor of the API */
+    void* userdata; 
+
+    /** Create a new watch for the specified file descriptor and for
+     * the specified events. The API will call the callback function
+     * whenever any of the events happens. */
+    AvahiWatch* (*watch_new)(const AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata);
+
+    /** Update the events to wait for. */
     void (*watch_update)(AvahiWatch *w, AvahiWatchEvent event);
+
+    /** Free a watch */
     void (*watch_free)(AvahiWatch *w);
-    
-    void (*set_wakeup)(AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata);
+
+    /** Set a wakeup time for the polling loop. The API will call the
+    callback function when the absolute time *tv is reached. If *tv is
+    NULL, the callback will be called in the next main loop
+    iteration. If callback is NULL the wakeup time is disabled. */
+    void (*set_wakeup)(const AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata);
 };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
+#endif
 
 #endif