client_manager: add API for async operations

[oweals/gnunet.git] / src / include / gnunet_resolver_service.h

diff --git a/src/include/gnunet_resolver_service.h b/src/include/gnunet_resolver_service.h
index f24bf5c5e83f140a94e843f4b1d08dd516a1bf66..2b165fbe549dbca119995309c37e9588a17fb2ec 100644 (file)
--- a/src/include/gnunet_resolver_service.h
+++ b/src/include/gnunet_resolver_service.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet.
-     (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2001-2013 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
@@ -22,6 +22,8 @@
  * @file include/gnunet_resolver_service.h
  * @brief functions related to doing DNS lookups
  * @author Christian Grothoff
+ * @defgroup resolver asynchronous standard DNS lookups
+ * @{
  */
 
 #ifndef GNUNET_RESOLVER_SERVICE_H
@@ -45,11 +47,12 @@ extern "C"
  *
  * @param cls closure
  * @param addr one of the addresses of the host, NULL for the last address
- * @param addrlen length of the address
+ * @param addrlen length of @a addr
  */
-typedef void (*GNUNET_RESOLVER_AddressCallback) (void *cls,
-                                                 const struct sockaddr * addr,
-                                                 socklen_t addrlen);
+typedef void
+(*GNUNET_RESOLVER_AddressCallback) (void *cls,
+                                    const struct sockaddr *addr,
+                                    socklen_t addrlen);
 
 
 /**
@@ -63,56 +66,49 @@ struct GNUNET_RESOLVER_RequestHandle;
  *
  * @param cfg configuration to use
  */
-void GNUNET_RESOLVER_connect (const struct GNUNET_CONFIGURATION_Handle *c);
+void
+GNUNET_RESOLVER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
 /**
  * Destroy the connection to the resolver service.
  */
-void GNUNET_RESOLVER_disconnect (void);
+void
+GNUNET_RESOLVER_disconnect (void);
 
 
 /**
  * Convert a string to one or more IP addresses.
  *
  * @param hostname the hostname to resolve
- * @param domain AF_INET or AF_INET6; use AF_UNSPEC for "any"
+ * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
  * @param callback function to call with addresses
- * @param callback_cls closure for callback
+ * @param callback_cls closure for @a callback
  * @param timeout how long to try resolving
  * @return handle that can be used to cancel the request, NULL on error
  */
-struct GNUNET_RESOLVER_RequestHandle *GNUNET_RESOLVER_ip_get (const char
-                                                              *hostname,
-                                                              int domain,
-                                                              struct
-                                                              GNUNET_TIME_Relative
-                                                              timeout,
-                                                              GNUNET_RESOLVER_AddressCallback
-                                                              callback,
-                                                              void
-                                                              *callback_cls);
+struct GNUNET_RESOLVER_RequestHandle *
+GNUNET_RESOLVER_ip_get (const char *hostname,
+                        int af,
+                        struct GNUNET_TIME_Relative timeout,
+                        GNUNET_RESOLVER_AddressCallback callback,
+                        void *callback_cls);
 
 
 /**
  * Resolve our hostname to an IP address.
  *
- * @param cfg configuration to use
- * @param domain AF_INET or AF_INET6; use AF_UNSPEC for "any"
+ * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any"
  * @param callback function to call with addresses
- * @param cls closure for callback
+ * @param cls closure for @a callback
  * @param timeout how long to try resolving
  * @return handle that can be used to cancel the request, NULL on error
  */
-struct GNUNET_RESOLVER_RequestHandle *GNUNET_RESOLVER_hostname_resolve (int
-                                                                        domain,
-                                                                        struct
-                                                                        GNUNET_TIME_Relative
-                                                                        timeout,
-                                                                        GNUNET_RESOLVER_AddressCallback
-                                                                        callback,
-                                                                        void
-                                                                        *cls);
+struct GNUNET_RESOLVER_RequestHandle *
+GNUNET_RESOLVER_hostname_resolve (int af,
+                                  struct GNUNET_TIME_Relative timeout,
+                                  GNUNET_RESOLVER_AddressCallback callback,
+                                  void *cls);
 
 
 /**
@@ -122,42 +118,37 @@ struct GNUNET_RESOLVER_RequestHandle *GNUNET_RESOLVER_hostname_resolve (int
  * @param hostname one of the names for the host, NULL
  *        on the last call to the callback
  */
-typedef void (*GNUNET_RESOLVER_HostnameCallback) (void *cls,
-                                                  const char *hostname);
+typedef void
+(*GNUNET_RESOLVER_HostnameCallback) (void *cls,
+                                     const char *hostname);
 
 /**
  * Get local fully qualified domain name
  *
  * @return local hostname, caller must free
  */
-char *GNUNET_RESOLVER_local_fqdn_get (void);
+char *
+GNUNET_RESOLVER_local_fqdn_get (void);
 
 
 /**
  * Perform a reverse DNS lookup.
  *
- * @param cfg configuration to use
  * @param sa host address
- * @param salen length of host address
- * @param do_resolve use GNUNET_NO to return numeric hostname
+ * @param salen length of @a sa
+ * @param do_resolve use #GNUNET_NO to return numeric hostname
  * @param timeout how long to try resolving
  * @param callback function to call with hostnames
- * @param cls closure for callback
+ * @param cls closure for @a callback
  * @return handle that can be used to cancel the request, NULL on error
  */
-struct GNUNET_RESOLVER_RequestHandle *GNUNET_RESOLVER_hostname_get (const struct
-                                                                    sockaddr
-                                                                    *sa,
-                                                                    socklen_t
-                                                                    salen,
-                                                                    int
-                                                                    do_resolve,
-                                                                    struct
-                                                                    GNUNET_TIME_Relative
-                                                                    timeout,
-                                                                    GNUNET_RESOLVER_HostnameCallback
-                                                                    callback,
-                                                                    void *cls);
+struct GNUNET_RESOLVER_RequestHandle *
+GNUNET_RESOLVER_hostname_get (const struct sockaddr *sa,
+                              socklen_t salen,
+                              int do_resolve,
+                              struct GNUNET_TIME_Relative timeout,
+                              GNUNET_RESOLVER_HostnameCallback callback,
+                              void *cls);
 
 
 /**
@@ -168,7 +159,8 @@ struct GNUNET_RESOLVER_RequestHandle *GNUNET_RESOLVER_hostname_get (const struct
  *
  * @param rh handle of request to cancel
  */
-void GNUNET_RESOLVER_request_cancel (struct GNUNET_RESOLVER_RequestHandle *rh);
+void
+GNUNET_RESOLVER_request_cancel (struct GNUNET_RESOLVER_RequestHandle *rh);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
@@ -178,6 +170,8 @@ void GNUNET_RESOLVER_request_cancel (struct GNUNET_RESOLVER_RequestHandle *rh);
 }
 #endif
 
+/** @} */ /* end of group resolver */
+
 /* ifndef GNUNET_RESOLVER_SERVICE_H */
 #endif
 /* end of gnunet_resolver_service.h */