Wiki pages connectivity_pg created: 1 main + 5 PG + index

Signed-off-by: Clément Bénier <clement.benier@openwide.fr>
This commit is contained in:
Clément Bénier 2015-09-03 10:29:25 +02:00 committed by Cedric BAIL
parent 89c96566b5
commit 2d1d2afcc1
9 changed files with 563 additions and 0 deletions

View File

@ -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 ===

View File

@ -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-&gt;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}}

View File

@ -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}}
-------

View File

@ -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}}

View File

@ -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}}

View File

@ -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]] |
++++

View File

@ -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. Lets 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}}

View File

@ -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}}

View File

@ -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]]
++++