From: Lennart Poettering <lennart@poettering.net>
Date: Sun, 14 Aug 2005 02:33:41 +0000 (+0000)
Subject: * doxygen documentation updates
X-Git-Url: https://git.meshlink.io/?a=commitdiff_plain;h=fcc9b0efe1accdb0edcb3143a8e15782e69383db;p=catta

* 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
---

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
 
diff --git a/avahi-core/core.h b/avahi-core/core.h
index 1f2dda9..b8ee91a 100644
--- a/avahi-core/core.h
+++ b/avahi-core/core.h
@@ -91,7 +91,7 @@ typedef struct AvahiServerConfig {
 
 /** Allocate a new mDNS responder object. */
 AvahiServer *avahi_server_new(
-    AvahiPoll *api,                /**< The main loop adapter */
+    const AvahiPoll *api,          /**< The main loop adapter */
     const AvahiServerConfig *sc,   /**< If non-NULL a pointer to a configuration structure for the server. The server makes an internal deep copy of this structure, so you may free it using avahi_server_config_done() immediately after calling this function. */
     AvahiServerCallback callback,  /**< A callback which is called whenever the state of the server changes */
     void* userdata,                /**< An opaque pointer which is passed to the callback function */
diff --git a/avahi-core/netlink.c b/avahi-core/netlink.c
index 92d614f..c5afde9 100644
--- a/avahi-core/netlink.c
+++ b/avahi-core/netlink.c
@@ -41,7 +41,7 @@ struct AvahiNetlink {
     uint8_t* buffer;
     size_t buffer_length;
 
-    AvahiPoll *poll_api;
+    const AvahiPoll *poll_api;
     AvahiWatch *watch;
 };
 
@@ -93,7 +93,7 @@ static void socket_event(AvahiWatch *w, int fd, AvahiWatchEvent event, void *use
     avahi_netlink_work(nl, 0);
 }
 
-AvahiNetlink *avahi_netlink_new(AvahiPoll *poll_api, uint32_t groups, void (*cb) (AvahiNetlink *nl, struct nlmsghdr *n, void* userdata), void* userdata) {
+AvahiNetlink *avahi_netlink_new(const AvahiPoll *poll_api, uint32_t groups, void (*cb) (AvahiNetlink *nl, struct nlmsghdr *n, void* userdata), void* userdata) {
     int fd = -1;
     struct sockaddr_nl addr;
     AvahiNetlink *nl = NULL;
diff --git a/avahi-core/netlink.h b/avahi-core/netlink.h
index 4768b6e..78f92d8 100644
--- a/avahi-core/netlink.h
+++ b/avahi-core/netlink.h
@@ -32,7 +32,7 @@ typedef struct AvahiNetlink AvahiNetlink;
 
 typedef void (*AvahiNetlinkCallback)(AvahiNetlink *n, struct nlmsghdr *m, void* userdata);
 
-AvahiNetlink *avahi_netlink_new(AvahiPoll *poll_api, uint32_t groups, AvahiNetlinkCallback callback, void* userdata);
+AvahiNetlink *avahi_netlink_new(const AvahiPoll *poll_api, uint32_t groups, AvahiNetlinkCallback callback, void* userdata);
 void avahi_netlink_free(AvahiNetlink *n);
 int avahi_netlink_send(AvahiNetlink *n, struct nlmsghdr *m, unsigned *ret_seq);
 int avahi_netlink_work(AvahiNetlink *n, int block);
diff --git a/avahi-core/server.c b/avahi-core/server.c
index ca5da5d..40ef616 100644
--- a/avahi-core/server.c
+++ b/avahi-core/server.c
@@ -1301,7 +1301,7 @@ static int setup_sockets(AvahiServer *s) {
     return 0;
 }
 
-AvahiServer *avahi_server_new(AvahiPoll *poll_api, const AvahiServerConfig *sc, AvahiServerCallback callback, void* userdata, int *error) {
+AvahiServer *avahi_server_new(const AvahiPoll *poll_api, const AvahiServerConfig *sc, AvahiServerCallback callback, void* userdata, int *error) {
     AvahiServer *s;
     int e;
     
diff --git a/avahi-core/server.h b/avahi-core/server.h
index 3630d1e..6ceab42 100644
--- a/avahi-core/server.h
+++ b/avahi-core/server.h
@@ -90,7 +90,7 @@ struct AvahiSEntryGroup {
 };
 
 struct AvahiServer {
-    AvahiPoll *poll_api;
+    const AvahiPoll *poll_api;
     
     AvahiInterfaceMonitor *monitor;
     AvahiServerConfig config;
diff --git a/avahi-core/timeeventq.c b/avahi-core/timeeventq.c
index b069ffd..bb9a5cd 100644
--- a/avahi-core/timeeventq.c
+++ b/avahi-core/timeeventq.c
@@ -42,7 +42,7 @@ struct AvahiTimeEvent {
 };
 
 struct AvahiTimeEventQueue {
-    AvahiPoll *poll_api;
+    const AvahiPoll *poll_api;
     AvahiPrioQueue *prioq;
 };
 
@@ -105,7 +105,7 @@ static void fix_expiry_time(AvahiTimeEvent *e) {
         e->expiry = now;
 }
 
-AvahiTimeEventQueue* avahi_time_event_queue_new(AvahiPoll *poll_api) {
+AvahiTimeEventQueue* avahi_time_event_queue_new(const AvahiPoll *poll_api) {
     AvahiTimeEventQueue *q;
 
     if (!(q = avahi_new(AvahiTimeEventQueue, 1))) {
diff --git a/avahi-core/timeeventq.h b/avahi-core/timeeventq.h
index b99c81f..5705eb9 100644
--- a/avahi-core/timeeventq.h
+++ b/avahi-core/timeeventq.h
@@ -33,7 +33,7 @@ typedef struct AvahiTimeEvent AvahiTimeEvent;
 
 typedef void (*AvahiTimeEventCallback)(AvahiTimeEvent *e, void* userdata);
 
-AvahiTimeEventQueue* avahi_time_event_queue_new(AvahiPoll *poll_api);
+AvahiTimeEventQueue* avahi_time_event_queue_new(const AvahiPoll *poll_api);
 void avahi_time_event_queue_free(AvahiTimeEventQueue *q);
 
 AvahiTimeEvent* avahi_time_event_new(
diff --git a/avahi-glib/glib-watch-test.c b/avahi-glib/glib-watch-test.c
index bd111dd..17b334d 100644
--- a/avahi-glib/glib-watch-test.c
+++ b/avahi-glib/glib-watch-test.c
@@ -33,7 +33,7 @@
 #include <avahi-common/timeval.h>
 #include "glib-watch.h"
 
-static AvahiPoll *api = NULL;
+static const AvahiPoll *api = NULL;
 static GMainLoop *loop = NULL;
 
 static void callback(AvahiWatch *w, int fd, AvahiWatchEvent event, void *userdata) {
diff --git a/avahi-glib/glib-watch.c b/avahi-glib/glib-watch.c
index 4af2390..f099e5a 100644
--- a/avahi-glib/glib-watch.c
+++ b/avahi-glib/glib-watch.c
@@ -78,7 +78,7 @@ static void cleanup(AvahiGLibPoll *g, int all) {
     g->req_cleanup = 0;
 }
 
-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;
     AvahiGLibPoll *g;
     
@@ -132,7 +132,7 @@ static void watch_free(AvahiWatch *w) {
     w->glib_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) {
     AvahiGLibPoll *g;
 
     assert(api);
@@ -299,7 +299,7 @@ void avahi_glib_poll_free(AvahiGLibPoll *g) {
 /*     g_message("AFTER"); */
 }
 
-AvahiPoll* avahi_glib_poll_get(AvahiGLibPoll *g) {
+const AvahiPoll* avahi_glib_poll_get(AvahiGLibPoll *g) {
     assert(g);
 
     return &g->api;
diff --git a/avahi-glib/glib-watch.h b/avahi-glib/glib-watch.h
index 9e6bd68..4fa8a3b 100644
--- a/avahi-glib/glib-watch.h
+++ b/avahi-glib/glib-watch.h
@@ -22,19 +22,36 @@
   USA.
 ***/
 
+/** \file glib-watch.h GLib's memory allocator for Avahi */
+
 #include <glib.h>
 
 #include <avahi-common/cdecl.h>
 #include <avahi-common/watch.h>
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
+#endif
 
+/** GLib main loop adapter */
 typedef struct AvahiGLibPoll AvahiGLibPoll;
 
+/** Create a new GLib main loop adapter attached to the specified
+ context. If context is NULL, the default main loop context is
+ used. You can attach as many AvahiGLibPoll objects to the same context
+ as you want. */
 AvahiGLibPoll *avahi_glib_poll_new(GMainContext *context);
+
+/** Free  GLib main loop adapter */
 void avahi_glib_poll_free(AvahiGLibPoll *g);
-AvahiPoll* avahi_glib_poll_get(AvahiGLibPoll *g);
 
+/** Return the abstract poll API structure for this object. This will
+ * return the same pointer to a internally allocated structure on each
+ * call */
+const AvahiPoll *avahi_glib_poll_get(AvahiGLibPoll *g);
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
+#endif
 
 #endif