cedric pushed a commit to branch master. http://git.enlightenment.org/website/www-content.git/commit/?id=2d1d2afcc114b3551723f8a9c5fdbb1de9a62fd9
commit 2d1d2afcc114b3551723f8a9c5fdbb1de9a62fd9 Author: Clément Bénier <[email protected]> Date: Thu Sep 3 10:29:25 2015 +0200 Wiki pages connectivity_pg created: 1 main + 5 PG + index Signed-off-by: Clément Bénier <[email protected]> --- pages/docs.txt | 1 + .../basic_usage_of_ecore_con_client.txt | 98 +++++++++++++ .../basic_usage_of_ecore_con_server.txt | 159 +++++++++++++++++++++ .../connectivity/basic_usage_of_ecore_con_url.txt | 120 ++++++++++++++++ .../connectivity/ecore_con_ssl_usage.txt | 72 ++++++++++ pages/program_guide/connectivity/index.txt | 4 + .../program_guide/connectivity/init_ecore_con.txt | 85 +++++++++++ pages/program_guide/connectivity_pg.txt | 23 +++ pages/program_guide/index.txt | 1 + 9 files changed, 563 insertions(+) diff --git a/pages/docs.txt b/pages/docs.txt index d5d8990..bb85741 100644 --- a/pages/docs.txt +++ b/pages/docs.txt @@ -63,6 +63,7 @@ Go check the current available version of EFL on each distro/platform: * [[program_guide/evas_pg|Evas PG]] * [[program_guide/edje_pg|Edje PG]] * [[program_guide/multilingual_pg|Multilingual PG]] + * [[program_guide/connectivity_pg|Connectivity PG]] === Samples === diff --git a/pages/program_guide/connectivity/basic_usage_of_ecore_con_client.txt b/pages/program_guide/connectivity/basic_usage_of_ecore_con_client.txt new file mode 100644 index 0000000..98b386a --- /dev/null +++ b/pages/program_guide/connectivity/basic_usage_of_ecore_con_client.txt @@ -0,0 +1,98 @@ +{{page>index}} +------- +===== Basic usage of Ecore_Con_Client ===== + +==== Connecting to the server ==== + +On the client side, we need to connect to the previously created server. + +<code c> +Ecore_Con_Server *svr; +svr = ecore_con_server_connect(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL); +</code> + +<note> +Here we consider that the client and the server are running on the same host. +</note> + +==== Registering callbacks ==== + +Like for the server, we then need to register callbacks on server events: + + * ''ECORE_CON_EVENT_SERVER_ADD'': to be notified when the server answers the connection request; + * ''ECORE_CON_EVENT_SERVER_DEL'': when the server disconnects; + * ''ECORE_CON_EVENT_SERVER_ERROR'': an error occurred when trying to reach the server; + * ''ECORE_CON_EVENT_SERVER_DATA'': a connected server has sent data. + +The ''_add_cb()'' calllback prints the name, IP address and port of the +server. It also prints if the client is well connected to the server. +''_del_cb()'' prints the IP address of the server and closes the connection on +the client side. ''_data_cb()'' prints the IP address of the server and the +length of the received data. The data is available to use thanks to the +''ev->data'' structure. + +Here follow the callbacks definitions: + +<code c> +Eina_Bool +_add_cb(void *data __UNUSED__, int type __UNUSED__, Ecore_Con_Event_Server_Add *ev) +{ + printf("Server connection: ip %s, name %s port %d, connected = %d\n", + ecore_con_server_ip_get(ev->server), + ecore_con_server_name_get(ev->server), + ecore_con_server_port_get(ev->server), + ecore_con_server_connected_get(ev->server)); + return ECORE_CALLBACK_RENEW; +} + +Eina_Bool +_del_cb(void *data __UNUSED__, int type __UNUSED__, Ecore_Con_Event_Server_Del *ev) +{ + printf("Server disconnected: ip %s\n", + ecore_con_server_ip_get(ev->server)); + // Close the connection with the server. + ecore_con_server_del(ev->server); + return ECORE_CALLBACK_RENEW; +} + +Eina_Bool +_data_cb(void *data __UNUSED__, int type __UNUSED__, Ecore_Con_Event_Server_Data *ev) +{ + printf("Received data from server: ip %s port %d size %i bytes\n", + ecore_con_server_ip_get(ev->server), + ecore_con_server_port_get(ev->server), + ev->size); + // ev->data holds the data sent by the server. + printf("%s\n",ev->data); + + return ECORE_CALLBACK_RENEW; +} +</code> + +and the registration for the server events: + +<code c> +/* set event handler for server connect */ +ecore_event_handler_add(ECORE_CON_EVENT_SERVER_ADD, (Ecore_Event_Handler_Cb)_add_cb, NULL); +/* set event handler for server disconnect */ +ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DEL, (Ecore_Event_Handler_Cb)_del_cb, NULL); +/* set event handler for receiving server data */ +ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DATA, (Ecore_Event_Handler_Cb)_data_cb, NULL); +</code> + +==== Sending data to the server ==== + +Once connected, we can send data to the server. + +<code c> +char hello[] = "hello Server ! I am the client."; +ecore_con_server_send(ev->server, hello, sizeof(hello)); +ecore_con_server_flush(ev->server); +</code> + +The ''ecore_con_server_send()'' function is used to send the data, and the +''ecore_con_server_flush()'' function is to avoid buffering and send this data +immediately to the server. + +------- +{{page>index}} diff --git a/pages/program_guide/connectivity/basic_usage_of_ecore_con_server.txt b/pages/program_guide/connectivity/basic_usage_of_ecore_con_server.txt new file mode 100644 index 0000000..026676b --- /dev/null +++ b/pages/program_guide/connectivity/basic_usage_of_ecore_con_server.txt @@ -0,0 +1,159 @@ +{{page>index}} +------- +===== Basic usage of Ecore_Con_Server ===== + +=== Table of Contents === + + * [[#Start_a_server|Start a server ]] + * [[#Configure_the_server|Configure the server ]] + * [[#Register_callbacks_on_events|Register callbacks on events]] + * [[#Sending_data_to_the_client|Sending data to the client]] + +==== Start a server ==== + +We create a ''Ecore_Con_Server'' object with the ''ecore_con_server_add''. +This function takes a connection type parameter that defines the type of the +connection that will be created with the client. This type can be composed of +several of the follwing values: + + * ''ECORE_CON_LOCAL_USER'': local user socket in “~/.ecore”; + * ''ECORE_CON_LOCAL_SYSTEM'': local system socket in “/tmp”; + * ''ECORE_CON_LOCAL_ABSTRACT'': abstract socket; + * ''ECORE_CON_REMOTE_TCP'': remote TCP server; + * ''ECORE_CON_REMOTE_UDP'': remote UDP server; + * ''ECORE_CON_REMOTE_MCAST'': remote multicast server; + * ''ECORE_CON_REMOTE_BROADCAST'': remote broadcast server; + * ''ECORE_CON_REMOTE_NODELAY'': remote connection sending data immediately without buffering; + * ''ECORE_CON_REMOTE_CORK'': remote connection sending large chunks of data; + * ''ECORE_CON_USE_SSL3'': enable SSL3; + * ''ECORE_CON_USE_TLS'': enable TLS; + * ''ECORE_CON_USE_MIXED'': enable both SSL3 and TLS; + * ''ECORE_CON_LOAD_CERT'': use a loaded certificate; + * ''ECORE_CON_NO_PROXY'': disable proxy on the server. + +<note> +To compose a type with more than one value, add a '|' between them. +</note> + +Here we will create a remote TCP server on the local host (127.0.0.1) that +will be listening on the port 8080. + +<code c> +Ecore_Con_Server *svr; +svr = ecore_con_server_add(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)); +</code> + +<note> +The ''ecore_con_server_add()'' function can return NULL if it cannot create +the server. +</note> + +==== Configure the server ==== + +We will set a maximum number of simultaneous connections to our server in +order to prevent it from being overloaded. As an example we will limit the +connections to three clients: if three clients are connected, a new oncoming +client will have to wait until one of the connected clients disconnects before +being able to actually connect to the server. + +<code c> +ecore_con_server_client_limit_set(svr, 3, 0); +</code> + +The last parameter of this function determines how the excess clients will be +rejected. If set to ''1'', the client that tries to connect will be +disconnected if there are already too many of them connected, whereas setting +to ''0'' will have the client wait until another client disconnects. + +To avoid a client holding a connection for too long, we can set a timeout +after which an inactive client will be disconnected. In the following example, +we set a ten seconds timeout. + +<code c> +ecore_con_server_timeout_set(svr, 10); +</code> + +==== Register callbacks on events ==== + +We need to register callbacks on events to be able to know when clients +connect to the server or send data. We can register callbacks on the following +events: + + * ''ECORE_CON_EVENT_CLIENT_ADD'': a client connects to the server; + * ''ECORE_CON_EVENT_CLIENT_DEL'': a client disconnects; + * ''ECORE_CON_EVENT_CLIENT_ERROR'': an error occurred while trying to reach the client; + * ''ECORE_CON_EVENT_CLIENT_DATA'': a connected client has sent data. + + +Here we only register callbacks on add, del and data events. The ''_add_cb()'' +callback prints the IP address and port of the client that just connected, and +also whether it is still connected. It then returns ''ECORE_CALLBACK_RENEW'' +to keep the callback handler on the ''ECORE_CON_EVENT_CLIENT_ADD'' event. + +The ''_del_cb()'' callback prints the IP address and the uptime of the client +that disconnects. It then calls ''ecore_con_client_del()'' to close the +connection and free the memory allocated to the client. + +Finally the ''_data_cb()'' callback prints the size of the data received by +the client. + +__Callbacks definition__: + +<code c> +static Eina_Bool +_add_cb(void *data __UNUSED__, int type __UNUSED__, Ecore_Con_Event_Client_Add *ev) +{ + printf("Client connection: ip %s, port %d, connected = %d!\n", + ecore_con_client_ip_get(ev->client), + ecore_con_client_port_get(ev->client), + ecore_con_client_connected_get(ev->client)); + return ECORE_CALLBACK_RENEW; +} + +static Eina_Bool +_del_cb(void *data __UNUSED__, int type __UNUSED__, Ecore_Con_Event_Client_Del *ev) +{ + printf("Client disconnected: ip %s uptime %0.3f seconds\n", + ecore_con_client_ip_get(ev->client), + ecore_con_client_uptime_get(ev->client)); + // Close the connection with the client + ecore_con_client_del(ev->client); + return ECORE_CALLBACK_RENEW; +} + +static Eina_Bool +_data_cb(void *data __UNUSED__, int type __UNUSED__, Ecore_Con_Event_Client_Data *ev) +{ + printf("Received data from client: ip %s port %d size %i bytes\n", + ecore_con_client_ip_get(ev->client), + ecore_con_client_port_get(ev->client,ev->size); + // ev->data contains the data sent by the client + printf("%s\n",ev->data); + return ECORE_CALLBACK_RENEW; +} +</code> + +Here are the callback registrations: + +<code c> +ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_ADD, (Ecore_Event_Handler_Cb)_add_cb, NULL); +ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DEL, (Ecore_Event_Handler_Cb)_del_cb, NULL); +ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DATA, (Ecore_Event_Handler_Cb)_data_cb, NULL); +</code> + +==== Sending data to the client ==== + +Once connected, we can send data to the client. + +<code c> +char hello[] = "hello Client ! I am the server."; +ecore_con_client_send(ev->client, hello, sizeof(hello)); +ecore_con_client_flush(ev->client); +</code> + +The ''ecore_con_client_send()'' function is used to send the data, and the +''ecore_con_client_flush()'' function is to avoid buffering and sending this +data to the client immediately. + +{{page>index}} +------- diff --git a/pages/program_guide/connectivity/basic_usage_of_ecore_con_url.txt b/pages/program_guide/connectivity/basic_usage_of_ecore_con_url.txt new file mode 100644 index 0000000..5ac7e0e --- /dev/null +++ b/pages/program_guide/connectivity/basic_usage_of_ecore_con_url.txt @@ -0,0 +1,120 @@ +{{page>index}} +------- +===== Basic usage of Ecore_Con_Url ===== + +The Ecore URL connection library is an HTTP abstraction. It makes it easy to +perform HTTP requests like ''POST'', ''GET'', … + +=== Table of Contents === + + * [[#Initialisation_and_URL_set|Initialisation and URL set]] + * [[#Download_a_file|Download a file]] + * [[#Ecore_File_usage|Ecore File usage]] + +==== Initialisation and URL set ==== + +First, we need to initialise the Ecore URL connection library and create a +''Ecore_Con_Url'' object. + +<note> +The Ecore_Con library shall also be initialized as described in the previous +chapter. +</note> + +<code c> +Ecore_Con_Url *ec_url = NULL; +// Initiate Ecore Url connection library. +ecore_con_url_init(); +// Create the Ecore_Con_Url object passing the URL that will receive the +// requests as an argument. +ec_url = ecore_con_url_new("http://www.enlightenment.org";); +</code> + +<note> +''ecore_con_url_new()'' will return NULL on error, so be careful to check the +returned object before using it. +</note> + +The URL can be modified using ''ecore_con_url_url_set()''. Here we will set it +to [[https://docs.enlightenment.org/efl/1.15.0/index.html]]. + +<code c> +Eina_Bool ret = ecore_con_url_url_set(ec_url, "https://docs.enlightenment.org/efl/1.15.0/index.html";); +</code> + +The ''return'' value will contain ''EINA_FALSE'' if the new URL cannot be set. + +==== Download a file ==== + +To download a file, we first need to create a local file and open it with +write access. We can then give the file descriptor to the Ecore URL connection +library so that it can write to it. + +We can then register a callback on the following events: + +^ ''ECORE_CON_EVENT_URL_PROGRESS'' |happens when the URL object transfer has made progress. \\ It gives the total and current data status of the transfer (upload and download).| +^ ''ECORE_CON_EVENT_URL_COMPLETE'' |happens when the URL object has completed a transfer. \\ It returns the HTTP status code of the operation.| +^ ''ECORE_CON_EVENT_URL_DATA'' |happens when the URL object has received data. \\ It gives the size of the received data and a buffer containing the data.| + +<note> +''ECORE_CON_EVENT_URL_DATA'' event will not be emitted if a file has been set +to receive the response data with ''ecore_con_url_fd_set()''. +</note> + +Here we only register callbacks for the complete and progress events. + +<code c> +static Eina_Bool +_url_progress_cb(void *data __UNUSED__, int type __UNUSED__, void *event_info) +{ + Ecore_Con_Event_Url_Progress *url_progress = event_info; + printf("Download progress : %d\n", (url_progress->down.now / url_progress->down.total) * 100); + return EINA_TRUE; +} + +static Eina_Bool +_url_complete_cb(void *data __UNUSED__, int type __UNUSED__, void *event_info) +{ + Ecore_Con_Event_Url_Complete *url_complete = event_info; + printf("Download completed with status: %d\n", url_complete->status); + return EINA_TRUE; +} + +ecore_event_handler_add(ECORE_CON_EVENT_URL_PROGRESS, _url_progress_cb, NULL); +ecore_event_handler_add(ECORE_CON_EVENT_URL_COMPLETE, _url_complete_cb, NULL); +</code> + +Once the URL is set up and the callbacks are registered, we can launch the GET +request. + +<code c> +ecore_con_url_get(ec_url); +</code> + +The status of the request will be shown in the ''_url_complete_cb()'' and the +progress will be reported by the ''_url_progress_cb()'' function. + +==== Ecore File usage ==== + +The Ecore File library provides an abstraction of the Ecore URL connection +library. All that we described previously can be done with one function call. + +<code c> +Ecore_File_Download_Job *jobret; +ecore_file_download(http://www.enlightenment.org, + file: + _url_complete_cb, + _url_progress_cb, + NULL, + &job_ret); +</code> + +We first pass the url string we want to download, the local filename where it +needs to be written, then the complete and progress callbacks with the data to +pass to them (here ''NULL''). Finally, it takes a ''Ecore_File_Download_Job'' +structure that is filled by the function and which can be used with +''ecore_file_download_abort()'' to cancel the current download. + + +------- +{{page>index}} diff --git a/pages/program_guide/connectivity/ecore_con_ssl_usage.txt b/pages/program_guide/connectivity/ecore_con_ssl_usage.txt new file mode 100644 index 0000000..f6c5a4a --- /dev/null +++ b/pages/program_guide/connectivity/ecore_con_ssl_usage.txt @@ -0,0 +1,72 @@ +{{page>index}} +------- +==== Ecore_con_ssl usage ==== + +Several functions are available to be able to use SSL. These functions can be +used on the server side. + +First, we can check whether SSL is supported on the host. + +<code c> +int ssl = ecore_con_ssl_available_get(); +</code> + +This function returns ''1'' if SSL is provided by GnuTLS, ''2'' if provided by +OpenSSL, and ''0'' if SSL is not supported. + +Several functions are available to add SSL certificate and private keys for +use when connecting or listening: + + * ''ecore_con_ssl_server_cert_add()'' to add a SSL PEM certificate; + * ''ecore_con_ssl_server_privkey_add()'' to add a SSL PEM private key; + * ''ecore_con_ssl_server_crl_add()'' to add a SSL PEM CRL file; + * ''ecore_con_ssl_server_cafile_add()'' to add a SSL PEM CA file. + +We can then enable certification verification on the server object against +loaded certificates. + +<code c> +ecore_con_ssl_server_verify(svr); +</code> + +Certification verification can be done using <em>only</em> the hostnames. + +<code c> +ecore_con_ssl_server_verify_basic(svr); +</code> + +Sometimes, the certificate hostname does not match with the hostname we are +trying to connect to. We can set the hostname to verify against in certificate +verification. Here we set the hostname to “enlightenment.org”. + +<code c> +ecore_con_ssl_server_verify_name_set(svr, "enlightenment.org"); +</code> + +==== Upgrade a connection ==== + +We can also upgrade a connection to a specified level of encryption. + +From the client: + +<code c> +ecore_con_ssl_server_upgrade(srv, ECORE_CON_USE_SSL3); +</code> + +<note> +Never use this function on the server side! +</note> + +From the server: + +<code c> +ecore_con_ssl_client_upgrade(srv, ECORE_CON_USE_SSL3); +</code> + +These functions will start a SSL handshake on a connection. Once the upgrade +has been completed, ''ECORE_CON_EVENT_SERVER_UPGRADE'' or +''ECORE_CON_EVENT_CLIENT_UPGRADE'' events will be emitted. The connection +should be treated as disconnected until the next event. + +------- +{{page>index}} diff --git a/pages/program_guide/connectivity/index.txt b/pages/program_guide/connectivity/index.txt new file mode 100644 index 0000000..28b0212 --- /dev/null +++ b/pages/program_guide/connectivity/index.txt @@ -0,0 +1,4 @@ +++++Connectivity Menu| +^ [[/program_guide/connectivity_pg|Connectivity PG]] ^^^^^ +| [[/program_guide/connectivity/init_ecore_con|Init Ecore_Con]] | [[/program_guide/connectivity/basic_usage_of_ecore_con_url|Basic usage of Ecore_con_url]] | [[/program_guide/connectivity/basic_usage_of_ecore_con_server|Basic usage of Ecore_con_server]] | [[/program_guide/connectivity/basic_usage_of_ecore_con_client|Basic usage of Ecore_con_client]] | [[/program_guide/connectivity/ecore_con_ssl usage|Ecore_con_ssl Usage]] | +++++ diff --git a/pages/program_guide/connectivity/init_ecore_con.txt b/pages/program_guide/connectivity/init_ecore_con.txt new file mode 100644 index 0000000..382d7e2 --- /dev/null +++ b/pages/program_guide/connectivity/init_ecore_con.txt @@ -0,0 +1,85 @@ +{{page>index}} +------- +===== Init Ecore_Con ===== + +Before using the Ecore_Con library, it needs to be initialized. + +<code c> +#include <Ecore_Con.h> +// Init ecore_con library. +int ret = ecore_con_init(); +// ret is the number of times the library has been initialized +// without shutdown. + +</code> + +==== Asynchronous DNS lookup ==== + +We can do a simple DNS lookup using the following function: + +<code c> +EAPI Eina_Bool ecore_con_lookup(const char * name, + Ecore_Con_Dns_Cb done_cb, + const void * data + ) +</code> + +in which: + + * ''name'': the IP address or the server name to translate; + * ''done_cb'': a callback to notify when the request is done; + * ''data'': the data to be passed to the callback. + +The ''done_cb'' function prototype is : + + +<code c> +void done_cb(const char * canonname, + const char * ip, + struct sockaddr * addr, + int addrlen, + void * data + ) +</code> + +where: + + * ''canonname'': the canonical name associated with the address; + * ''ip'': the resolved IP address; + * ''addr'': a pointer to the socket address; + * ''addrlen'': the length of the socket address, in bytes; + * ''data'': the data passed to the callback. + +As an example, we want to know the canonical name of the 140.211.167.135 IP +address. Let’s first declare the ''done_cb'' callback that will be called when +the DNS lookup will finish. + +<code c> +static void +done_cb(const char *canonname, const char *ip, struct sockaddr *addr, int addrlen, void *data) +{ + printf("140.211.167.135 name is %s\n", canonname); +} + +</code> + +Then we can call the ''ecore_con_lookup()'' function to do the query. + +<code c> +// Call ecore_con_lookup. +ret = ecore_con_lookup("140.211.167.135", done_cb, NULL); +// If ret is EINA_FALSE the request failed to set up. +</code> + +When the request succeeds it shall call the ''done_cb()'' callback that will +printthe name associated with the IP address we gave. + +When the library is not be used anymore, it has to be shut down. + +<code c> +// Shutdown the library. +ret = ecore_con_shutdown(); +</code> + +------ +{{page>index}} diff --git a/pages/program_guide/connectivity_pg.txt b/pages/program_guide/connectivity_pg.txt new file mode 100644 index 0000000..d005799 --- /dev/null +++ b/pages/program_guide/connectivity_pg.txt @@ -0,0 +1,23 @@ +{{page>index}} +------- +===== Conncetivity PG ===== + +The Ecore connection library provides a way to make your application +communicate through sockets abstracting some of the tasks that are not really +interesting to do (like creating file descriptors and waiting for incoming +connections). + +=== Table of Contents === + + * [[/program_guide/connectivity/init_ecore_con|Init Ecore_Con]] + * [[/program_guide/connectivity/basic_usage_of_ecore_con_url|Basic usage of Ecore_con_url]] + * [[/program_guide/connectivity/basic_usage_of_ecore_con_server|Basic usage of Ecore_con_server]] + * [[/program_guide/connectivity/basic_usage_of_ecore_con_client|Basic usage of Ecore_con_client]] + * [[/program_guide/connectivity/ecore_con_ssl usage|Ecore_con_ssl Usage]] + +=== Related Info === + + * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Ecore__Con__Group.html|Ecore_Con - Connection functions API]] + +------- +{{page>index}} diff --git a/pages/program_guide/index.txt b/pages/program_guide/index.txt index cfcf599..d082190 100644 --- a/pages/program_guide/index.txt +++ b/pages/program_guide/index.txt @@ -6,4 +6,5 @@ * [[program_guide/evas_pg|Evas PG]] * [[program_guide/edje_pg|Edje PG]] * [[program_guide/multilingual_pg|Multilingual PG]] + * [[program_guide/connectivity_pg|Connectivity PG]] ++++ --
