From 9bd5f83c64f4ee4550adc0c2e5dd04853189a0a7 Mon Sep 17 00:00:00 2001 From: antognolli Date: Tue, 12 Jul 2011 14:36:58 +0000 Subject: [PATCH] ecore/ecore_con - Move more function documentation to Ecore_Con.h Some small fixes were also made to these docs. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@61294 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/lib/ecore_con/Ecore_Con.h | 276 +++++++++++++++++++++++++++++++++++++++++- src/lib/ecore_con/ecore_con.c | 223 ---------------------------------- 2 files changed, 275 insertions(+), 224 deletions(-) diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h index 78b024a..e9d6331 100644 --- a/src/lib/ecore_con/Ecore_Con.h +++ b/src/lib/ecore_con/Ecore_Con.h @@ -532,31 +532,214 @@ EAPI Eina_Bool ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_ * @{ */ +/** + * Creates a server to listen for connections. + * + * The socket on which the server listens depends on the connection + * type: + * @li If @a compl_type is @c ECORE_CON_LOCAL_USER, the server will listen on + * the Unix socket "~/.ecore/[name]/[port]". + * @li If @a compl_type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen + * on Unix socket "/tmp/.ecore_service|[name]|[port]". + * @li If @a compl_type is @c ECORE_CON_REMOTE_TCP, the server will listen + * on TCP port @c port. + * + * @param compl_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. + */ 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. + * + * The socket to which the connection is made depends on the connection type: + * @li If @a compl_type is @c ECORE_CON_LOCAL_USER, the function will + * connect to the server at the Unix socket + * "~/.ecore/[name]/[port]". + * @li If @a compl_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 compl_type is @c ECORE_CON_REMOTE_TCP, the function will + * connect to the server at the TCP port "[name]:[port]". + * + * @param compl_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. + */ 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. + * + * @param svr The given server. + * @return Data associated with the server when it was created. + * + * All the clients connected to this server will be disconnected. + * + * @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. + * + * @param svr The given server. + * @return The associated data. + */ EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr); +/** + * 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. + */ EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr, void *data); +/** + * Retrieves whether the given server is currently connected. + * + * @param svr The given server. + * @return #EINA_TRUE if the server is connected. #EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr); +/** + * Retrieves the current list of clients. + * + * @param svr The given server. + * @return The list of clients on this server. + * + * Each node in the returned list points to an @ref Ecore_Con_Client. + */ EAPI Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr); + +/** + * Retrieves the name of server. + * + * @param svr The given server. + * @return The name of the server. + */ EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr); + +/** + * Retrieves the server port in use. + * + * @param svr The given server. + * @return The server port in use. + * + * The port where the server is listening for connections. + */ EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr); +/** + * @brief Check 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 + * + * This function is used to find out how long a server has been + * connected/running for. + */ EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr); +/** + * 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. + */ 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. + */ 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. + * + * @param 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. + * This string should not be modified or trusted to stay valid after + * deletion for the @p svr object. If no IP is known NULL is returned. + */ EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr); +/** + * Flushes all pending data to the given server. Will return when done. + * + * @param svr The given server. + */ EAPI void ecore_con_server_flush(Ecore_Con_Server *svr); +/** + * Set the default time after which an inactive client will be disconnected + * + * @param svr The server object + * @param timeout The timeout, in seconds, to disconnect after + * + * This function is used to set the idle timeout on clients. A value of < 1 + * disables the idle timeout. + * + * @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 + * + * @param svr The server object + * @return The timeout, in seconds, to disconnect after + * + * This function is used to get the idle timeout for clients. A value of < 1 + * means the idle timeout is disabled. + * + * @see ecore_con_server_timeout_set() + * @see ecore_con_client_timeout_get() + */ EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr); /** @@ -569,20 +752,111 @@ EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr); * @{ */ +/** + * 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. + */ EAPI int ecore_con_client_send(Ecore_Con_Client *cl, const void *data, int size); +/** + * Retrieves the server representing the socket the client has + * connected to. + * + * @param 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); +/** + * Closes the connection and frees memory allocated to the given client. + * + * @param cl The given client. + * @return 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. + * + * @param cl The given client. + * @param data What to set the data to. + */ EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl, - const void *data); + const void *data); +/** + * Retrieves the data associated with the given client. + * + * @param cl The given client. + * @return The data associated with @p cl. + */ EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl); + +/** + * 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. + * + * 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 NULL is returned. + */ EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl); +/** + * Flushes all pending data to the given client. Will return when done. + * + * @param cl The given client. + */ EAPI void ecore_con_client_flush(Ecore_Con_Client *cl); +/** + * @brief Check 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 + * + * This function is used to find out how long a client has been connected for. + */ EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl); +/** + * Get the default time after which the client will be disconnected when + * inactive + * + * @param cl The client object + * @return The timeout, in seconds, to disconnect after + * + * This function is used to get the idle timeout for a client. A value of < 1 + * means the idle timeout is disabled. + */ EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl); +/** + * Set the time after which the client will be disconnected when inactive + * + * @param cl The client object + * @param timeout The timeout, in seconds, to disconnect after + * + * This function is used to set the idle timeout on a client. A value of < 1 + * disables the idle timeout. + */ EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout); +/** + * Returns whether the client is still connected + * + * @param cl The given client. + * @return #EINA_TRUE if connected, else EINA_FALSE + */ EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl); +/** + * @brief Return 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. + */ EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl); /** diff --git a/src/lib/ecore_con/ecore_con.c b/src/lib/ecore_con/ecore_con.c index 44e6b2a..a706993 100644 --- a/src/lib/ecore_con/ecore_con.c +++ b/src/lib/ecore_con/ecore_con.c @@ -256,30 +256,6 @@ on_error: * Shows how to write a simple server using the Ecore_Con library. */ -/** - * Creates a server to listen for connections. - * - * The socket on which the server listens depends on the connection - * type: - * @li If @a compl_type is @c ECORE_CON_LOCAL_USER, the server will listen on - * the Unix socket "~/.ecore/[name]/[port]". - * @li If @a compl_type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen - * on Unix socket "/tmp/.ecore_service|[name]|[port]". - * @li If @a compl_type is @c ECORE_CON_REMOTE_TCP, the server will listen - * on TCP port @c port. - * - * @param compl_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. - */ EAPI Ecore_Con_Server * ecore_con_server_add(Ecore_Con_Type compl_type, const char *name, @@ -374,31 +350,6 @@ error: return NULL; } -/** - * Creates a connection to the specified server and returns an associated object. - * - * The socket to which the connection is made depends on the connection type: - * @li If @a compl_type is @c ECORE_CON_LOCAL_USER, the function will - * connect to the server at the Unix socket - * "~/.ecore/[name]/[port]". - * @li If @a compl_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 compl_type is @c ECORE_CON_REMOTE_TCP, the function will - * connect to the server at the TCP port "[name]:[port]". - * - * @param compl_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. - */ EAPI Ecore_Con_Server * ecore_con_server_connect(Ecore_Con_Type compl_type, const char *name, @@ -491,13 +442,6 @@ error: return NULL; } -/** - * Set the default time after which an inactive client will be disconnected - * @param svr The server object - * @param timeout The timeout, in seconds, to disconnect after - * This function is used to set the idle timeout on clients. A value of < 1 - * disables the idle timeout. - */ EAPI void ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout) @@ -514,13 +458,6 @@ ecore_con_server_timeout_set(Ecore_Con_Server *svr, svr->disconnect_time = timeout; } -/** - * Get the default time after which an inactive client will be disconnected - * @param svr The server object - * @return The timeout, in seconds, to disconnect after - * This function is used to get the idle timeout for clients. A value of < 1 - * means the idle timeout is disabled. - */ EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr) { @@ -533,12 +470,6 @@ ecore_con_server_timeout_get(Ecore_Con_Server *svr) return svr->created ? svr->client_disconnect_time : svr->disconnect_time; } -/** - * Closes the connection and frees the given server. - * @param svr The given server. - * @return Data associated with the server when it was created. - * @see ecore_con_server_add, ecore_con_server_connect - */ EAPI void * ecore_con_server_del(Ecore_Con_Server *svr) { @@ -569,11 +500,6 @@ ecore_con_server_del(Ecore_Con_Server *svr) return data; } -/** - * Retrieves the data associated with the given server. - * @param svr The given server. - * @return The associated data. - */ EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr) { @@ -588,12 +514,6 @@ ecore_con_server_data_get(Ecore_Con_Server *svr) return svr->data; } -/** - * 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. - */ EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr, void *data) @@ -613,11 +533,6 @@ ecore_con_server_data_set(Ecore_Con_Server *svr, return ret; } -/** - * Retrieves whether the given server is currently connected. - * @param svr The given server. - * @return #EINA_TRUE if the server is connected. #EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr) { @@ -634,11 +549,6 @@ ecore_con_server_connected_get(Ecore_Con_Server *svr) return EINA_TRUE; } -/** - * Retrieves the current list of clients. - * @param svr The given server. - * @return The list of clients on this server. - */ EAPI Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr) { @@ -652,11 +562,6 @@ ecore_con_server_clients_get(Ecore_Con_Server *svr) return svr->clients; } -/** - * Retrieves the name of server. - * @param svr The given server. - * @return The name of the server. - */ EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr) { @@ -670,11 +575,6 @@ ecore_con_server_name_get(Ecore_Con_Server *svr) return svr->name; } -/** - * Retrieves the server port in use. - * @param svr The given server. - * @return The server port in use. - */ EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr) { @@ -687,14 +587,6 @@ ecore_con_server_port_get(Ecore_Con_Server *svr) return svr->port; } -/** - * 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. - */ EAPI int ecore_con_server_send(Ecore_Con_Server *svr, const void *data, @@ -738,27 +630,6 @@ ecore_con_server_send(Ecore_Con_Server *svr, return 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. - * 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. - * @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). - */ EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr, int client_limit, @@ -775,15 +646,6 @@ ecore_con_server_client_limit_set(Ecore_Con_Server *svr, svr->reject_excess_clients = reject_excess_clients; } -/** - * Gets the IP address of a server that has been connected to. - * - * @param 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. - * This string should not be modified or trusted to stay valid after - * deletion for the @p svr object. If no IP is known NULL is returned. - */ EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr) { @@ -796,12 +658,6 @@ ecore_con_server_ip_get(Ecore_Con_Server *svr) return svr->ip; } -/** - * @brief Check 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 - * This function is used to find out how long a server has been connected/running for. - */ EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr) { @@ -814,11 +670,6 @@ ecore_con_server_uptime_get(Ecore_Con_Server *svr) return ecore_time_get() - svr->start_time; } -/** - * Flushes all pending data to the given server. Will return when done. - * - * @param svr The given server. - */ EAPI void ecore_con_server_flush(Ecore_Con_Server *svr) { @@ -848,14 +699,6 @@ ecore_con_server_flush(Ecore_Con_Server *svr) * Shows how to write a simple client that connects to the example server. */ -/** - * 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. - */ EAPI int ecore_con_client_send(Ecore_Con_Client *cl, const void *data, @@ -903,12 +746,6 @@ ecore_con_client_send(Ecore_Con_Client *cl, return size; } -/** - * Retrieves the server representing the socket the client has - * connected to. - * @param 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) { @@ -922,11 +759,6 @@ ecore_con_client_server_get(Ecore_Con_Client *cl) return cl->host_server; } -/** - * Returns whether the client is still connected - * @param cl The given client. - * @return #EINA_TRUE if connected, else EINA_FALSE - */ EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl) { @@ -940,13 +772,6 @@ ecore_con_client_connected_get(Ecore_Con_Client *cl) return !cl->dead; } -/** - * Set the time after which the client will be disconnected when inactive - * @param cl The client object - * @param timeout The timeout, in seconds, to disconnect after - * This function is used to set the idle timeout on a client. A value of < 1 - * disables the idle timeout. - */ EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout) @@ -963,13 +788,6 @@ ecore_con_client_timeout_set(Ecore_Con_Client *cl, _ecore_con_cl_timer_update(cl); } -/** - * Get the default time after which the client will be disconnected when inactive - * @param cl The client object - * @return The timeout, in seconds, to disconnect after - * This function is used to get the idle timeout for a client. A value of < 1 - * means the idle timeout is disabled. - */ EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl) { @@ -982,11 +800,6 @@ ecore_con_client_timeout_get(Ecore_Con_Client *cl) return cl->disconnect_time; } -/** - * Closes the connection and frees memory allocated to the given client. - * @param cl The given client. - * @return Data associated with the client. - */ EAPI void * ecore_con_client_del(Ecore_Con_Client *cl) { @@ -1022,11 +835,6 @@ ecore_con_client_del(Ecore_Con_Client *cl) return data; } -/** - * Sets the data associated with the given client to @p data. - * @param cl The given client. - * @param data What to set the data to. - */ EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl, const void *data) @@ -1042,11 +850,6 @@ ecore_con_client_data_set(Ecore_Con_Client *cl, cl->data = (void *)data; } -/** - * Retrieves the data associated with the given client. - * @param cl The given client. - * @return The data associated with @p cl. - */ EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl) { @@ -1061,15 +864,6 @@ ecore_con_client_data_get(Ecore_Con_Client *cl) return cl->data; } -/** - * 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. - * This string should not be modified or trusted to stay valid after - * deletion for the @p cl object. If no IP is known NULL is returned. - */ EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl) { @@ -1084,12 +878,6 @@ ecore_con_client_ip_get(Ecore_Con_Client *cl) return cl->ip; } -/** - * @brief Return 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. - */ EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl) { @@ -1103,12 +891,6 @@ ecore_con_client_port_get(Ecore_Con_Client *cl) return ((struct sockaddr_in6*)cl->client_addr)->sin6_port; } -/** - * @brief Check 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 - * This function is used to find out how long a client has been connected for. - */ EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl) { @@ -1121,11 +903,6 @@ ecore_con_client_uptime_get(Ecore_Con_Client *cl) return ecore_time_get() - cl->start_time; } -/** - * Flushes all pending data to the given client. Will return when done. - * - * @param cl The given client. - */ EAPI void ecore_con_client_flush(Ecore_Con_Client *cl) { -- 2.7.4