aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/ecore_con/Ecore_Con.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/ecore_con/Ecore_Con.h')
-rw-r--r--src/lib/ecore_con/Ecore_Con.h1586
1 files changed, 855 insertions, 731 deletions
diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h
index 6cfea2eff3..a299c033a4 100644
--- a/src/lib/ecore_con/Ecore_Con.h
+++ b/src/lib/ecore_con/Ecore_Con.h
@@ -9,7 +9,6 @@
# include <netdb.h>
#endif
#include <Eina.h>
-#include <Eo.h>
#ifdef EAPI
# undef EAPI
@@ -38,12 +37,13 @@
#endif
/**
+ * @internal
* @defgroup Ecore_Con_Group Ecore_Con - Connection functions
- * @ingroup Ecore
+ * @ingroup Ecore_Group
*
* The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
- * for communications between programs using reliable sockets. It saves
- * the programmer from having to worry about file descriptors and waiting
+ * for communications between programs using reliable sockets. It saves
+ * you from having to worry about file descriptors and waiting
* for incoming connections.
*
* There are two main objects in the @c Ecore_Con library: the @c
@@ -70,138 +70,140 @@
/**
+ * @internal
* @defgroup Ecore_Con_Events_Group Ecore Connection Events Functions
* @ingroup Ecore_Con_Group
*
* @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
* @c Ecore_Con_Server, an event of this type is emitted, allowing the
- * retrieval of the client's ip with @ref ecore_con_client_ip_get and
+ * retrieval of the client's IP with @ref ecore_con_client_ip_get and
* associating data with the client using ecore_con_client_data_set.
* @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
- * @c Ecore_Con_Server, an event of this type is emitted. The contents of
+ * @c Ecore_Con_Server, an event of this type is emitted. The contents of
* the data with this event are variable, but if the client object in the data
* is non-null, it must be freed with @ref ecore_con_client_del.
* @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
* with @ref ecore_con_server_connect, an event of this type is emitted,
* allowing for data to be serialized and sent to the server using
- * @ref ecore_con_server_send. At this point, the http handshake has
+ * @ref ecore_con_server_send. At this point, the HTTP handshake has
* occurred.
* @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
* usually by the server connection being refused or dropped, an event of this
- * type is emitted. The contents of the data with this event are variable,
+ * type is emitted. The contents of the data with this event are variable,
* but if the server object in the data is non-null, it must be freed
* with @ref ecore_con_server_del.
* @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server
- * object and sends data, an event of this type is emitted. The data will contain both
- * the size and contents of the message sent by the client. It should be noted that
+ * object and sends data, an event of this type is emitted. The data contains both
+ * the size and contents of the message sent by the client. It should be noted that
* data within this object is transient, so it must be duplicated in order to be
- * retained. This event will continue to occur until the client has stopped sending its
- * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
+ * retained. This event continues to occur until the client has stopped sending its
+ * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
* been received in full, the client object must be freed with ecore_con_client_free.
* @li ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination
- * and receives data, an event of this type is emitted. The data will contain both
- * the size and contents of the message sent by the server. It should be noted that
+ * and receives data, an event of this type is emitted. The data contains both
+ * the size and contents of the message sent by the server. It should be noted that
* data within this object is transient, so it must be duplicated in order to be
- * retained. This event will continue to occur until the server has stopped sending its
- * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
+ * retained. This event continues to occur until the server has stopped sending its
+ * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
* been received in full, the server object must be freed with ecore_con_server_free.
*
*/
/**
+ * @internal
* @defgroup Ecore_Con_Buffer Ecore Connection Buffering
* @ingroup Ecore_Con_Group
- *
- * As Ecore_Con works on an event driven design, as data arrives, events will
- * be produced containing the data that arrived. It is up to the user of
+ *
+ * As Ecore_Con works on an event driven design, as data arrives, events are
+ * produced containing the data that arrived. It is up to the user of
* Ecore_Con to either parse as they go, append to a file to later parse the
- * whole file in one go, or append to memory to parse or handle later.
- *
- * To help with this Eina has some handy API's. The Eina_Binbuf and
- * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial
- * to handle buffers at runtime, without having to manage them. Eina_Binbuf
- * makes it possible to create, expand, reset and slice a blob of memory -
- * all via API. No system calls, no pointer manipulations and no size
+ * whole file in one go, or append to memory to parse or handle leter.
+ *
+ * To help with this, Eina has some handy API's. The Eina_Binbuf and
+ * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial
+ * to handle buffers at runtime, without having to manage them. Eina_Binbuf
+ * makes it possible to create, expand, reset and slice a blob of memory -
+ * all via API. No system calls, no pointer manipulations and no size
* calculation.
- *
- * Additional functions include adding content at specified byte positions in
- * the buffer, escaping the inputs, find and replace strings. This provides
+ *
+ * Additional functions include adding content at specified byte positions in
+ * the buffer, escaping the inputs, find and replace strings. This provides
* extreme flexibility to play around, with a dynamic blob of memory.
- *
+ *
* It is good to free it (using eina_binbuf_free()) after using it.
- *
+ *
* Eina_Binbuf compliments Ecore_Con use cases, where dynamic sizes of data
* arrive from the network (think http download in chunks). Using
* Eina_Binbuf provides enough flexibility to handle data as it arrives and
* to defer its processing until desired, without having to think about
* where to store the temporary data and how to manage its size.
- *
+ *
* An example of how to use these with Ecore_Con follows.
- *
+ *
* @code
* #include <Eina.h>
* #include <Ecore.h>
* #include <Ecore_Con.h>
- *
+ *
* static Eina_Bool
* data_callback(void *data, int type, void *event)
* {
* Ecore_Con_Event_Url_Data *url_data = event;
* if ( url_data->size > 0)
* {
- * // append data as it arrives - don't worry where or how it gets stored.
- * // Also don't worry about size, expanding, reallocing etc.
- * // just keep appending - size is automatically handled.
- *
+ * // Append data as it arrives - do not worry where or how it gets stored.
+ * // Also do not worry about size, expanding, reallocing etc.
+ * // Just keep appending - size is automatically handled.
+ *
* eina_binbuf_append_length(data, url_data->data, url_data->size);
- *
+ *
* fprintf(stderr, "Appended %d \n", url_data->size);
* }
* return EINA_TRUE;
* }
- *
- *
- *
+ *
+ *
+ *
* static Eina_Bool
* completion_callback(void *data, int type, void *event)
* {
* Ecore_Con_Event_Url_Complete *url_complete = event;
* printf("download completed with status code: %d\n", url_complete->status);
- *
- * // get the data back from Eina_Binbuf
+ *
+ * // Get the data back from Eina_Binbuf
* char *ptr = eina_binbuf_string_get(data);
* size_t size = eina_binbuf_length_get(data);
- *
- * // process data as required (write to file)
+ *
+ * // Process data as required (write to file)
* fprintf(stderr, "Size of data = %d bytes\n", size);
* int fd = open("./elm.png", O_CREAT);
* write(fd, ptr, size);
* close(fd);
- *
- * // free it when done.
+ *
+ * // Free it when done.
* eina_binbuf_free(data);
- *
+ *
* ecore_main_loop_quit();
- *
+ *
* return EINA_TRUE;
* }
- *
- *
+ *
+ *
* int
* main(int argc, char **argv)
* {
- *
+ *
* const char *url = "http://www.enlightenment.org/p/index/d/logo.png";
- *
+ *
* ecore_init();
* ecore_con_init();
* ecore_con_url_init();
- *
- *
+ *
+ *
* // This is single additional line to manage dynamic network data.
* Eina_Binbuf *data = eina_binbuf_new();
* Ecore_Con_Url *url_con = ecore_con_url_new(url);
- *
+ *
* ecore_event_handler_add(ECORE_CON_EVENT_URL_COMPLETE,
* completion_callback,
* data);
@@ -209,7 +211,7 @@
* data_callback,
* data);
* ecore_con_url_get(url_con);
- *
+ *
* ecore_main_loop_begin();
* return 0;
* }
@@ -222,376 +224,341 @@ extern "C" {
#define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
#define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
-typedef Eo Ecore_Con;
/**
- * @typedef Ecore_Con_Socks
- * An object representing a SOCKS proxy
- * @ingroup Ecore_Con_Socks_Group
- * @since 1.2
+ * @typedef Ecore_Con_Server
+ * @brief The structure type containing a connection handle to a server.
+ * @ingroup Ecore_Con_Server_Group
*/
-typedef struct Ecore_Con_Socks Ecore_Con_Socks;
+typedef struct _Ecore_Con_Server Ecore_Con_Server;
/**
- * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
- * @ingroup Ecore_Con_Group
- *
- * 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.
+ * @typedef Ecore_Con_Client
+ * @brief The structure type containing a connection handle to a client.
+ * @ingroup Ecore_Con_Client_Group
+ */
+typedef struct _Ecore_Con_Client Ecore_Con_Client;
+
+/**
+ * @typedef Ecore_Con_Socks
+ * @brief The structure type containing an object representing a SOCKS proxy.
*
- * A simple example of how to use these functions:
- * @li @ref ecore_con_lookup_example_c
+ * @since 1.2
*
- * @{
+ * @ingroup Ecore_Con_Socks_Group
*/
+typedef struct Ecore_Con_Socks Ecore_Con_Socks;
/**
- * @typedef Ecore_Con_Type
- * @enum _Ecore_Con_Type
- * Types for an ecore_con client/server object. A correct way to set this type is
- * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
- * and LOAD_CERT if the previously loaded certificate should be used.
- * @code
- * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
- * @endcode
- * @ingroup Ecore_Con_Server_Group
+ * @typedef Ecore_Con_Url
+ * @brief The structure type containing a handle to an HTTP upload/download object.
+ * @ingroup Ecore_Con_Url_Group
*/
-typedef enum _Ecore_Con_Type
-{
- /** Socket in ~/.ecore */
- ECORE_CON_LOCAL_USER = 0,
- /** Socket in /tmp */
- ECORE_CON_LOCAL_SYSTEM = 1,
- /** Abstract socket */
- ECORE_CON_LOCAL_ABSTRACT = 2,
- /** Remote server using TCP */
- ECORE_CON_REMOTE_TCP = 3,
- /** Remote multicast server */
- ECORE_CON_REMOTE_MCAST = 4,
- /** Remote server using UDP */
- ECORE_CON_REMOTE_UDP = 5,
- /** Remote broadcast using UDP */
- ECORE_CON_REMOTE_BROADCAST = 6,
- /** Remote connection sending packets immediately */
- ECORE_CON_REMOTE_NODELAY = 7,
- /** Remote connection sending data in large chunks
- * @note Only available on Linux
- * @since 1.2
- */
- ECORE_CON_REMOTE_CORK = 8,
- /** Use SSL2: UNSUPPORTED. **/
- ECORE_CON_USE_SSL2 = (1 << 4),
- /** Use SSL3 */
- ECORE_CON_USE_SSL3 = (1 << 5),
- /** Use TLS */
- ECORE_CON_USE_TLS = (1 << 6),
- /** Use both TLS and SSL3 */
- ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
- /** Attempt to use the loaded certificate */
- ECORE_CON_LOAD_CERT = (1 << 7),
- /** Disable all types of proxy on the server
- * @note Only functional for clients
- * @since 1.2
- */
- ECORE_CON_NO_PROXY = (1 << 8),
- ECORE_CON_SOCKET_ACTIVATE = (1 << 9)
-} Ecore_Con_Type;
-
-/** @} */
+typedef struct _Ecore_Con_Url Ecore_Con_Url;
-#ifndef EFL_NOLEGACY_API_SUPPORT
-#include "Ecore_Con_Legacy.h"
-#endif
-#ifdef EFL_EO_API_SUPPORT
-#include "Ecore_Con_Eo.h"
-#endif
/**
+ * @internal
* @addtogroup Ecore_Con_Events_Group
+ *
* @{
*/
/**
* @typedef Ecore_Con_Event_Client_Add
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event
*/
typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
/**
* @typedef Ecore_Con_Event_Client_Upgrade
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Upgrade Ecore_Con_Event_Client_Upgrade;
/**
* @typedef Ecore_Con_Event_Client_Del
- * Used as the @p data param for the corresponding event
+ * @brief The structure type containing a connection used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
/**
* @typedef Ecore_Con_Event_Client_Error
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Error Ecore_Con_Event_Client_Error;
/**
* @typedef Ecore_Con_Event_Server_Add
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
/**
* @typedef Ecore_Con_Event_Server_Upgrade
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Upgrade Ecore_Con_Event_Server_Upgrade;
/**
* @typedef Ecore_Con_Event_Server_Del
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
/**
* @typedef Ecore_Con_Event_Server_Error
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Error Ecore_Con_Event_Server_Error;
/**
* @typedef Ecore_Con_Event_Client_Data
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
/**
* @typedef Ecore_Con_Event_Server_Data
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
/**
* @typedef Ecore_Con_Event_Client_Write
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Write Ecore_Con_Event_Client_Write;
/**
* @typedef Ecore_Con_Event_Server_Write
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Write Ecore_Con_Event_Server_Write;
/**
* @typedef Ecore_Con_Event_Proxy_Bind
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.2
*/
typedef struct _Ecore_Con_Event_Proxy_Bind Ecore_Con_Event_Proxy_Bind;
/**
* @typedef Ecore_Con_Event_Url_Data
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
/**
* @typedef Ecore_Con_Event_Url_Complete
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
/**
* @typedef Ecore_Con_Event_Url_Progress
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Add
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event.
*/
struct _Ecore_Con_Event_Client_Add
{
- Ecore_Con_Client *client; /**< the client that connected */
+ Ecore_Con_Client *client; /** the client that connected */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Upgrade
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event.
* @since 1.1
*/
struct _Ecore_Con_Event_Client_Upgrade
{
- Ecore_Con_Client *client; /**< the client that completed handshake */
+ Ecore_Con_Client *client; /** The client that completed handshake */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Del
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event.
*/
struct _Ecore_Con_Event_Client_Del
{
- Ecore_Con_Client *client; /**< the client that was lost */
+ Ecore_Con_Client *client; /** The client that was lost */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Error
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event.
*/
struct _Ecore_Con_Event_Client_Error
{
- Ecore_Con_Client *client; /**< the client for which an error occurred */
- char *error; /**< the error string describing what happened */
+ Ecore_Con_Client *client; /** The client for which an error occurred */
+ char *error; /**< The error string describing what happened */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Add
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_ADD event.
*/
struct _Ecore_Con_Event_Server_Add
{
- Ecore_Con_Server *server; /**< the server that was connected to */
+ Ecore_Con_Server *server; /** The server that is connected to */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Upgrade
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event.
* @since 1.1
*/
struct _Ecore_Con_Event_Server_Upgrade
{
- Ecore_Con_Server *server; /**< the server that was connected to */
+ Ecore_Con_Server *server; /** The server that is connected to */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Del
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_DEL event.
*/
struct _Ecore_Con_Event_Server_Del
{
- Ecore_Con_Server *server; /**< the client that was lost */
+ Ecore_Con_Server *server; /** The client that is lost */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Error
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event.
*/
struct _Ecore_Con_Event_Server_Error
{
- Ecore_Con_Server *server; /**< the server for which an error occurred */
- char *error; /**< the error string describing what happened */
+ Ecore_Con_Server *server; /** The server for which an error occurred */
+ char *error; /**< The error string describing what happened */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Data
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event.
*/
struct _Ecore_Con_Event_Client_Data
{
- Ecore_Con_Client *client; /**< the client that connected */
- void *data; /**< the data that the client sent */
- int size; /**< the length of the data sent */
+ Ecore_Con_Client *client; /**< The client that connected */
+ void *data; /**< The data that the client sent */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Data
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_DATA event.
*/
struct _Ecore_Con_Event_Server_Data
{
- Ecore_Con_Server *server; /**< the server that was connected to */
- void *data; /**< the data that the server sent */
- int size; /**< the length of the data sent */
+ Ecore_Con_Server *server; /**< The server that is connected to */
+ void *data; /**< The data that the server sent */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Write
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event.
*/
struct _Ecore_Con_Event_Client_Write
{
- Ecore_Con_Client *client; /**< the client that connected */
- int size; /**< the length of the data sent */
+ Ecore_Con_Client *client; /**< The client that connected */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Write
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event.
*/
struct _Ecore_Con_Event_Server_Write
{
- Ecore_Con_Server *server; /**< the server that was connected to */
- int size; /**< the length of the data sent */
+ Ecore_Con_Server *server; /**< The server that is connected to */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Proxy_Bind
- * Used as the @p data param for the @ref ECORE_CON_EVENT_PROXY_BIND event
- * @ingroup Ecore_Con_Socks_Group
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_PROXY_BIND event.
+ *
* @since 1.2
+ * @ingroup Ecore_Con_Socks_Group
*/
struct _Ecore_Con_Event_Proxy_Bind
{
- Ecore_Con_Server *server; /**< the server object connected to the proxy */
- const char *ip; /**< the proxy-bound ip address */
- int port; /**< the proxy-bound port */
+ Ecore_Con_Server *server; /**< The server object connected to the proxy */
+ const char *ip; /**< The proxy-bound ip address */
+ int port; /**< The proxy-bound port */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Url_Data
- * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_DATA event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Data
{
- Ecore_Con_Url *url_con; /**< a pointer to the connection object */
- int size; /**< the size of the current received data (in bytes) */
- unsigned char data[1]; /**< the data received on this event */
+ Ecore_Con_Url *url_con; /**< A pointer to the connection object */
+ int size; /**< The size of the current received data (in bytes) */
+ unsigned char data[1]; /**< The data received on this event */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Url_Complete
- * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Complete
{
- Ecore_Con_Url *url_con; /**< a pointer to the connection object */
+ Ecore_Con_Url *url_con; /**< A pointer to the connection object */
int status; /**< HTTP status code of the operation (200, 404, 401, etc.) */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Url_Progress
- * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Progress
{
- Ecore_Con_Url *url_con; /**< a pointer to the connection object */
+ Ecore_Con_Url *url_con; /**< A pointer to the connection object */
struct
{
- double total; /**< total size of the downloading data (in bytes) */
- double now; /**< current size of the downloading data (in bytes) */
- } down; /**< download info */
+ double total; /**< Total size of the downloading data (in bytes) */
+ double now; /**< Current size of the downloading data (in bytes) */
+ } down; /**< Download info */
struct
{
- double total; /**< total size of the uploading data (in bytes) */
- double now; /**< current size of the uploading data (in bytes) */
- } up; /**< upload info */
+ double total; /**< Total size of the uploading data (in bytes) */
+ double now; /**< Current size of the uploading data (in bytes) */
+ } up; /**< Upload info */
};
/** A client has connected to the server */
@@ -606,9 +573,9 @@ EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR;
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_CLIENT_UPGRADE;
-/** A server was created */
+/** A server is created */
EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
-/** A server connection was lost */
+/** A server connection is lost */
EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
/** A server experienced an error
* @since 1.1
@@ -646,36 +613,127 @@ EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
*/
/**
- * @addtogroup Ecore_Con_Events_Group Ecore_Con_Lib_Group
+ * @internal
+ * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
* @ingroup Ecore_Con_Group
*
+ * @brief This group provides utility functions that set up and shut down the Ecore Connection
+ * library.
+ *
+ * There is also ecore_con_lookup() that can be used to make simple asynchronous
+ * DNS lookups.
+ *
* @{
*/
/**
- * Initialises the Ecore_Con library.
- * @return Number of times the library has been initialised without being
- * shut down.
+ * @typedef Ecore_Con_Dns_Cb
+ * A callback type for use with @ref ecore_con_lookup.
+ */
+typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
+ const char *ip,
+ struct sockaddr *addr,
+ int addrlen,
+ void *data);
+
+/**
+ * @typedef Ecore_Con_Type
+ * @enum _Ecore_Con_Type
+ * @brief Enumeration of the types for an ecore_con client/server object. A correct way to set this type is
+ * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
+ * and LOAD_CERT if the previously loaded certificate should be used.
+ * @code
+ * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
+ * @endcode
+ * @ingroup Ecore_Con_Server_Group
+ */
+typedef enum _Ecore_Con_Type
+{
+ /** Socket in ~/.ecore */
+ ECORE_CON_LOCAL_USER = 0,
+ /** Socket in /tmp */
+ ECORE_CON_LOCAL_SYSTEM = 1,
+ /** Abstract socket */
+ ECORE_CON_LOCAL_ABSTRACT = 2,
+ /** Remote server using TCP */
+ ECORE_CON_REMOTE_TCP = 3,
+ /** Remote multicast server */
+ ECORE_CON_REMOTE_MCAST = 4,
+ /** Remote server using UDP */
+ ECORE_CON_REMOTE_UDP = 5,
+ /** Remote broadcast using UDP */
+ ECORE_CON_REMOTE_BROADCAST = 6,
+ /** Remote connection sending packets immediately */
+ ECORE_CON_REMOTE_NODELAY = 7,
+ /** Remote connection sending data in large chunks
+ * @note Only available on Linux
+ * @since 1.2
+ */
+ ECORE_CON_REMOTE_CORK = 8,
+ /** Use SSL2: UNSUPPORTED. **/
+ ECORE_CON_USE_SSL2 = (1 << 4),
+ /** Use SSL3 */
+ ECORE_CON_USE_SSL3 = (1 << 5),
+ /** Use TLS */
+ ECORE_CON_USE_TLS = (1 << 6),
+ /** Use both TLS and SSL3 */
+ ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
+ /** Attempt to use the loaded certificate */
+ ECORE_CON_LOAD_CERT = (1 << 7),
+ /** Disable all types of proxy on the server
+ * @note Only functional for clients
+ * @since 1.2
+ */
+ ECORE_CON_NO_PROXY = (1 << 8)
+} Ecore_Con_Type;
+
+/**
+ * @brief Initialises the Ecore_Con library.
*
- * @note This function already calls ecore_init() internally, so you don't need
- * to call it explicitly.
+ * @remarks This function already calls ecore_init() internally. So you do not need
+ * to call it explicitly.
+ * @return The 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.
- * @note This function already calls ecore_shutdown() internally, so you don't
- * need to call it explicitly unless you called ecore_init() explicitly too.
+ * @brief Shuts down the Ecore_Con library.
+ *
+ * @remarks This function already calls ecore_shutdown() internally. So you do not
+ * need to call it explicitly unless you called ecore_init() explicitly too.
+ *
+ * @return The number of times the library has been initialised without being shut down
*/
EAPI int ecore_con_shutdown(void);
/**
+ * @brief Does an asynchronous DNS lookup.
+ *
+ * @details This function performs a DNS lookup on the hostname specified by @a name,
+ * then calls @a done_cb with the result and the @a data given as parameter.
+ * The result is given to the @a 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()
+ *
+ * @param[in] name The IP address or server name to translate
+ * @param[in] done_cb The callback to notify when done
+ * @param[in] data The user data to be given to done_cb
+ * @return @c EINA_TRUE if the request did not fail to be set up, \n
+ * otherwise @c EINA_FALSE if it failed
+ */
+EAPI Eina_Bool ecore_con_lookup(const char *name,
+ Ecore_Con_Dns_Cb done_cb,
+ const void *data);
+
+/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
* @ingroup Ecore_Con_Group
*
@@ -713,18 +771,19 @@ EAPI void ecore_con_socks_apply_once(Ecore_Con_Socks *ecs);
EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
/**
+ * @internal
* @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
* @ingroup Ecore_Con_Group
*
- * This group of functions is applied to an @ref Ecore_Con_Server object. It
- * doesn't mean that they should be used in the server application, but on the
- * server object. In fact, most of them should be used in the client
- * application, when retrieving information or sending data.
+ * @brief This group of functions is applied to an @ref Ecore_Con_Server object. It
+ * does not mean that they should be used in the server application, but on the
+ * server object. In fact, most of them should be used in the client
+ * application, when retrieving information or sending data.
*
* Setting up a server is very simple: you just need to start it with
* ecore_con_server_add() and setup some callbacks to the events
* @ref ECORE_CON_EVENT_CLIENT_ADD, @ref ECORE_CON_EVENT_CLIENT_DEL and
- * @ref ECORE_CON_EVENT_CLIENT_DATA, that will be called when a client is
+ * @ref ECORE_CON_EVENT_CLIENT_DATA, that is called when a client is
* communicating with the server:
*
* @code
@@ -739,7 +798,7 @@ EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
* @endcode
*
* The function ecore_con_server_connect() can be used to write a client that
- * connects to a server. The resulting code will be very similar to the server
+ * connects to a server. The resulting code is very similar to the server
* code:
*
* @code
@@ -754,180 +813,194 @@ EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
* @endcode
*
* After these two pieces of code are executed, respectively, in the server and
- * client code, the server will be up and running and the client will try to
+ * client code, the server is up and running and the client tries to
* connect to it. The connection, with its subsequent messages being sent from
* server to client and client to server, can be represented in the following
* sequence diagram:
*
* @htmlonly
- * <img src="ecore_con-client-server.png" style="max-width: 400px"/>
* <a href="ecore_con-client-server.png">Full size</a>
* @endhtmlonly
*
+ * @image html ecore_con-client-server.png
* @image rtf ecore_con-client-server.png
- * @image latex ecore_con-client-server.eps width=\textwidth
+ * @image latex ecore_con-client-server.eps "ecore con client server" width=\textwidth
*
- * Please notice the important difference between these two codes: the first is
+ * Note the important difference between these two codes: the first is
* used for writing a @b server, while the second should be used for writing a
* @b client.
*
* A reference for the @c client functions can be found at @ref
* Ecore_Con_Client_Group.
*
- * Examples of usage for this API can be found here:
- * @li @ref ecore_con_server_simple_example_c
- * @li @ref ecore_con_client_simple_example_c
- *
* @{
*/
/**
- * Creates a server to listen for connections.
+ * @brief Creates a server to listen for connections.
*
- * @param type The connection type.
- * @param name Name to associate with the socket. It is used when
- * generating the socket name of a Unix socket, or for
- * determining what host to listen on for TCP sockets.
- * @c NULL will not be accepted.
- * @param port Number to identify socket. When a Unix socket is used,
- * it becomes part of the socket name. When a TCP socket
- * is used, it is used as the TCP port.
- * @param data Data to associate with the created Ecore_Con_Server
- * object.
- * @return A new Ecore_Con_Server.
+ * @remarks The socket on which the server listens depends on the connection type:
+ * @li If @a type is @c ECORE_CON_LOCAL_USER, the server listens on
+ * the Unix socket "~/.ecore/[name]/[port]".
+ * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server listens
+ * on Unix socket "/tmp/.ecore_service|[name]|[port]".
+ * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server listens
+ * on TCP port @c port.
*
- * The socket on which the server listens depends on the connection
- * type:
- * @li If @a type is @c ECORE_CON_LOCAL_USER, the server will listen on
- * the Unix socket "~/.ecore/[name]/[port]".
- * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen
- * on Unix socket "/tmp/.ecore_service|[name]|[port]".
- * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server will listen
- * on TCP port @c port.
+ * @remarks More information about the @a type can be found at @ref _Ecore_Con_Type.
*
- * More information about the @p type can be found at @ref _Ecore_Con_Type.
+ * @remarks The @a data parameter can be fetched later using ecore_con_server_data_get()
+ * or changed with ecore_con_server_data_set().
*
- * The @p data parameter can be fetched later using ecore_con_server_data_get()
- * or changed with ecore_con_server_data_set().
+ * @param[in] type The connection type
+ * @param[in] name The name to associate with the socket \n
+ * It is used when generating the socket name of a Unix socket, or for
+ * determining what host to listen on for TCP sockets.
+ * @c NULL is not accepted.
+ * @param[in] port The number to identify socket \n
+ * When a Unix socket is used, it becomes part of the socket name.
+ * When a TCP socket is used, it is used as the TCP port.
+ * @param[in] data The data to associate with the created Ecore_Con_Server object
+ * @return A new Ecore_Con_Server
*/
EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
const char *name, int port,
const void *data);
/**
- * Creates a connection to the specified server and returns an associated object.
+ * @brief Creates a connection to the specified server and returns an associated object.
*
- * @param type The connection type.
- * @param name Name used when determining what socket to connect to.
- * It is used to generate the socket name when the socket
- * is a Unix socket. It is used as the hostname when
- * connecting with a TCP socket.
- * @param port Number to identify the socket to connect to. Used when
- * generating the socket name for a Unix socket, or as the
- * TCP port when connecting to a TCP socket.
- * @param data Data to associate with the created Ecore_Con_Server
- * object.
- * @return A new Ecore_Con_Server.
+ * @remarks The socket to which the connection is made depends on the connection type:
+ * @li If @a type is @c ECORE_CON_LOCAL_USER, the function
+ * connects to the server at the Unix socket
+ * "~/.ecore/[name]/[port]".
+ * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function
+ * connects to the server at the Unix socket
+ * "/tmp/.ecore_service|[name]|[port]".
+ * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function
+ * connects to the server at the TCP port "[name]:[port]".
*
- * The socket to which the connection is made depends on the connection type:
- * @li If @a type is @c ECORE_CON_LOCAL_USER, the function will
- * connect to the server at the Unix socket
- * "~/.ecore/[name]/[port]".
- * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function will
- * connect to the server at the Unix socket
- * "/tmp/.ecore_service|[name]|[port]".
- * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function will
- * connect to the server at the TCP port "[name]:[port]".
+ * @remarks More information about the @a type can be found at @ref _Ecore_Con_Type.
*
- * More information about the @p type can be found at @ref _Ecore_Con_Type.
+ * @remarks This function does not block. It either succeeds, or fails due to invalid
+ * parameters, failed memory allocation, etc., returning @c NULL in that case.
*
- * This function won't block. It will either succeed, or fail due to invalid
- * parameters, failed memory allocation, etc., returning @c NULL on that case.
+ * @remarks However, even if this call returns a valid @ref Ecore_Con_Server, the
+ * connection is only successfully completed if an event of type
+ * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
+ * @ref ECORE_CON_EVENT_SERVER_DEL is received.
*
- * However, even if this call returns a valid @ref Ecore_Con_Server, the
- * connection will only be successfully completed if an event of type
- * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
- * @ref ECORE_CON_EVENT_SERVER_DEL will be received.
+ * @remarks The @a data parameter can be fetched later using ecore_con_server_data_get()
+ * or changed with ecore_con_server_data_set().
*
- * The @p data parameter can be fetched later using ecore_con_server_data_get()
- * or changed with ecore_con_server_data_set().
+ * @param[in] type The connection type
+ * @param[in] name The name used when determining what socket to connect to \n
+ * It is used to generate the socket name when the socket
+ * is a Unix socket. It is used as the hostname when
+ * connecting with a TCP socket.
+ * @param[in] port The number to identify the socket to connect to \n
+ * It is used when generating the socket name for a Unix socket,
+ * or as the TCP port when connecting to a TCP socket.
+ * @param[in] data The data to associate with the created Ecore_Con_Server object
+ * @return A new Ecore_Con_Server
*/
EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
const char *name, int port,
const void *data);
/**
- * Closes the connection and frees the given server.
+ * @brief Closes the connection and frees the given server.
*
- * @param svr The given server.
- * @return Data associated with the server when it was created.
+ * @remarks All the clients connected to this server is disconnected.
*
- * All the clients connected to this server will be disconnected.
+ * @param[in] svr The given server
+ * @return The data associated with the server when it is created
*
* @see ecore_con_server_add, ecore_con_server_connect
*/
EAPI void * ecore_con_server_del(Ecore_Con_Server *svr);
/**
- * Retrieves the data associated with the given server.
+ * @brief Gets the data associated with the given server.
*
- * @param svr The given server.
- * @return The associated data.
+ * @param[in] svr The given server
+ * @return The associated data
*
* @see ecore_con_server_data_set()
*/
EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
/**
- * Sets the data associated with the given server.
+ * @brief Sets the data associated with the given server.
*
- * @param svr The given server.
- * @param data The data to associate with @p svr
- * @return The previously associated data, if any.
+ * @param[in] svr The given server
+ * @param[in] data The data to associate with @a svr
+ * @return The previously associated data, if any
*
* @see ecore_con_server_data_get()
*/
EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr,
void *data);
/**
- * Retrieves whether the given server is currently connected.
+ * @brief Checks whether the given server is currently connected.
+ *
+ * @param[in] svr The given server
+ * @return @c EINA_TRUE if the server is connected, \n
+ * otherwise @c EINA_FALSE if the server is not connected
+ */
+EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr);
+/**
+ * @brief Gets the current list of clients.
+ *
+ * @remarks Each node in the returned list points to an @ref Ecore_Con_Client. This list
+ * cannot be modified or freed. It can also change if new clients are connected
+ * or disconnected, and becomes invalid when the server is deleted or freed.
+ *
+ * @param[in] svr The given server
+ * @return The list of clients on this server
+ */
+EAPI const Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr);
+
+/**
+ * @brief Gets the name of server.
+ *
+ * @remarks The name returned is the name used to connect on this server.
*
- * @param svr The given server.
- * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise.
+ * @param[in] svr The given server
+ * @return The name of the server
*/
-EAPI Eina_Bool ecore_con_server_connected_get(const Ecore_Con_Server *svr);
+EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr);
/**
- * Retrieves the server port in use.
+ * @brief Gets the server port in use.
*
- * @param svr The given server.
- * @return The server port in use.
+ * @remarks The port where the server is listening for connections.
*
- * The port where the server is listening for connections.
+ * @param[in] svr The given server
+ * @return The server port in use
*/
-EAPI int ecore_con_server_port_get(const Ecore_Con_Server *svr);
+EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr);
/**
- * @brief Check how long a server has been connected
+ * @brief Checks how long a server has been connected.
*
- * @param svr The server to check
- * @return The total time, in seconds, that the server has been
- * connected/running
+ * @details This function is used to find out the time that has been elapsed since
+ * ecore_con_server_add() succeeded.
*
- * This function is used to find out the time that has been elapsed since
- * ecore_con_server_add() succeeded.
+ * @param[in] svr The server to check
+ * @return The total time, in seconds, that the server has been connected or running
*/
-EAPI double ecore_con_server_uptime_get(const Ecore_Con_Server *svr);
+EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
/**
- * Sends the given data to the given server.
+ * @brief Sends the given data to the given server.
*
- * @param svr The given server.
- * @param data The given data.
- * @param size Length of the data, in bytes, to send.
- * @return The number of bytes sent. @c 0 will be returned if there is an
- * error.
+ * @details This function sends the given data to the server as soon as the program
+ * is back to the main loop. Thus, this function returns immediately
+ * (non-blocking). If the data needs to be sent @b now, call
+ * ecore_con_server_flush() after this one.
*
- * This function will send the given data to the server as soon as the program
- * is back to the main loop. Thus, this function returns immediately
- * (non-blocking). If the data needs to be sent @b now, call
- * ecore_con_server_flush() after this one.
+ * @param[in] svr The given server
+ * @param[in] data The given data
+ * @param[in] size The length of the data, in bytes, to send
+ * @return The number of bytes sent, \n
+ * otherwise @c 0 if there is an error
*
* @see ecore_con_client_send()
* @see ecore_con_server_flush()
@@ -936,120 +1009,121 @@ EAPI int ecore_con_server_send(Ecore_Con_Server *svr,
const void *data,
int size);
/**
- * Sets a limit on the number of clients that can be handled concurrently
- * by the given server, and a policy on what to do if excess clients try to
- * connect.
- *
- * @param svr The given server.
- * @param client_limit The maximum number of clients to handle
- * concurrently. -1 means unlimited (default). 0
- * effectively disables the server.
- * @param reject_excess_clients Set to 1 to automatically disconnect
- * excess clients as soon as they connect if you are
- * already handling client_limit clients. Set to 0
- * (default) to just hold off on the "accept()"
- * system call until the number of active clients
- * drops. This causes the kernel to queue up to 4096
- * connections (or your kernel's limit, whichever is
- * lower).
- *
- * Beware that if you set this once ecore is already running, you may
- * already have pending CLIENT_ADD events in your event queue. Those
- * clients have already connected and will not be affected by this call.
- * Only clients subsequently trying to connect will be affected.
+ * @brief Sets a limit on the number of clients that can be handled concurrently
+ * by the given server, and a policy on what to do if excess clients try to
+ * connect.
+ *
+ * @remarks Beware that if you set this once, ecore is already running. You may
+ * already have pending CLIENT_ADD events in your event queue. Those
+ * clients have already connected and is not affected by this call.
+ * Only clients subsequently trying to connect is affected.
+ *
+ * @param[in] svr The given server
+ * @param[in] client_limit The maximum number of clients to handle concurrently \n
+ * @c -1 means unlimited (default), @c 0 effectively disables the server.
+ * @param[in] reject_excess_clients Set to @c 1 to automatically disconnect excess clients
+ * as soon as they connect if you are already handling client_limit clients \n
+ * otherwise set to @c 0 (default) to just hold off on the "accept()"
+ * system call until the number of active clients drops \n
+ * This causes the kernel to queue up to 4096
+ * connections (or your kernel's limit, whichever is lower).
*/
EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
int client_limit,
char reject_excess_clients);
/**
- * Gets the IP address of a server that has been connected to.
+ * @brief Gets the IP address of a server that has been connected to.
*
- * @param svr The given server.
+ * @param[in] svr The given server
* @return A pointer to an internal string that contains the IP address of
- * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
+ * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation \n
* This string should not be modified or trusted to stay valid after
- * deletion for the @p svr object. If no IP is known @c NULL is
- * returned.
+ * deletion for the @a svr object. If no IP is known, @c NULL is returned.
*/
-EAPI const char * ecore_con_server_ip_get(const Ecore_Con_Server *svr);
+EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr);
/**
- * Flushes all pending data to the given server.
+ * @brief Flushes all pending data to the given server.
*
- * @param svr The given server.
+ * @details This function blocks until all data is sent to the server.
*
- * This function will block until all data is sent to the server.
+ * @param[in] svr The given server
*
* @see ecore_con_server_send()
* @see ecore_con_client_flush()
*/
EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
/**
- * Set the default time after which an inactive client will be disconnected
+ * @brief Sets the default time after which an inactive client is disconnected.
*
- * @param svr The server object
- * @param timeout The timeout, in seconds, to disconnect after
+ * @details This function is used by the server to set the default idle timeout on
+ * clients. If the any of the clients becomes idle for a time higher than this
+ * value, it is disconnected. A value of < @c 1 disables the idle timeout.
*
- * This function is used by the server to set the default idle timeout on
- * clients. If the any of the clients becomes idle for a time higher than this
- * value, it will be disconnected. A value of < 1 disables the idle timeout.
+ * @remarks This timeout is not affected by the one set by
+ * ecore_con_client_timeout_set(). A client is disconnected whenever the
+ * client or the server timeout is reached. That means, the lower timeout value
+ * is used for that client if ecore_con_client_timeout_set() is used on it.
*
- * This timeout is not affected by the one set by
- * ecore_con_client_timeout_set(). A client will be disconnected whenever the
- * client or the server timeout is reached. That means, the lower timeout value
- * will be used for that client if ecore_con_client_timeout_set() is used on it.
+ * @param[in] svr The server object
+ * @param[in] timeout The timeout, in seconds, to disconnect after
*
* @see ecore_con_server_timeout_get()
* @see ecore_con_client_timeout_set()
*/
EAPI void ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout);
/**
- * Get the default time after which an inactive client will be disconnected
+ * @brief Gets the default time after which an inactive client is disconnected.
*
- * @param svr The server object
- * @return The timeout, in seconds, to disconnect after
+ * @details This function is used to get the idle timeout for clients. A value of < @c 1
+ * means the idle timeout is disabled.
*
- * This function is used to get the idle timeout for clients. A value of < 1
- * means the idle timeout is disabled.
+ * @param[in] svr The server object
+ * @return The timeout, in seconds, to disconnect after
*
* @see ecore_con_server_timeout_set()
* @see ecore_con_client_timeout_get()
*/
-EAPI double ecore_con_server_timeout_get(const Ecore_Con_Server *svr);
+EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr);
/**
- * Get the fd that the server is connected to
+ * @brief Get the fd that the server is connected to.
*
- * @param svr The server object
- * @return The fd, or -1 on failure
+ * @details This function returns the fd which is used by the underlying server connection.
+ * It should not be tampered with unless you REALLY know what you are doing.
+ * @since 1.1
*
- * This function returns the fd which is used by the underlying server connection.
- * It should not be tampered with unless you REALLY know what you are doing.
- * @note This function is only valid for servers created with ecore_con_server_connect()
- * @warning Seriously. Don't use this unless you know what you are doing.
- * @since 1.1
+ * @remarks This function is only valid for servers created with ecore_con_server_connect()
+ * @remarks Do not use this unless you know what you are doing.
+ *
+ * @param[in] svr The server object
+ * @return The fd, \n
+ * otherwise @c -1 on failure
*/
-EAPI int ecore_con_server_fd_get(const Ecore_Con_Server *svr);
+EAPI int ecore_con_server_fd_get(Ecore_Con_Server *svr);
/**
- * Get the fd that the client is connected to
+ * @brief Gets the fd that the client is connected to.
*
- * @param cl The client object
- * @return The fd, or -1 on failure
+ * @details This function returns the fd which is used by the underlying client connection.
+ * It should not be tampered with unless you REALLY know what you are doing.
+ *
+ * @since 1.1
*
- * This function returns the fd which is used by the underlying client connection.
- * It should not be tampered with unless you REALLY know what you are doing.
- * @since 1.1
+ * @param[in] cl The client object
+ * @return The fd, \n
+ * otherwise @c -1 on failure
*/
-EAPI int ecore_con_client_fd_get(const Ecore_Con_Client *cl);
+EAPI int ecore_con_client_fd_get(Ecore_Con_Client *cl);
/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
* @ingroup Ecore_Con_Group
*
- * Functions to communicate with and/or set options on a client.
+ * @brief This group provides functions to communicate with and/or set options on a client.
*
* This set of functions, as explained in @ref Ecore_Con_Server_Group, is used
* to send data to a client, or to set options and get information about this
@@ -1059,25 +1133,22 @@ EAPI int ecore_con_client_fd_get(const Ecore_Con_Client *cl);
* If you need to implement a client, the way to connect to a server is
* described in @ref Ecore_Con_Server_Group.
*
- * An example of usage of these functions can be found at:
- * @li @ref ecore_con_client_simple_example_c
- *
* @{
*/
/**
- * Sends the given data to the given client.
+ * @brief Sends the given data to the given client.
*
- * @param cl The given client.
- * @param data The given data.
- * @param size Length of the data, in bytes, to send.
- * @return The number of bytes sent. @c 0 will be returned if there is an
- * error.
+ * @details This function sends the given data to the client as soon as the program
+ * is back to the main loop. Thus, this function returns immediately
+ * (non-blocking). If the data needs to be sent @b now, call
+ * ecore_con_client_flush() after this one.
*
- * This function will send the given data to the client as soon as the program
- * is back to the main loop. Thus, this function returns immediately
- * (non-blocking). If the data needs to be sent @b now, call
- * ecore_con_client_flush() after this one.
+ * @param[in] cl The given client
+ * @param[in] data The given data
+ * @param[in] size The length of the data, in bytes, to send
+ * @return The number of bytes sent, \n
+ * otherwise @c 0 if there is an error
*
* @see ecore_con_server_send()
* @see ecore_con_client_flush()
@@ -1086,126 +1157,139 @@ EAPI int ecore_con_client_send(Ecore_Con_Client *cl,
const void *data,
int size);
/**
- * Closes the connection and frees memory allocated to the given client.
+ * @brief Gets the server representing the socket the client has connected to.
*
- * @param cl The given client.
- * @return Data associated with the client.
+ * @param[in] cl The given client
+ * @return The server that the client connected to
+ */
+EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
+
+/**
+ * @brief Closes the connection and frees the memory allocated to the given client.
+ *
+ * @param[in] cl The given client
+ * @return The data associated with the client
*/
EAPI void * ecore_con_client_del(Ecore_Con_Client *cl);
+
/**
- * Sets the data associated with the given client to @p data.
+ * @brief Sets the data associated with the given client to @a data.
*
- * @param cl The given client.
- * @param data What to set the data to.
+ * @param[in] cl The given client
+ * @param[in] data The data to set
*/
EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl,
const void *data);
/**
- * Retrieves the data associated with the given client.
+ * @brief Gets the data associated with the given client.
*
- * @param cl The given client.
- * @return The data associated with @p cl.
+ * @param[in] cl The given client
+ * @return The data associated with @a cl
*/
EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl);
/**
- * Gets the IP address of a client that has connected.
+ * @brief Gets the IP address of a client that has connected.
*
- * @param cl The given client.
- * @return A pointer to an internal string that contains the IP address of
- * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation.
+ * @remarks The returned string should not be modified, freed or trusted to stay valid
+ * after deletion for the @a cl object. If no IP is known @c NULL is returned.
*
- * The returned string should not be modified, freed or trusted to stay valid
- * after deletion for the @p cl object. If no IP is known @c NULL is returned.
+ * @param[in] cl The given client
+ * @return A pointer to an internal string that contains the IP address of
+ * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation
*/
-EAPI const char * ecore_con_client_ip_get(const Ecore_Con_Client *cl);
+EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl);
+
/**
- * Flushes all pending data to the given client.
+ * @brief Flushes all pending data to the given client.
*
- * @param cl The given client.
+ * @details This function blocks until all data is sent to the server.
*
- * This function will block until all data is sent to the server.
+ * @param[in] cl The given client
*
* @see ecore_con_client_send()
* @see ecore_con_server_flush()
*/
EAPI void ecore_con_client_flush(Ecore_Con_Client *cl);
+
/**
- * @brief Check how long a client has been connected
+ * @brief Checks how long a client has been connected.
*
- * @param cl The client to check
- * @return The total time, in seconds, that the client has been connected to
- * the server
+ * @details This function is used to find out how long a client has been connected for.
*
- * This function is used to find out how long a client has been connected for.
+ * @param[in] cl The client to check
+ * @return The total time, in seconds, that the client has been connected to the server
*/
-EAPI double ecore_con_client_uptime_get(const Ecore_Con_Client *cl);
+EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl);
+
/**
- * Get the default time after which the client will be disconnected when
- * inactive
+ * @brief Gets the default time after which the client is disconnected when inactive.
*
- * @param cl The client object
- * @return The timeout, in seconds, to disconnect after
+ * @details This function is used to get the idle timeout for a client. A value of < @c 1
+ * means the idle timeout is disabled.
*
- * This function is used to get the idle timeout for a client. A value of < 1
- * means the idle timeout is disabled.
+ * @param[in] cl The client object
+ * @return The timeout, in seconds, to disconnect after
*
* @see ecore_con_client_timeout_set()
*/
-EAPI double ecore_con_client_timeout_get(const Ecore_Con_Client *cl);
+EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl);
+
/**
- * Set the time after which the client will be disconnected when inactive
+ * @brief Sets the time after which the client is disconnected when inactive.
*
- * @param cl The client object
- * @param timeout The timeout, in seconds, to disconnect after
+ * @details This function is used by the server to set the idle timeout on a specific
+ * client. If the client becomes idle for a time higher than this value, it is
+ * disconnected. A value of < @c 1 disables the idle timeout.
*
- * This function is used by the server to set the idle timeout on a specific
- * client. If the client becomes idle for a time higher than this value, it will
- * be disconnected. A value of < 1 disables the idle timeout.
+ * @details This timeout is not affected by the one set by
+ * ecore_con_server_timeout_set(). A client is disconnected whenever the
+ * client or the server timeout is reached. That means, the lower timeout value
+ * is used for that client if ecore_con_server_timeout_set() is used on the server.
*
- * This timeout is not affected by the one set by
- * ecore_con_server_timeout_set(). A client will be disconnected whenever the
- * client or the server timeout is reached. That means, the lower timeout value
- * will be used for that client if ecore_con_server_timeout_set() is used on the
- * server.
+ * @param[in] cl The client object
+ * @param[in] timeout The timeout, in seconds, to disconnect after
*
* @see ecore_con_client_timeout_get()
* @see ecore_con_server_timeout_set()
*/
EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout);
+
/**
- * Returns whether the client is still connected
+ * @brief Checks whether the client is still connected.
*
- * @param cl The given client.
- * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise.
+ * @param[in] cl The given client
+ * @return @c EINA_TRUE if connected, \n
+ * otherwise @c EINA_FALSE if it is not connected
*/
-EAPI Eina_Bool ecore_con_client_connected_get(const Ecore_Con_Client *cl);
+EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl);
/**
- * @brief Return the port that the client has connected to
+ * @brief Gets the port that the client has connected to.
*
- * @param cl The client
- * @return The port that @p cl has connected to, or -1 on error
- * Use this function to return the port on which a given client has connected.
+ * @remarks Use this function to return the port on which a given client has connected.
+ *
+ * @param[in] cl The client
+ * @return The port that @a cl has connected to, \n
+ * otherwise @c -1 on error
*/
-EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl);
-
-
+EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl);
/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions
* @ingroup Ecore_Con_Group
*
- * Utility functions that set up, use and shut down the Ecore URL
- * Connection library.
+ * @brief This group provides utility functions that set up, use and shut down the Ecore URL
+ * Connection library.
*
- * These functions are a shortcut to make it easy to perform http requests
+ * These functions are shortcuts to make it easy to perform HTTP requests
* (POST, GET, etc).
*
- * Brief usage:
+ * Brief usage details:
* 1. Create an Ecore_Con_Url object with ecore_con_url_new(url);
* 2. Register to receive the #ECORE_CON_EVENT_URL_COMPLETE event
* (and optionally the #ECORE_CON_EVENT_URL_DATA and
@@ -1218,7 +1302,7 @@ EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl);
* need to wait for the #ECORE_CON_EVENT_URL_COMPLETE event before re-using or
* destroying the object.
*
- * If it's necessary to change the @ref Ecore_Con_Url object url, use
+ * If it is necessary to change the @ref Ecore_Con_Url object url, use
* ecore_con_url_url_set().
*
* Simple Usage 1 (HTTP GET):
@@ -1253,18 +1337,14 @@ EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl);
* ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass","dir");
* @endcode
*
- * These are complete examples for the API:
- * @li @ref ecore_con_url_download_example.c "Downloading a file"
- * @li @ref ecore_con_url_headers_example.c "Setting many options for the connection"
- *
* @{
*/
/**
* @typedef Ecore_Con_Url_Time
* @enum _Ecore_Con_Url_Time
- * The type of condition to use when making an HTTP request dependent on time,
- * so that headers such as "If-Modified-Since" are used.
+ * @brief Enumeration for the type of condition to use when making an HTTP request dependent on time,
+ * so that headers such as "If-Modified-Since" are used.
*/
typedef enum _Ecore_Con_Url_Time
{
@@ -1289,7 +1369,7 @@ typedef enum _Ecore_Con_Url_Time
/**
* @typedef Ecore_Con_Url_Http_Version
* @enum _Ecore_Con_Url_Http_Version
- * The http version to use
+ * @brief Enumeration of the HTTP version to use.
* @since 1.2
*/
typedef enum _Ecore_Con_Url_Http_Version
@@ -1307,84 +1387,87 @@ typedef enum _Ecore_Con_Url_Http_Version
} Ecore_Con_Url_Http_Version;
/**
- * Change the HTTP version used for the request
- * @param url_con Connection object through which the request will be sent.
- * @param version The version to be used
- * @return @c EINA_TRUE on success, @c EINA_FALSE on failure to change version.
- * @since 1.2
+ * @brief Changes the HTTP version used for the request.
+ * @since 1.2
+ *
+ * @param[in] url_con The connection object through which the request is sent
+ * @param[in] version The version to be used
+ * @return @c EINA_TRUE if the version is changed successfully, \n
+ * otherwise @c EINA_FALSE on failure to change version
* @see ecore_con_url_pipeline_get()
*/
EAPI Eina_Bool ecore_con_url_http_version_set(Ecore_Con_Url *url_con, Ecore_Con_Url_Http_Version version);
-
+
/**
- * Initialises the Ecore_Con_Url library.
- * @return Number of times the library has been initialised without being
- * shut down.
+ * @brief Initialises the Ecore_Con_Url library.
*
- * @note This function doesn't call ecore_con_init(). You still need to call it
- * explicitly before calling this one.
+ * @remarks This function does not call ecore_con_init(). You still need to call it
+ * explicitly before calling this one.
+ * @return The number of times the library has been initialised without being shut down
*/
EAPI int ecore_con_url_init(void);
/**
- * Shuts down the Ecore_Con_Url library.
- * @return Number of calls that still uses Ecore_Con_Url
+ * @brief Shuts down the Ecore_Con_Url library.
*
- * @note This function doesn't call ecore_con_shutdown(). You still need to call
- * it explicitly after calling this one.
+ * @remarks This function does not call ecore_con_shutdown(). You still need to call
+ * it explicitly after calling this one.
+ * @return The number of calls that still uses Ecore_Con_Url
*/
EAPI int ecore_con_url_shutdown(void);
/**
- * Enable or disable HTTP 1.1 pipelining.
- * @param enable @c EINA_TRUE will turn it on, @c EINA_FALSE will disable it.
+ * @brief Enables or disables HTTP 1.1 pipelining.
*
- * Pipelining allows to send one request after another one, without having to
- * wait for the reply of the first request. The respective replies are received
- * in the order that the requests were sent.
+ * @remarks Pipelining allows to send one request after another one, without having to
+ * wait for the reply of the first request. The respective replies are received
+ * in the order that the requests were sent.
*
- * Enabling this feature will be valid for all requests done using @c
- * ecore_con_url.
+ * @remarks Enabling this feature is valid for all requests done using @c ecore_con_url.
*
- * See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.
+ * @remarks See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.
*
+ * @param[in] enable Set @c EINA_TRUE to turn it on, \n
+ * otherwise @c EINA_FALSE to disable it
* @see ecore_con_url_pipeline_get()
*/
EAPI void ecore_con_url_pipeline_set(Eina_Bool enable);
/**
- * Is HTTP 1.1 pipelining enable ?
- * @return @c EINA_TRUE if it is enable.
+ * @brief Checks whether HTTP 1.1 pipelining is enabled.
+ *
+ * @return @c EINA_TRUE if it is enabled, \n
+ * otherwise @c EINA_FALSE if it is not enabled
*
* @see ecore_con_url_pipeline_set()
*/
EAPI Eina_Bool ecore_con_url_pipeline_get(void);
/**
- * Creates and initializes a new Ecore_Con_Url connection object.
+ * @brief Creates and initializes a new Ecore_Con_Url connection object.
*
- * @param url URL that will receive requests. Can be changed using
- * ecore_con_url_url_set.
+ * @details This function creates and initializes a new Ecore_Con_Url connection object that can be
+ * used for sending requests.
*
- * @return @c NULL on error, a new Ecore_Con_Url on success.
- *
- * Creates and initializes a new Ecore_Con_Url connection object that can be
- * used for sending requests.
+ * @param[in] url The URL that receives requests \n
+ * This can be changed using ecore_con_url_url_set.
+ * @return A new Ecore_Con_Url, \n
+ * otherwise @c NULL on error
*
* @see ecore_con_url_custom_new()
* @see ecore_con_url_url_set()
*/
EAPI Ecore_Con_Url * ecore_con_url_new(const char *url);
/**
- * Creates a custom connection object.
- *
- * @param url URL that will receive requests
- * @param custom_request Custom request (e.g. GET, POST, HEAD, PUT, etc)
+ * @brief Creates a custom connection object.
*
- * @return @c NULL on error, a new Ecore_Con_Url on success.
+ * @details This function creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD,
+ * SUBSCRIBE and other obscure HTTP requests). This object should be used like
+ * the one created with ecore_con_url_new().
*
- * Creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD,
- * SUBSCRIBE and other obscure HTTP requests). This object should be used like
- * one created with ecore_con_url_new().
+ * @param[in] url The URL that receives requests
+ * @param[in] custom_request The custom request (e.g. GET, POST, HEAD, PUT, etc)
+ * @return A new Ecore_Con_Url, \n
+ * otherwise @c NULL on error
*
* @see ecore_con_url_new()
* @see ecore_con_url_url_set()
@@ -1392,52 +1475,74 @@ EAPI Ecore_Con_Url * ecore_con_url_new(const char *url);
EAPI Ecore_Con_Url * ecore_con_url_custom_new(const char *url,
const char *custom_request);
/**
- * Destroys a Ecore_Con_Url connection object.
+ * @brief Destroys an Ecore_Con_Url connection object.
*
- * @param url_con Connection object to free.
+ * @param[in] url_con The connection object to free
*
* @see ecore_con_url_new()
*/
EAPI void ecore_con_url_free(Ecore_Con_Url *url_con);
/**
- * Associates data with a connection object.
+ * @brief Sets the URL to send the request to.
+ *
+ * @param[in] url_con The connection object through which the request is sent
+ * @param[in] url The URL that receives the request
+ *
+ * @return @c EINA_TRUE if the URL is set successfully, \n
+ * otherwise @c EINA_FALSE on error
+ */
+EAPI Eina_Bool ecore_con_url_url_set(Ecore_Con_Url *url_con,
+ const char *url);
+/**
+ * @brief Gets the URL to send the request to.
+ * @since 1.1
+ *
+ * @param[in] url_con The connection object through which the request is sent
+ * @return The URL that receives the request, \n
+ * otherwise @c NULL on failure \n
+ * URL is stringshared.
+ */
+EAPI const char *ecore_con_url_url_get(Ecore_Con_Url *url_con);
+
+/**
+ * @brief Associates data with a connection object.
*
- * @param url_con Connection object to associate data.
- * @param data Data to be set.
+ * @remarks Associates data with a connection object, which can be retrieved later with
+ * ecore_con_url_data_get()).
*
- * Associates data with a connection object, which can be retrieved later with
- * ecore_con_url_data_get()).
+ * @param[in] url_con The connection object to associate data
+ * @param[in] data The data to be set
*
* @see ecore_con_url_data_get()
*/
EAPI void ecore_con_url_data_set(Ecore_Con_Url *url_con,
void *data);
/**
- * Retrieves data associated with a Ecore_Con_Url connection object.
+ * @brief Gets data associated with a Ecore_Con_Url connection object.
*
- * @param url_con Connection object to retrieve data from.
+ * @details This function gets data associated with a Ecore_Con_Url connection object (previously
+ * set with ecore_con_url_data_set()).
*
- * @return Data associated with the given object.
- *
- * Retrieves data associated with a Ecore_Con_Url connection object (previously
- * set with ecore_con_url_data_set()).
+ * @param[in] url_con The connection object to retrieve data from
+ * @return The data associated with the given object
*
* @see ecore_con_url_data_set()
*/
EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con);
+
/**
- * Adds an additional header to the request connection object.
+ * @brief Adds an additional header to the request connection object.
*
- * @param url_con Connection object
- * @param key Header key
- * @param value Header value
+ * @details This function adds an additional header (User-Agent, Content-Type, etc.) to the request
+ * connection object. This addition is valid for only one
+ * ecore_con_url_get() or ecore_con_url_post() call.
*
- * Adds an additional header (User-Agent, Content-Type, etc.) to the request
- * connection object. This addition will be valid for only one
- * ecore_con_url_get() or ecore_con_url_post() call.
+ * @remarks Some functions like ecore_con_url_time() also add headers to the request.
*
- * Some functions like ecore_con_url_time() also add headers to the request.
+ * @param[in] url_con The connection object
+ * @param[in] key The header key
+ * @param[in] value The header value
*
* @see ecore_con_url_get()
* @see ecore_con_url_post()
@@ -1446,88 +1551,92 @@ EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con);
EAPI void ecore_con_url_additional_header_add(Ecore_Con_Url *url_con,
const char *key,
const char *value);
+
/**
- * Cleans additional headers.
+ * @brief Cleans additional headers.
*
- * @param url_con Connection object to clean additional headers.
+ * @details This function cleans additional headers associated with a connection object (previously
+ * added with ecore_con_url_additional_header_add()).
*
- * Cleans additional headers associated with a connection object (previously
- * added with ecore_con_url_additional_header_add()).
+ * @param[in] url_con The connection object to clean additional headers
*
* @see ecore_con_url_additional_header_add()
* @see ecore_con_url_get()
* @see ecore_con_url_post()
*/
EAPI void ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con);
+
/**
- * Retrieves headers from last request sent.
+ * @brief Gets headers from last request sent.
*
- * @param url_con Connection object to retrieve response headers from.
+ * @details This function retrieves a list containing the response headers. This function should be
+ * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be
+ * ready at that time).
*
- * Retrieves a list containing the response headers. This function should be
- * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be
- * ready at that time).
- *
- * @return List of response headers. This list must not be modified by the user.
+ * @param[in] url_con The connection object to retrieve response headers from
+ * @return The list of response headers \n
+ * This list must not be modified by the user.
*/
EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con);
+
/**
- * Setup a file for receiving response data.
+ * @brief Sets up a file for receiving response data.
*
- * @param url_con Connection object to set file
- * @param fd File descriptor associated with the file. A negative value will
- * unset any previously set fd.
+ * @details This function sets up a file to have response data written into. Note that
+ * ECORE_CON_EVENT_URL_DATA events are not emitted if a file has been set to
+ * receive the response data.
*
- * Sets up a file to have response data written into. Note that
- * ECORE_CON_EVENT_URL_DATA events will not be emitted if a file has been set to
- * receive the response data.
+ * @remarks This function can be used to easily setup a file where the downloaded data
+ * is saved.
*
- * This call can be used to easily setup a file where the downloaded data will
- * be saved.
+ * @param[in] url_con The connection object to set file
+ * @param[in] fd The file descriptor associated with the file \n
+ * A negative value unsets any previously set @a fd.
*/
EAPI void ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
+
/**
- * Retrieves the number of bytes received.
- *
- * Retrieves the number of bytes received on the last request of the given
- * connection object.
+ * @brief Gets the number of bytes received.
*
- * @param url_con Connection object which the request was sent on.
+ * @details This function retrieves the number of bytes received on the last request of the given
+ * connection object.
*
- * @return Number of bytes received on request.
+ * @param[in] url_con The connection object which the request is sent on
+ * @return The number of bytes received on request
*
* @see ecore_con_url_get()
* @see ecore_con_url_post()
*/
EAPI int ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
+
/**
- * Sets url_con to use http auth, with given username and password, "safely" or not.
- *
- * @param url_con Connection object to perform a request on, previously created
- * with ecore_con_url_new() or ecore_con_url_custom_new().
- * @param username Username to use in authentication
- * @param password Password to use in authentication
- * @param safe Whether to use "safer" methods (eg, NOT http basic auth)
+ * @brief Sets @a url_con to use http auth, with the given @a username and @a password, "safely" or not.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @remarks This function requires libcurl >= 7.19.1 to work. Otherwise it always returns @c 0.
*
- * @attention Requires libcurl >= 7.19.1 to work, otherwise will always return
- * @c 0.
+ * @param[in] url_con The connection object to perform a request on, previously created
+ * with ecore_con_url_new() or ecore_con_url_custom_new().
+ * @param[in] username The username to use in authentication
+ * @param[in] password The password to use in authentication
+ * @param[in] safe Set @c EINA_TRUE to use "safer" methods (eg, NOT http basic auth), \n
+ * otherwise set @c EINA_FALSE to not use it
+ * @return @c EINA_TRUE if it is set successfully,
+ * otherwise @c EINA_FALSE on error
*/
EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
const char *username,
const char *password,
Eina_Bool safe);
/**
- * Sends a get request.
+ * @brief Sends a get request.
*
- * @param url_con Connection object to perform a request on, previously created
+ * @remarks The request is performed immediately, but you need to setup event handlers
+ * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
+ * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
- *
- * The request is performed immediately, but you need to setup event handlers
- * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
- * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
+ * @param[in] url_con The connection object to perform a request on, previously created
+ * @return @c EINA_TRUE if the request is sent successfully, \n
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_custom_new()
* @see ecore_con_url_additional_headers_clear()
@@ -1539,24 +1648,27 @@ EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
* @see ecore_con_url_post()
*/
EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con);
+
/**
- * Sends a post request.
+ * @brief Sends a post request.
*
- * @param url_con Connection object to perform a request on, previously created
- * with ecore_con_url_new() or ecore_con_url_custom_new().
- * @param data Payload (data sent on the request). Can be @c NULL.
- * @param length Payload length. If @c -1, rely on automatic length
- * calculation via @c strlen() on @p data.
- * @param content_type Content type of the payload (e.g. text/xml). Can be @c
- * NULL.
+ * @remarks The request starts immediately, but you need to setup event handlers
+ * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
+ * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @remarks This call does not block your main loop.
*
- * The request starts immediately, but you need to setup event handlers
- * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
- * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
- *
- * This call won't block your main loop.
+ * @param[in] url_con The connection object to perform a request on, previously created
+ * with ecore_con_url_new() or ecore_con_url_custom_new().
+ * @param[in] data The payload (data sent on the request) \n
+ * This can be @c NULL.
+ * @param[in] length The payload length \n
+ * If this is @c -1, it relies on automatic length
+ * calculation via @c strlen() on @a data.
+ * @param[in] content_type The content type of the payload (e.g. text/xml) \n
+ * This can be @c NULL.
+ * @return @c EINA_TRUE if the request is sent successfully,
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_custom_new()
* @see ecore_con_url_additional_headers_clear()
@@ -1570,37 +1682,39 @@ EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con);
EAPI Eina_Bool ecore_con_url_post(Ecore_Con_Url *url_con,
const void *data, long length,
const char *content_type);
+
/**
- * Sets whether HTTP requests should be conditional, dependent on
- * modification time.
+ * @brief Sets whether HTTP requests should be conditional, dependent on
+ * modification time.
*
- * @param url_con Ecore_Con_Url to act upon.
- * @param time_condition Condition to use for HTTP requests.
- * @param timestamp Time since 1 Jan 1970 to use in the condition.
+ * @details This function may set the header "If-Modified-Since" or
+ * "If-Unmodified-Since", depending on the value of @a time_condition, with the
+ * value @a timestamp.
*
- * This function may set the header "If-Modified-Since" or
- * "If-Unmodified-Since", depending on the value of @p time_condition, with the
- * value @p timestamp.
+ * @param[in] url_con The Ecore_Con_Url to act upon
+ * @param[in] time_condition The condition to use for HTTP requests
+ * @param[in] timestamp The time since 1 Jan 1970 to use in the condition
*
- * @sa ecore_con_url_get()
- * @sa ecore_con_url_post()
+ * @see ecore_con_url_get()
+ * @see ecore_con_url_post()
*/
EAPI void ecore_con_url_time(Ecore_Con_Url *url_con,
Ecore_Con_Url_Time time_condition,
double timestamp);
/**
- * @brief Uploads a file to an ftp site.
+ * @brief Uploads a file to an FTP site.
*
- * @param url_con The Ecore_Con_Url object to send with
- * @param filename The path to the file to send
- * @param user The username to log in with
- * @param pass The password to log in with
- * @param upload_dir The directory to which the file should be uploaded
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
+ * @remarks Upload @a filename to an FTP server set in @a url_con using @a user
+ * and @a pass to directory @a upload_dir
*
- * Upload @p filename to an ftp server set in @p url_con using @p user
- * and @p pass to directory @p upload_dir
+ * @param[in] url_con The Ecore_Con_Url object to send with
+ * @param[in] filename The path to the file to send
+ * @param[in] user The username to log in with
+ * @param[in] pass The password to log in with
+ * @param[in] upload_dir The directory to which the file should be uploaded
+ * @return @c EINA_TRUE if the file is uploaded successfully, \n
+ * otherwise @c EINA_FALSE on error
*/
EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
const char *filename,
@@ -1608,173 +1722,178 @@ EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
const char *pass,
const char *upload_dir);
/**
- * Toggle libcurl's verbose output.
+ * @brief Toggles libcurl's verbose output.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param verbose Whether or not to enable libcurl's verbose output.
+ * @remarks If @a verbose is @c EINA_TRUE, libcurl outputs a lot of verbose
+ * information about its operations, which is useful for
+ * debugging. The verbose information is sent to stderr.
*
- * If @p verbose is @c EINA_TRUE, libcurl will output a lot of verbose
- * information about its operations, which is useful for
- * debugging. The verbose information will be sent to stderr.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] verbose Set @c EINA_TRUE to enable libcurl's verbose output, \n
+ * otherwise @c EINA_FALSE to disable verbose output
*/
EAPI void ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
Eina_Bool verbose);
+
/**
- * Enable or disable EPSV extension
- * @param url_con The Ecore_Con_Url instance which will be acted upon.
- * @param use_epsv Boolean to enable/disable the EPSV extension.
+ * @brief Enables or disables EPSV extension.
+ *
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] use_epsv Set @c EINA_TRUE to enable the EPSV extension, \n
+ * otherwise @c EINA_FALSE to disable it
*/
EAPI void ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
Eina_Bool use_epsv);
/**
- * Enables the cookie engine for subsequent HTTP requests.
+ * @brief Enables the cookie engine for subsequent HTTP requests.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @remarks After this function is called, cookies set by the server in HTTP responses
+ * are parsed and stored, as well as sent back to the server in new HTTP requests.
*
- * After this function is called, cookies set by the server in HTTP responses
- * will be parsed and stored, as well as sent back to the server in new HTTP
- * requests.
+ * @remarks Even though this function is called @c ecore_con_url_cookies_init(),
+ * there is no symmetrical shutdown operation.
*
- * @note Even though this function is called @c ecore_con_url_cookies_init(),
- * there is no symmetrical shutdown operation.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
*/
EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con);
+
/**
- * Controls whether session cookies from previous sessions shall be loaded.
+ * @brief Sets whether session cookies from previous sessions shall be loaded.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param ignore If @c EINA_TRUE, ignore session cookies when loading cookies
- * from files. If @c EINA_FALSE, all cookies will be loaded.
+ * @remarks Session cookies are cookies with no expire date set, which usually means
+ * they are removed after the current session is closed.
*
- * Session cookies are cookies with no expire date set, which usually means
- * they are removed after the current session is closed.
+ * @remarks By default, when Ecore_Con_Url loads cookies from a file, all cookies are
+ * loaded, including session cookies, which, most of the time, were supposed
+ * to be loaded and valid only for that session.
*
- * By default, when Ecore_Con_Url loads cookies from a file, all cookies are
- * loaded, including session cookies, which, most of the time, were supposed
- * to be loaded and valid only for that session.
+ * @remarks If @a ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from
+ * the files passed to @c ecore_con_url_cookies_file_add(), session cookies
+ * are not loaded.
*
- * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from
- * the files passed to @c ecore_con_url_cookies_file_add(), session cookies
- * will not be loaded.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] ignore Set @c EINA_TRUE to ignore session cookies when loading cookies from files, \n
+ * otherwise set @c EINA_FALSE to load all cookies
*
* @see ecore_con_url_cookies_file_add()
*/
EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con,
Eina_Bool ignore);
+
/**
- * Clears currently loaded cookies.
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @brief Clears currently loaded cookies.
*
- * The cleared cookies are removed and will not be sent in subsequent HTTP
- * requests, nor will they be written to the cookiejar file set via
- * @c ecore_con_url_cookies_jar_file_set().
+ * @remarks The cleared cookies are removed and not sent in subsequent HTTP
+ * requests, nor are they written to the cookiejar file set using
+ * @c ecore_con_url_cookies_jar_file_set().
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
- * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
- * immediately, just when the request is started. Thus, if you ask to
- * clear the cookies, but has a file already set by that function, the
- * cookies will then be loaded and you will have old cookies set. In order
- * to don't have any old cookie set, you need to don't call
- * ecore_con_url_cookies_file_add() ever on the @p url_con handler, and
- * call this function to clear any cookie set by a previous request on
- * this handler.
+ * @remarks This function initializes the cookie engine if it has not been
+ * initialized yet.
+ * @remarks The cookie files set by ecore_con_url_cookies_file_add() are not loaded
+ * immediately, just when the request is started. Thus, if you ask to
+ * clear the cookies, but has a file already set by that function, the
+ * cookies are then loaded and you have old cookies set. In order
+ * to not have any old cookie set, you need to not call
+ * ecore_con_url_cookies_file_add() ever on the @a url_con handler, and
+ * call this function to clear any cookie set by a previous request on
+ * this handler.
+ *
+ * @param[in] url_con The Ecore_Con_Url instance which are acted upon
*
* @see ecore_con_url_cookies_session_clear()
* @see ecore_con_url_cookies_ignore_old_session_set()
*/
EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con);
+
/**
- * Clears currently loaded session cookies.
+ * @brief Clears currently loaded session cookies.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @remarks Session cookies are cookies with no expire date set, which usually means
+ * they are removed after the current session is closed.
*
- * Session cookies are cookies with no expire date set, which usually means
- * they are removed after the current session is closed.
+ * @remarks The cleared cookies are removed and not sent in subsequent HTTP
+ * requests, nor are they be written to the cookiejar file set using
+ * @c ecore_con_url_cookies_jar_file_set().
*
- * The cleared cookies are removed and will not be sent in subsequent HTTP
- * requests, nor will they be written to the cookiejar file set via
- * @c ecore_con_url_cookies_jar_file_set().
+ * @remarks This function initializes the cookie engine if it has not been
+ * initialized yet.
+ * @remarks The cookie files set by ecore_con_url_cookies_file_add() are not loaded
+ * immediately, just when the request is started. Thus, if you ask to
+ * clear the session cookies, but has a file already set by that function,
+ * the session cookies are then loaded and you have old cookies
+ * set. In order to not have any old session cookie set, you need to
+ * not call ecore_con_url_cookies_file_add() ever on the @a url_con
+ * handler, and call this function to clear any session cookie set by a
+ * previous request on this handler. An easier way to not use old
+ * session cookies is by using the function
+ * ecore_con_url_cookies_ignore_old_session_set().
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
- * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
- * immediately, just when the request is started. Thus, if you ask to
- * clear the session cookies, but has a file already set by that function,
- * the session cookies will then be loaded and you will have old cookies
- * set. In order to don't have any old session cookie set, you need to
- * don't call ecore_con_url_cookies_file_add() ever on the @p url_con
- * handler, and call this function to clear any session cookie set by a
- * previous request on this handler. An easier way to don't use old
- * session cookies is by using the function
- * ecore_con_url_cookies_ignore_old_session_set().
+ * @param[in] url_con The Ecore_Con_Url instance which are acted upon
*
* @see ecore_con_url_cookies_clear()
* @see ecore_con_url_cookies_ignore_old_session_set()
*/
EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con);
+
/**
- * Adds a file to the list of files from which to load cookies.
- *
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param file_name Name of the file that will be added to the list.
+ * @brief Adds a file to the list of files from which to load cookies.
*
- * Files must contain cookies defined according to two possible formats:
+ * @remarks The files must contain cookies defined according to two possible formats:
+ * @li HTTP-style header ("Set-Cookie: ...").
+ * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a>
*
- * @li HTTP-style header ("Set-Cookie: ...").
- * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a>
+ * @remarks Cookies are only @b read from this file. If you want to save cookies to a
+ * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this
+ * function supports the both types of cookie file cited above, while
+ * ecore_con_url_cookies_jar_file_set() saves only in the Netscape/Mozilla's format.
*
- * Cookies will only be @b read from this file. If you want to save cookies to a
- * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this
- * function supports the both types of cookie file cited above, while
- * ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's
- * format.
+ * @remarks Please notice that the file is not read immediately, but rather added
+ * to a list of files that is loaded and parsed at a later time.
*
- * Please notice that the file will not be read immediately, but rather added
- * to a list of files that will be loaded and parsed at a later time.
+ * @remarks This function initializes the cookie engine if it has not been
+ * initialized yet.
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] file_name The name of the file that is added to the list
*
* @see ecore_con_url_cookies_ignore_old_session_set()
* @see ecore_con_url_cookies_jar_file_set()
*/
EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con,
const char * const file_name);
+
/**
- * Sets the name of the file to which all current cookies will be written when
- * either cookies are flushed or Ecore_Con is shut down.
- *
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param cookiejar_file File to which the cookies will be written.
+ * @brief Sets the name of the file to which all current cookies are written when
+ * either cookies are flushed or Ecore_Con is shut down.
*
- * @return @c EINA_TRUE is the file name has been set successfully,
- * @c EINA_FALSE otherwise.
+ * @remarks Cookies are written following Netscape/Mozilla's data format, also known as
+ * cookie-jar.
*
- * Cookies are written following Netscape/Mozilla's data format, also known as
- * cookie-jar.
+ * @remarks Cookies are only @b saved to this file. If you need to read cookies from
+ * a file, use ecore_con_url_cookies_file_add() instead.
*
- * Cookies will only be @b saved to this file. If you need to read cookies from
- * a file, use ecore_con_url_cookies_file_add() instead.
+ * @remarks This function initializes the cookie engine if it has not been initialized yet.
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
+ * @param[in] url_con The Ecore_Con_Url instance which are acted upon
+ * @param[in] cookiejar_file The file to which the cookies are written
+ * @return @c EINA_TRUE is the file name has been set successfully, \n
+ * otherwise @c EINA_FALSE on failure
*
* @see ecore_con_url_cookies_jar_write()
*/
EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con,
const char * const cookiejar_file);
+
/**
- * Writes all current cookies to the cookie jar immediately.
+ * @brief Writes all current cookies to the cookie jar immediately.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @remarks A cookie-jar file must have been previously set by
+ * ecore_con_url_jar_file_set(), otherwise nothing is done.
*
- * A cookie-jar file must have been previously set by
- * @c ecore_con_url_jar_file_set, otherwise nothing will be done.
+ * @remarks This function initializes the cookie engine if it has not been initialized yet.
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
*
* @see ecore_con_url_cookies_jar_file_set()
*/
@@ -1786,81 +1905,86 @@ EAPI int ecore_con_url_ssl_ca_set(Ecore_Con_Url *url_con,
const char *ca_path);
/**
- * Set HTTP proxy to use.
- *
- * The parameter should be a char * to a zero terminated string holding
- * the host name or dotted IP address. To specify port number in this string,
- * append :[port] to the end of the host name.
- * The proxy string may be prefixed with [protocol]:// since any such prefix
- * will be ignored.
- * The proxy's port number may optionally be specified with the separate option.
- * If not specified, libcurl will default to using port 1080 for proxies.
+ * @brief Sets the HTTP proxy to use.
+ * @since 1.2
*
- * @param url_con Connection object that will use the proxy.
- * @param proxy Porxy string or @c NULL to disable
+ * @remarks The parameter should be a char * to a zero terminated string holding
+ * the host name or dotted IP address. To specify port number in this string,
+ * append :[port] to the end of the host name.
+ * The proxy string may be prefixed with [protocol]:// since any such prefix
+ * is ignored.
+ * The proxy's port number may optionally be specified with the separate option.
+ * If not specified, libcurl defaults to using port 1080 for proxies.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
- * @since 1.2
+ * @param[in] url_con The connection object that uses the proxy
+ * @param[in] proxy The proxy string, \n
+ * otherwise set @c NULL to disable
+ * @return @c EINA_TRUE if the proxy is set successfully,
+ * otherwise @c EINA_FALSE on error
*/
EAPI Eina_Bool ecore_con_url_proxy_set(Ecore_Con_Url *url_con, const char *proxy);
/**
- * Set zero terminated username to use for proxy.
+ * @brief Sets zero terminated username to use for proxy.
+ * @since 1.2
*
- * if socks protocol is used for proxy, protocol should be socks5 and above.
+ * @remarks If socks protocol is used for proxy, protocol should be socks5 and above.
*
- * @param url_con Connection object that will use the proxy.
- * @param username Username string.
+ * @param[in] url_con The connection object that uses the proxy
+ * @param[in] username The username string
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @return @c EINA_TRUE if the username is set successfully, \n
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_proxy_set()
*
- * @since 1.2
*/
EAPI Eina_Bool ecore_con_url_proxy_username_set(Ecore_Con_Url *url_con, const char *username);
/**
- * Set zero terminated password to use for proxy.
+ * @brief Sets zero terminated password to use for proxy.
+ * @since 1.2
*
- * if socks protocol is used for proxy, protocol should be socks5 and above.
+ * @remarks If socks protocol is used for proxy, protocol should be socks5 and above.
*
- * @param url_con Connection object that will use the proxy.
- * @param password Password string.
+ * @param[in] url_con The connection object that uses the proxy
+ * @param[in] password The password string
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @return @c EINA_TRUE if the password is set successfully, \n
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_proxy_set()
*
- * @since 1.2
*/
EAPI Eina_Bool ecore_con_url_proxy_password_set(Ecore_Con_Url *url_con, const char *password);
/**
- * Set timeout in seconds.
+ * @brief Sets timeout in seconds.
*
- * the maximum time in seconds that you allow the ecore con url transfer
- * operation to take. Normally, name lookups can take a considerable time
- * and limiting operations to less than a few minutes risk aborting perfectly
- * normal operations.
+ * @since 1.2
*
- * @param url_con Connection object that will use the timeout.
- * @param timeout time in seconds.
+ * @remarks The maximum time in seconds that you allow the ecore_con_url_transfer
+ * operation to take. Normally, name lookups can take a considerable time
+ * and limiting operations to less than a few minutes risk aborting perfectly
+ * normal operations.
*
- * @see ecore_con_url_cookies_jar_file_set()
+ * @param[in] url_con The connection object that uses the timeout
+ * @param[in] timeout The time in seconds
*
- * @since 1.2
+ * @see ecore_con_url_cookies_jar_file_set()
*/
EAPI void ecore_con_url_timeout_set(Ecore_Con_Url *url_con, double timeout);
/**
- * Get the returned HTTP STATUS code
+ * @brief Gets the returned HTTP STATUS code.
+ * @since 1.2
*
- * This is used to, at any time, try to return the status code for a transmission.
- * @param url_con Connection object
- * @return A valid HTTP STATUS code, or 0 on failure
+ * @remarks This is used to try to return the status code for a transmission.
+ *
+ * @param[in] url_con The connection object
+ * @return A valid HTTP STATUS code, \n
+ * otherwise @c 0 on failure
*
- * @since 1.2
*/
EAPI int ecore_con_url_status_code_get(Ecore_Con_Url *url_con);
/**