From fcc9b0efe1accdb0edcb3143a8e15782e69383db Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 14 Aug 2005 02:33:41 +0000 Subject: * 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 --- avahi-common/alternative.h | 12 +++++++---- avahi-common/gccmacro.h | 7 +++++++ avahi-common/simple-watch.c | 17 +++++++++++---- avahi-common/simple-watch.h | 35 ++++++++++++++++++++++++++++++- avahi-common/watch-test.c | 2 +- avahi-common/watch.h | 49 ++++++++++++++++++++++++++++++++++++-------- avahi-core/core.h | 2 +- avahi-core/netlink.c | 4 ++-- avahi-core/netlink.h | 2 +- avahi-core/server.c | 2 +- avahi-core/server.h | 2 +- avahi-core/timeeventq.c | 4 ++-- avahi-core/timeeventq.h | 2 +- avahi-glib/glib-watch-test.c | 2 +- avahi-glib/glib-watch.c | 6 +++--- avahi-glib/glib-watch.h | 19 ++++++++++++++++- 16 files changed, 134 insertions(+), 33 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 - /** \file alternative.h Functions to find alternative names for hosts and services in the case of name collision */ +#include + +#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 #include #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 #include #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 #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 #include #include +#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 -- cgit