ecore/ecore_con - improved documentation and added example.

Just ecore_con_init, shutdown and lookup documented for now.



SVN revision: 61050

legacy/ecore/doc/examples.dox

@@ -10,6 +10,7 @@
  * @li @ref ecore_event_example_c
  * @li @ref ecore_fd_handler_example_c
  * @li @ref ecore_poller_example_c
+ * @li @ref ecore_con_lookup_example_c
  *
  */
 
@@ -460,6 +461,39 @@
  * library.
  */
 
+/**
+ * @page ecore_con_lookup_example_c Ecore_Con - DNS lookup
+ *
+ * This is a very simple example that shows how to make a simple DNS lookup
+ * using ecore_con_lookup().
+ *
+ * It's possible to see in the beginning of the main function that we are using
+ * the arguments passed via command line. This is the address that we are going
+ * to make the DNS lookup on.
+ *
+ * The next step is to initialize the libraries, and just call
+ * ecore_con_lookup(). This function will get the string that contains the
+ * address to be resolved as first parameter, then a callback that will be
+ * called when the resolve stage is done, and finally a data pointer that will
+ * be passed to the callback.
+ *
+ * This function is asynchronous, and the callback will be called only on
+ * success. If there was an error during the resolve stage, there's no way to
+ * know about that. It's only possible to know about errors when setting up the
+ * lookup, by looking at the return code of the ecore_con_lookup() function.
+ *
+ * The callback @c _lookup_done_cb passed as argument to ecore_con_lookup() just
+ * prints the resolved canonical name, ip, address of the sockaddr structure,
+ * and the length of the socket address (in bytes).
+ *
+ * Finally, we start the main loop, and after that we finalize the libraries and
+ * exit.
+ *
+ * This is the code for this simple example:
+ *
+ * @include ecore_con_lookup_example.c
+ */
+
 /**
  * @example ecore_idler_example.c
  * This example shows when @ref Ecore_Idler, @ref Ecore_Idle_Enterer and @ref
@@ -506,7 +540,13 @@
 /**
  * @example ecore_fd_handler_gnutls_example.c
  * Shows how to use fd handlers.
-*/
+ */
+
+/**
+ * @example ecore_con_lookup_example.c
+ * Shows how to make a simple DNS lookup. See the complete example description
+ * at @ref @ecore_con_lookup_example_c
+ */
 
 /**
  * @page tutorial_ecore_pipe_gstreamer_example

legacy/ecore/src/examples/Makefile.am

@@ -5,12 +5,17 @@ pkglibdir = $(datadir)/$(PACKAGE)/examples
 AM_CPPFLAGS = \
 -I. \
 -I$(top_srcdir)/src/lib/ecore \
+-I$(top_srcdir)/src/lib/ecore_con \
 @GLIB_CFLAGS@ @EVIL_CFLAGS@ @EINA_CFLAGS@ @WIN32_CPPFLAGS@ @EFL_ECORE_BUILD@
 
-LDADD = \
+ECOREBASELDADD = \
 	$(top_builddir)/src/lib/ecore/libecore.la \
 	@dlopen_libs@ @EINA_LIBS@ @EVIL_LIBS@ @GLIB_LIBS@ @WIN32_LIBS@ @LTLIBINTL@ @EFL_PTHREAD_LIBS@ @rt_libs@ -lm
 
+
+LDADD = \
+	$(ECOREBASELDADD)
+
 SRCS = \
 	ecore_fd_handler_example.c \
 	ecore_poller_example.c \
@@ -19,6 +24,7 @@ SRCS = \
 	ecore_timer_example.c \
 	ecore_time_functions_example.c \
 	ecore_job_example.c \
+	ecore_con_lookup_example.c \
 	client_bench.c \
 	server_bench.c \
 	ecore_con_client_example.c \
@@ -46,6 +52,9 @@ pkglib_PROGRAMS += \
 	ecore_job_example \
 	ecore_timer_example \
 	ecore_time_functions_example \
-	ecore_pipe_simple_example
+	ecore_pipe_simple_example \
+	ecore_con_lookup_example
+
+ecore_con_lookup_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la
 endif
 

legacy/ecore/src/examples/ecore_con_lookup_example.c

@@ -0,0 +1,38 @@
+#include <stdio.h>
+#include <Ecore.h>
+#include <Ecore_Con.h>
+
+static void
+_lookup_done_cb(const char *canonname, const char *ip, struct sockaddr *addr, int addrlen, void *data)
+{
+    printf("canonname = %s\n", canonname);
+    printf("ip = %s\n", ip);
+    printf("addr = %p\n", addr);
+    printf("addrlen = %d\n", addrlen);
+}
+
+int main(int argc, const char *argv[])
+{
+   if (argc < 2)
+     {
+	printf("need one parameter: <address>\n");
+	return -1;
+     }
+
+   ecore_init();
+   ecore_con_init();
+
+   if (!ecore_con_lookup(argv[1], _lookup_done_cb, NULL))
+     {
+	printf("error when trying to start lookup for %s\n", argv[1]);
+	goto end;
+     }
+
+   ecore_main_loop_begin();
+
+end:
+   ecore_con_shutdown();
+   ecore_shutdown();
+
+   return 0;
+}

legacy/ecore/src/lib/ecore_con/Ecore_Con.h

@@ -395,6 +395,15 @@ EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
 /**
  * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
  *
+ * Utility functions that set up and shut down the Ecore Connection
+ * library.
+ *
+ * There's also ecore_con_lookup() that can be used to make simple asynchronous
+ * DNS lookups.
+ *
+ * A simple example of how to use these functions:
+ * @li @ref ecore_con_lookup_example_c
+ *
  * @{
  */
 
@@ -447,9 +456,38 @@ typedef enum _Ecore_Con_Type
    ECORE_CON_LOAD_CERT = (1 << 7)
 } Ecore_Con_Type;
 
+/**
+ * Initialises the Ecore_Con library.
+ * @return  Number of times the library has been initialised without being
+ *          shut down.
+ */
 EAPI int               ecore_con_init(void);
+
+/**
+ * Shuts down the Ecore_Con library.
+ * @return  Number of times the library has been initialised without being
+ *          shut down.
+ */
 EAPI int               ecore_con_shutdown(void);
 
+/**
+ * Do an asynchronous DNS lookup.
+ *
+ * @param name IP address or server name to translate.
+ * @param done_cb Callback to notify when done.
+ * @param data User data to be given to done_cb.
+ * @return EINA_TRUE if the request did not fail to be set up, EINA_FALSE if it
+ * failed.
+ *
+ * This function performs a DNS lookup on the hostname specified by @p name,
+ * then calls @p done_cb with the result and the @p data given as parameter.
+ * The result will be given to the @p done_cb as follows:
+ * @li @c canonname - the canonical name of the address
+ * @li @c ip - the resolved ip address
+ * @li @c addr - a pointer to the socket address
+ * @li @c addrlen - the length of the socket address, in bytes
+ * @li @c data - the data pointer given as parameter to ecore_con_lookup()
+ */
 EAPI Eina_Bool         ecore_con_lookup(const char *name,
                                             Ecore_Con_Dns_Cb done_cb,
                                             const void *data);

legacy/ecore/src/lib/ecore_con/ecore_con.c

@@ -115,19 +115,6 @@ static Eina_List *servers = NULL;
 static int _ecore_con_init_count = 0;
 int _ecore_con_log_dom = -1;
 
-/**
- * @addtogroup Ecore_Con_Lib_Group Ecore Connection Library Functions
- *
- * Utility functions that set up and shut down the Ecore Connection
- * library.
- * @{
- */
-
-/**
- * Initialises the Ecore_Con library.
- * @return  Number of times the library has been initialised without being
- *          shut down.
- */
 EAPI int
 ecore_con_init(void)
 {
@@ -173,11 +160,6 @@ ecore_con_init(void)
    return _ecore_con_init_count;
 }
 
-/**
- * Shuts down the Ecore_Con library.
- * @return  Number of times the library has been initialised without being
- *          shut down.
- */
 EAPI int
 ecore_con_shutdown(void)
 {
@@ -202,17 +184,6 @@ ecore_con_shutdown(void)
    return _ecore_con_init_count;
 }
 
-/**
- * Do an asynchronous DNS lookup.
- *
- * This function performs a DNS lookup on the hostname specified by @p name, then
- * calls @p done_cb with
- *
- * @param name IP address or server name to translate.
- * @param done_cb Callback to notify when done.
- * @param data User data to be given to done_cb.
- * @return EINA_TRUE if the request did not fail to be set up, EINA_FALSE if it failed.
- */
 EAPI Eina_Bool
 ecore_con_lookup(const char      *name,
                  Ecore_Con_Dns_Cb done_cb,
@@ -272,10 +243,6 @@ on_error:
    return EINA_FALSE;
 }
 
-/**
- * @}
- */
-
 /**
  * @addtogroup Ecore_Con_Server_Group Ecore Connection Server Functions
  *