forked from enlightenment/efl
ecore/ecore_con - Brief description for the client and server groups.
Also improve the documentation of some functions. SVN revision: 61298
This commit is contained in:
parent
6c645fa930
commit
c66ec1de38
|
@ -432,6 +432,7 @@ typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
|
||||||
* @code
|
* @code
|
||||||
* ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
|
* ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
|
||||||
* @endcode
|
* @endcode
|
||||||
|
* @ingroup Ecore_Con_Server_Group
|
||||||
*/
|
*/
|
||||||
typedef enum _Ecore_Con_Type
|
typedef enum _Ecore_Con_Type
|
||||||
{
|
{
|
||||||
|
@ -529,22 +530,61 @@ EAPI Eina_Bool ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_
|
||||||
/**
|
/**
|
||||||
* @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
|
* @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
|
||||||
*
|
*
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* 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
|
||||||
|
* #ECORE_CON_EVENT_CLIENT_ADD, #ECORE_CON_EVENT_CLIENT_DEL and
|
||||||
|
* #ECORE_CON_EVENT_CLIENT_DATA, that will be called when a client is
|
||||||
|
* communicating with the server:
|
||||||
|
*
|
||||||
|
* @code
|
||||||
|
* if (!(svr = ecore_con_server_add(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)))
|
||||||
|
* exit(1);
|
||||||
|
*
|
||||||
|
* ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_ADD, _add_cb, NULL);
|
||||||
|
* ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DEL, _del_cb, NULL);
|
||||||
|
* ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DATA, _data_cb, NULL);
|
||||||
|
*
|
||||||
|
* ecore_main_loop_begin();
|
||||||
|
* @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
|
||||||
|
* code:
|
||||||
|
*
|
||||||
|
* @code
|
||||||
|
* if (!(svr = ecore_con_server_connect(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)))
|
||||||
|
* exit(1);
|
||||||
|
*
|
||||||
|
* ecore_event_handler_add(ECORE_CON_EVENT_SERVER_ADD, _add_cb, NULL);
|
||||||
|
* ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DEL, _del_cb, NULL);
|
||||||
|
* ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DATA, _data_cb, NULL);
|
||||||
|
*
|
||||||
|
* ecore_main_loop_begin();
|
||||||
|
* @endcode
|
||||||
|
*
|
||||||
|
* Please notice 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.
|
* Creates a server to listen for connections.
|
||||||
*
|
*
|
||||||
* The socket on which the server listens depends on the connection
|
* @param type The connection type.
|
||||||
* 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
|
* @param name Name to associate with the socket. It is used when
|
||||||
* generating the socket name of a Unix socket, or for
|
* generating the socket name of a Unix socket, or for
|
||||||
* determining what host to listen on for TCP sockets.
|
* determining what host to listen on for TCP sockets.
|
||||||
|
@ -555,6 +595,20 @@ EAPI Eina_Bool ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_
|
||||||
* @param data Data to associate with the created Ecore_Con_Server
|
* @param data Data to associate with the created Ecore_Con_Server
|
||||||
* object.
|
* object.
|
||||||
* @return A new Ecore_Con_Server.
|
* @return A new Ecore_Con_Server.
|
||||||
|
*
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* More information about the @p type can be found at @ref _Ecore_Con_Type.
|
||||||
|
*
|
||||||
|
* The @p data parameter can be fetched later using ecore_con_server_data_get()
|
||||||
|
* or changed with ecore_con_server_data_set().
|
||||||
*/
|
*/
|
||||||
EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
|
EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
|
||||||
const char *name, int port,
|
const char *name, int port,
|
||||||
|
@ -563,17 +617,7 @@ EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
|
||||||
/**
|
/**
|
||||||
* Creates a connection to the specified server and returns an associated object.
|
* 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:
|
* @param type 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.
|
* @param name Name used when determining what socket to connect to.
|
||||||
* It is used to generate the socket name when the socket
|
* It is used to generate the socket name when the socket
|
||||||
* is a Unix socket. It is used as the hostname when
|
* is a Unix socket. It is used as the hostname when
|
||||||
|
@ -584,6 +628,29 @@ EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
|
||||||
* @param data Data to associate with the created Ecore_Con_Server
|
* @param data Data to associate with the created Ecore_Con_Server
|
||||||
* object.
|
* object.
|
||||||
* @return A new Ecore_Con_Server.
|
* @return A new Ecore_Con_Server.
|
||||||
|
*
|
||||||
|
* 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]".
|
||||||
|
*
|
||||||
|
* More information about the @p type can be found at @ref _Ecore_Con_Type.
|
||||||
|
*
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* However, even if this call returns a valid @ref Ecore_Con_Server, the
|
||||||
|
* connection will only be successfully completed if an event of type
|
||||||
|
* #ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
|
||||||
|
* #ECORE_CON_EVENT_SERVER_DEL will be received.
|
||||||
|
*
|
||||||
|
* The @p data parameter can be fetched later using ecore_con_server_data_get()
|
||||||
|
* or changed with ecore_con_server_data_set().
|
||||||
*/
|
*/
|
||||||
EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
|
EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
|
||||||
const char *name, int port,
|
const char *name, int port,
|
||||||
|
@ -605,6 +672,8 @@ EAPI void * ecore_con_server_del(Ecore_Con_Server *svr);
|
||||||
*
|
*
|
||||||
* @param svr The given server.
|
* @param svr The given server.
|
||||||
* @return The associated data.
|
* @return The associated data.
|
||||||
|
*
|
||||||
|
* @see ecore_con_server_data_set()
|
||||||
*/
|
*/
|
||||||
EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
|
EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
|
||||||
/**
|
/**
|
||||||
|
@ -613,6 +682,8 @@ EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
|
||||||
* @param svr The given server.
|
* @param svr The given server.
|
||||||
* @param data The data to associate with @p svr
|
* @param data The data to associate with @p svr
|
||||||
* @return The previously associated data, if any.
|
* @return The previously associated data, if any.
|
||||||
|
*
|
||||||
|
* @see ecore_con_server_data_get()
|
||||||
*/
|
*/
|
||||||
EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr,
|
EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr,
|
||||||
void *data);
|
void *data);
|
||||||
|
@ -640,6 +711,8 @@ EAPI const Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr);
|
||||||
*
|
*
|
||||||
* @param svr The given server.
|
* @param svr The given server.
|
||||||
* @return The name of the server.
|
* @return The name of the server.
|
||||||
|
*
|
||||||
|
* The name returned is the name used to connect on this server.
|
||||||
*/
|
*/
|
||||||
EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr);
|
EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr);
|
||||||
|
|
||||||
|
@ -659,8 +732,8 @@ EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr);
|
||||||
* @return The total time, in seconds, that the server has been
|
* @return The total time, in seconds, that the server has been
|
||||||
* connected/running
|
* connected/running
|
||||||
*
|
*
|
||||||
* This function is used to find out how long a server has been
|
* This function is used to find out the time that has been elapsed since
|
||||||
* connected/running for.
|
* ecore_con_server_add() succeeded.
|
||||||
*/
|
*/
|
||||||
EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
|
EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
|
||||||
/**
|
/**
|
||||||
|
@ -671,6 +744,14 @@ EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
|
||||||
* @param size Length of the data, in bytes, to send.
|
* @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
|
* @return The number of bytes sent. @c 0 will be returned if there is an
|
||||||
* error.
|
* error.
|
||||||
|
*
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* @see ecore_con_client_send()
|
||||||
|
* @see ecore_con_server_flush()
|
||||||
*/
|
*/
|
||||||
EAPI int ecore_con_server_send(Ecore_Con_Server *svr,
|
EAPI int ecore_con_server_send(Ecore_Con_Server *svr,
|
||||||
const void *data,
|
const void *data,
|
||||||
|
@ -712,9 +793,14 @@ EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
|
||||||
*/
|
*/
|
||||||
EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr);
|
EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr);
|
||||||
/**
|
/**
|
||||||
* Flushes all pending data to the given server. Will return when done.
|
* Flushes all pending data to the given server.
|
||||||
*
|
*
|
||||||
* @param svr The given server.
|
* @param svr The given server.
|
||||||
|
*
|
||||||
|
* This function will block until all data is sent to the server.
|
||||||
|
*
|
||||||
|
* @see ecore_con_server_send()
|
||||||
|
* @see ecore_con_client_flush()
|
||||||
*/
|
*/
|
||||||
EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
|
EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
|
||||||
/**
|
/**
|
||||||
|
@ -723,12 +809,14 @@ EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
|
||||||
* @param svr The server object
|
* @param svr The server object
|
||||||
* @param timeout The timeout, in seconds, to disconnect after
|
* @param timeout The timeout, in seconds, to disconnect after
|
||||||
*
|
*
|
||||||
* This function is used to set the idle timeout on clients. A value of < 1
|
* This function is used by the server to set the default idle timeout on
|
||||||
* disables the idle timeout.
|
* 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.
|
||||||
*
|
*
|
||||||
* This timeout is not affected by the one set by
|
* This timeout is not affected by the one set by
|
||||||
* ecore_con_client_timeout_set(). A client will be disconnected whenever the
|
* ecore_con_client_timeout_set(). A client will be disconnected whenever the
|
||||||
* client or the server timeout is reached.
|
* 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.
|
||||||
*
|
*
|
||||||
* @see ecore_con_server_timeout_get()
|
* @see ecore_con_server_timeout_get()
|
||||||
* @see ecore_con_client_timeout_set()
|
* @see ecore_con_client_timeout_set()
|
||||||
|
@ -755,6 +843,19 @@ EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr);
|
||||||
/**
|
/**
|
||||||
* @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
|
* @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
|
||||||
*
|
*
|
||||||
|
* 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
|
||||||
|
* client. Most of them should be used on the server, applied on the client
|
||||||
|
* object.
|
||||||
|
*
|
||||||
|
* 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
|
||||||
|
*
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
@ -766,6 +867,14 @@ EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr);
|
||||||
* @param size Length of the data, in bytes, to send.
|
* @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
|
* @return The number of bytes sent. @c 0 will be returned if there is an
|
||||||
* error.
|
* error.
|
||||||
|
*
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* @see ecore_con_server_send()
|
||||||
|
* @see ecore_con_client_flush()
|
||||||
*/
|
*/
|
||||||
EAPI int ecore_con_client_send(Ecore_Con_Client *cl,
|
EAPI int ecore_con_client_send(Ecore_Con_Client *cl,
|
||||||
const void *data,
|
const void *data,
|
||||||
|
@ -813,9 +922,14 @@ EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl);
|
||||||
*/
|
*/
|
||||||
EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl);
|
EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl);
|
||||||
/**
|
/**
|
||||||
* Flushes all pending data to the given client. Will return when done.
|
* Flushes all pending data to the given client.
|
||||||
*
|
*
|
||||||
* @param cl The given client.
|
* @param cl The given client.
|
||||||
|
*
|
||||||
|
* This function will block until all data is sent to the server.
|
||||||
|
*
|
||||||
|
* @see ecore_con_client_send()
|
||||||
|
* @see ecore_con_server_flush()
|
||||||
*/
|
*/
|
||||||
EAPI void ecore_con_client_flush(Ecore_Con_Client *cl);
|
EAPI void ecore_con_client_flush(Ecore_Con_Client *cl);
|
||||||
/**
|
/**
|
||||||
|
@ -847,12 +961,16 @@ EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl);
|
||||||
* @param cl The client object
|
* @param cl The client object
|
||||||
* @param timeout The timeout, in seconds, to disconnect after
|
* @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
|
* This function is used by the server to set the idle timeout on a specific
|
||||||
* disables the idle timeout.
|
* 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.
|
||||||
*
|
*
|
||||||
* This timeout is not affected by the one set by
|
* This timeout is not affected by the one set by
|
||||||
* ecore_con_server_timeout_set(). A client will be disconnected whenever the
|
* ecore_con_server_timeout_set(). A client will be disconnected whenever the
|
||||||
* client or the server timeout is reached.
|
* 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.
|
||||||
|
*
|
||||||
* @see ecore_con_client_timeout_get()
|
* @see ecore_con_client_timeout_get()
|
||||||
* @see ecore_con_server_timeout_set()
|
* @see ecore_con_server_timeout_set()
|
||||||
*/
|
*/
|
||||||
|
|
Loading…
Reference in New Issue