aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/ecore/src/lib/ecore_con/Ecore_Con.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/ecore/src/lib/ecore_con/Ecore_Con.h')
-rw-r--r--libraries/ecore/src/lib/ecore_con/Ecore_Con.h1801
1 files changed, 1801 insertions, 0 deletions
diff --git a/libraries/ecore/src/lib/ecore_con/Ecore_Con.h b/libraries/ecore/src/lib/ecore_con/Ecore_Con.h
new file mode 100644
index 0000000..e3b68c4
--- /dev/null
+++ b/libraries/ecore/src/lib/ecore_con/Ecore_Con.h
@@ -0,0 +1,1801 @@
1#ifndef _ECORE_CON_H
2#define _ECORE_CON_H
3
4#include <time.h>
5#include <libgen.h>
6#ifdef _WIN32
7# include <ws2tcpip.h>
8#else
9# include <netdb.h>
10#endif
11#include <Eina.h>
12
13#ifdef EAPI
14# undef EAPI
15#endif
16
17#ifdef _WIN32
18# ifdef EFL_ECORE_CON_BUILD
19# ifdef DLL_EXPORT
20# define EAPI __declspec(dllexport)
21# else
22# define EAPI
23# endif
24# else
25# define EAPI __declspec(dllimport)
26# endif
27#else
28# ifdef __GNUC__
29# if __GNUC__ >= 4
30# define EAPI __attribute__ ((visibility("default")))
31# else
32# define EAPI
33# endif
34# else
35# define EAPI
36# endif
37#endif
38
39/**
40 * @defgroup Ecore_Con_Group Ecore_Con - Connection functions
41 *
42 * The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
43 * for communications between programs using reliable sockets. It saves
44 * the programmer from having to worry about file descriptors and waiting
45 * for incoming connections.
46 *
47 * There are two main objects in the @c Ecore_Con library: the @c
48 * Ecore_Con_Server and the @c Ecore_Con_Client.
49 *
50 * The @c Ecore_Con_Server represents a server that can be connected to.
51 * It is used regardless of whether the program is acting as a server or
52 * client itself.
53 *
54 * To create a listening server call @c ecore_con_server_add(), optionally using
55 * an ECORE_CON_USE_* encryption type OR'ed with the type for encryption.
56 *
57 * To connect to a server, call @c ecore_con_server_connect(). Data can
58 * then be sent to the server using the @c ecore_con_server_send().
59 *
60 * Functions are described in the following groupings:
61 * @li @ref Ecore_Con_Lib_Group
62 * @li @ref Ecore_Con_Server_Group
63 * @li @ref Ecore_Con_Client_Group
64 * @li @ref Ecore_Con_Url_Group
65 *
66 * Events are described in @ref Ecore_Con_Events_Group.
67 */
68
69
70/**
71 * @defgroup Ecore_Con_Events_Group Events
72 *
73 * @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
74 * @c Ecore_Con_Server, an event of this type is emitted, allowing the
75 * retrieval of the client's ip with @ref ecore_con_client_ip_get and
76 * associating data with the client using ecore_con_client_data_set.
77 * @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
78 * @c Ecore_Con_Server, an event of this type is emitted. The contents of
79 * the data with this event are variable, but if the client object in the data
80 * is non-null, it must be freed with @ref ecore_con_client_del.
81 * @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
82 * with @ref ecore_con_server_connect, an event of this type is emitted,
83 * allowing for data to be serialized and sent to the server using
84 * @ref ecore_con_server_send. At this point, the http handshake has
85 * occurred.
86 * @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
87 * usually by the server connection being refused or dropped, an event of this
88 * type is emitted. The contents of the data with this event are variable,
89 * but if the server object in the data is non-null, it must be freed
90 * with @ref ecore_con_server_del.
91 * @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server
92 * object and sends data, an event of this type is emitted. The data will contain both
93 * the size and contents of the message sent by the client. It should be noted that
94 * data within this object is transient, so it must be duplicated in order to be
95 * retained. This event will continue to occur until the client has stopped sending its
96 * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
97 * been received in full, the client object must be freed with ecore_con_client_free.
98 * @li ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination
99 * and receives data, an event of this type is emitted. The data will contain both
100 * the size and contents of the message sent by the server. It should be noted that
101 * data within this object is transient, so it must be duplicated in order to be
102 * retained. This event will continue to occur until the server has stopped sending its
103 * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
104 * been received in full, the server object must be freed with ecore_con_server_free.
105 *
106 */
107
108/**
109 * @defgroup Ecore_Con_Buffer Buffering
110 *
111 * As Ecore_Con works on an event driven design, as data arrives, events will
112 * be produced containing the data that arrived. It is up to the user of
113 * Ecore_Con to either parse as they go, append to a file to later parse the
114 * whole file in one go, or append to memory to parse or handle leter.
115 *
116 * To help with this Eina has some handy API's. The Eina_Binbuf and
117 * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial
118 * to handle buffers at runtime, without having to manage them. Eina_Binbuf
119 * makes it possible to create, expand, reset and slice a blob of memory -
120 * all via API. No system calls, no pointer manipulations and no size
121 * calculation.
122 *
123 * Additional functions include adding content at specified byte positions in
124 * the buffer, escaping the inputs, find and replace strings. This provides
125 * extreme flexibility to play around, with a dynamic blob of memory.
126 *
127 * It is good to free it (using eina_binbuf_free()) after using it.
128 *
129 * Eina_Binbuf compliments Ecore_Con use cases, where dynamic sizes of data
130 * arrive from the network (think http download in chunks). Using
131 * Eina_Binbuf provides enough flexibility to handle data as it arrives and
132 * to defer its processing until desired, without having to think about
133 * where to store the temporary data and how to manage its size.
134 *
135 * An example of how to use these with Ecore_Con follows.
136 *
137 * @code
138 * #include <Eina.h>
139 * #include <Ecore.h>
140 * #include <Ecore_Con.h>
141 *
142 * static Eina_Bool
143 * data_callback(void *data, int type, void *event)
144 * {
145 * Ecore_Con_Event_Url_Data *url_data = event;
146 * if ( url_data->size > 0)
147 * {
148 * // append data as it arrives - don't worry where or how it gets stored.
149 * // Also don't worry about size, expanding, reallocing etc.
150 * // just keep appending - size is automatically handled.
151 *
152 * eina_binbuf_append_length(data, url_data->data, url_data->size);
153 *
154 * fprintf(stderr, "Appended %d \n", url_data->size);
155 * }
156 * return EINA_TRUE;
157 * }
158 *
159 *
160 *
161 * static Eina_Bool
162 * completion_callback(void *data, int type, void *event)
163 * {
164 * Ecore_Con_Event_Url_Complete *url_complete = event;
165 * printf("download completed with status code: %d\n", url_complete->status);
166 *
167 * // get the data back from Eina_Binbuf
168 * char *ptr = eina_binbuf_string_get(data);
169 * size_t size = eina_binbuf_length_get(data);
170 *
171 * // process data as required (write to file)
172 * fprintf(stderr, "Size of data = %d bytes\n", size);
173 * int fd = open("./elm.png", O_CREAT);
174 * write(fd, ptr, size);
175 * close(fd);
176 *
177 * // free it when done.
178 * eina_binbuf_free(data);
179 *
180 * ecore_main_loop_quit();
181 *
182 * return EINA_TRUE;
183 * }
184 *
185 *
186 * int
187 * main(int argc, char **argv)
188 * {
189 *
190 * const char *url = "http://www.enlightenment.org/p/index/d/logo.png";
191 *
192 * ecore_init();
193 * ecore_con_init();
194 * ecore_con_url_init();
195 *
196 *
197 * // This is single additional line to manage dynamic network data.
198 * Eina_Binbuf *data = eina_binbuf_new();
199 * Ecore_Con_Url *url_con = ecore_con_url_new(url);
200 *
201 * ecore_event_handler_add(ECORE_CON_EVENT_URL_COMPLETE,
202 * completion_callback,
203 * data);
204 * ecore_event_handler_add(ECORE_CON_EVENT_URL_DATA,
205 * data_callback,
206 * data);
207 * ecore_con_url_get(url_con);
208 *
209 * ecore_main_loop_begin();
210 * return 0;
211 * }
212 * @endcode
213 */
214
215#ifdef __cplusplus
216extern "C" {
217#endif
218#define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
219#define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
220
221
222/**
223 * @typedef Ecore_Con_Server
224 * A connection handle to a server
225 * @ingroup Ecore_Con_Server_Group
226 */
227typedef struct _Ecore_Con_Server Ecore_Con_Server;
228
229/**
230 * @typedef Ecore_Con_Client
231 * A connection handle to a client
232 * @ingroup Ecore_Con_Client_Group
233 */
234typedef struct _Ecore_Con_Client Ecore_Con_Client;
235
236/**
237 * @typedef Ecore_Con_Url
238 * A handle to an http upload/download object
239 * @ingroup Ecore_Con_Url_Group
240 */
241typedef struct _Ecore_Con_Url Ecore_Con_Url;
242
243
244/**
245 * @addtogroup Ecore_Con_Events_Group Events
246 * @{
247 */
248
249/**
250 * @typedef Ecore_Con_Event_Client_Add
251 * Used as the @p data param for the corresponding event
252 */
253typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
254
255/**
256 * @typedef Ecore_Con_Event_Client_Upgrade
257 * Used as the @p data param for the corresponding event
258 * @since 1.1
259 */
260typedef struct _Ecore_Con_Event_Client_Upgrade Ecore_Con_Event_Client_Upgrade;
261
262/**
263 * @typedef Ecore_Con_Event_Client_Del
264 * Used as the @p data param for the corresponding event
265 */
266typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
267
268/**
269 * @typedef Ecore_Con_Event_Client_Error
270 * Used as the @p data param for the corresponding event
271 * @since 1.1
272 */
273typedef struct _Ecore_Con_Event_Client_Error Ecore_Con_Event_Client_Error;
274
275/**
276 * @typedef Ecore_Con_Event_Server_Add
277 * Used as the @p data param for the corresponding event
278 */
279typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
280
281/**
282 * @typedef Ecore_Con_Event_Server_Upgrade
283 * Used as the @p data param for the corresponding event
284 * @since 1.1
285 */
286typedef struct _Ecore_Con_Event_Server_Upgrade Ecore_Con_Event_Server_Upgrade;
287
288/**
289 * @typedef Ecore_Con_Event_Server_Del
290 * Used as the @p data param for the corresponding event
291 */
292typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
293
294/**
295 * @typedef Ecore_Con_Event_Server_Error
296 * Used as the @p data param for the corresponding event
297 * @since 1.1
298 */
299typedef struct _Ecore_Con_Event_Server_Error Ecore_Con_Event_Server_Error;
300
301/**
302 * @typedef Ecore_Con_Event_Client_Data
303 * Used as the @p data param for the corresponding event
304 */
305typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
306
307/**
308 * @typedef Ecore_Con_Event_Server_Data
309 * Used as the @p data param for the corresponding event
310 */
311typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
312
313/**
314 * @typedef Ecore_Con_Event_Client_Write
315 * Used as the @p data param for the corresponding event
316 * @since 1.1
317 */
318typedef struct _Ecore_Con_Event_Client_Write Ecore_Con_Event_Client_Write;
319
320/**
321 * @typedef Ecore_Con_Event_Server_Write
322 * Used as the @p data param for the corresponding event
323 * @since 1.1
324 */
325typedef struct _Ecore_Con_Event_Server_Write Ecore_Con_Event_Server_Write;
326
327/**
328 * @typedef Ecore_Con_Event_Url_Data
329 * Used as the @p data param for the corresponding event
330 * @ingroup Ecore_Con_Url_Group
331 */
332typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
333
334/**
335 * @typedef Ecore_Con_Event_Url_Complete
336 * Used as the @p data param for the corresponding event
337 * @ingroup Ecore_Con_Url_Group
338 */
339typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
340
341/**
342 * @typedef Ecore_Con_Event_Url_Progress
343 * Used as the @p data param for the corresponding event
344 * @ingroup Ecore_Con_Url_Group
345 */
346typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
347
348/**
349 * @struct _Ecore_Con_Event_Client_Add
350 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event
351 */
352struct _Ecore_Con_Event_Client_Add
353{
354 Ecore_Con_Client *client; /** the client that connected */
355};
356
357/**
358 * @struct _Ecore_Con_Event_Client_Upgrade
359 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event
360 * @since 1.1
361 */
362struct _Ecore_Con_Event_Client_Upgrade
363{
364 Ecore_Con_Client *client; /** the client that completed handshake */
365};
366
367/**
368 * @struct _Ecore_Con_Event_Client_Del
369 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event
370 */
371struct _Ecore_Con_Event_Client_Del
372{
373 Ecore_Con_Client *client; /** the client that was lost */
374};
375
376/**
377 * @struct _Ecore_Con_Event_Client_Error
378 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event
379 */
380struct _Ecore_Con_Event_Client_Error
381{
382 Ecore_Con_Client *client; /** the client for which an error occurred */
383 char *error; /**< the error string describing what happened */
384};
385
386/**
387 * @struct _Ecore_Con_Event_Server_Add
388 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event
389 */
390struct _Ecore_Con_Event_Server_Add
391{
392 Ecore_Con_Server *server; /** the server that was connected to */
393};
394
395/**
396 * @struct _Ecore_Con_Event_Server_Upgrade
397 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event
398 * @since 1.1
399 */
400struct _Ecore_Con_Event_Server_Upgrade
401{
402 Ecore_Con_Server *server; /** the server that was connected to */
403};
404
405/**
406 * @struct _Ecore_Con_Event_Server_Del
407 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event
408 */
409struct _Ecore_Con_Event_Server_Del
410{
411 Ecore_Con_Server *server; /** the client that was lost */
412};
413
414/**
415 * @struct _Ecore_Con_Event_Server_Error
416 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event
417 */
418struct _Ecore_Con_Event_Server_Error
419{
420 Ecore_Con_Server *server; /** the server for which an error occurred */
421 char *error; /**< the error string describing what happened */
422};
423
424/**
425 * @struct _Ecore_Con_Event_Client_Data
426 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event
427 */
428struct _Ecore_Con_Event_Client_Data
429{
430 Ecore_Con_Client *client; /**< the client that connected */
431 void *data; /**< the data that the client sent */
432 int size; /**< the length of the data sent */
433};
434
435/**
436 * @struct _Ecore_Con_Event_Server_Data
437 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
438 */
439struct _Ecore_Con_Event_Server_Data
440{
441 Ecore_Con_Server *server; /**< the server that was connected to */
442 void *data; /**< the data that the server sent */
443 int size; /**< the length of the data sent */
444};
445
446/**
447 * @struct _Ecore_Con_Event_Client_Write
448 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event
449 */
450struct _Ecore_Con_Event_Client_Write
451{
452 Ecore_Con_Client *client; /**< the client that connected */
453 int size; /**< the length of the data sent */
454};
455
456/**
457 * @struct _Ecore_Con_Event_Server_Write
458 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event
459 */
460struct _Ecore_Con_Event_Server_Write
461{
462 Ecore_Con_Server *server; /**< the server that was connected to */
463 int size; /**< the length of the data sent */
464};
465
466/**
467 * @struct _Ecore_Con_Event_Url_Data
468 * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event
469 * @ingroup Ecore_Con_Url_Group
470 */
471struct _Ecore_Con_Event_Url_Data
472{
473 Ecore_Con_Url *url_con; /**< a pointer to the connection object */
474 int size; /**< the size of the current received data (in bytes) */
475 unsigned char data[1]; /**< the data received on this event */
476};
477
478/**
479 * @struct _Ecore_Con_Event_Url_Complete
480 * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event
481 * @ingroup Ecore_Con_Url_Group
482 */
483struct _Ecore_Con_Event_Url_Complete
484{
485 Ecore_Con_Url *url_con; /**< a pointer to the connection object */
486 int status; /**< HTTP status code of the operation (200, 404, 401, etc.) */
487};
488
489/**
490 * @struct _Ecore_Con_Event_Url_Progress
491 * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event
492 * @ingroup Ecore_Con_Url_Group
493 */
494struct _Ecore_Con_Event_Url_Progress
495{
496 Ecore_Con_Url *url_con; /**< a pointer to the connection object */
497 struct
498 {
499 double total; /**< total size of the downloading data (in bytes) */
500 double now; /**< current size of the downloading data (in bytes) */
501 } down; /**< download info */
502 struct
503 {
504 double total; /**< total size of the uploading data (in bytes) */
505 double now; /**< current size of the uploading data (in bytes) */
506 } up; /**< upload info */
507};
508
509/** A client has connected to the server */
510EAPI extern int ECORE_CON_EVENT_CLIENT_ADD;
511/** A client has disconnected from the server */
512EAPI extern int ECORE_CON_EVENT_CLIENT_DEL;
513/** A client experienced an error
514 * @since 1.1
515 */
516EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR;
517/** A client connection has been upgraded to SSL
518 * @since 1.1
519 */
520EAPI extern int ECORE_CON_EVENT_CLIENT_UPGRADE;
521/** A server was created */
522EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
523/** A server connection was lost */
524EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
525/** A server experienced an error
526 * @since 1.1
527 */
528EAPI extern int ECORE_CON_EVENT_SERVER_ERROR;
529/** A server connection has been upgraded to SSL
530 * @since 1.1
531 */
532EAPI extern int ECORE_CON_EVENT_SERVER_UPGRADE;
533/** A server connection has sent data to its client
534 * @since 1.1
535 */
536EAPI extern int ECORE_CON_EVENT_CLIENT_WRITE;
537/** A server connection object has sent data
538 * @since 1.1
539 */
540EAPI extern int ECORE_CON_EVENT_SERVER_WRITE;
541/** A client connected to the server has sent data */
542EAPI extern int ECORE_CON_EVENT_CLIENT_DATA;
543/** A server connection object has data */
544EAPI extern int ECORE_CON_EVENT_SERVER_DATA;
545/** A URL object has data */
546EAPI extern int ECORE_CON_EVENT_URL_DATA;
547/** A URL object has completed its transfer to and from the server and can be reused */
548EAPI extern int ECORE_CON_EVENT_URL_COMPLETE;
549/** A URL object has made progress in its transfer */
550EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
551
552/**
553 * @}
554 */
555
556/**
557 * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
558 *
559 * Utility functions that set up and shut down the Ecore Connection
560 * library.
561 *
562 * There's also ecore_con_lookup() that can be used to make simple asynchronous
563 * DNS lookups.
564 *
565 * A simple example of how to use these functions:
566 * @li @ref ecore_con_lookup_example_c
567 *
568 * @{
569 */
570
571/**
572 * @typedef Ecore_Con_Dns_Cb
573 * A callback type for use with @ref ecore_con_lookup.
574 */
575typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
576 const char *ip,
577 struct sockaddr *addr,
578 int addrlen,
579 void *data);
580
581/**
582 * @typedef Ecore_Con_Type
583 * @enum _Ecore_Con_Type
584 * Types for an ecore_con client/server object. A correct way to set this type is
585 * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
586 * and LOAD_CERT if the previously loaded certificate should be used.
587 * @code
588 * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
589 * @endcode
590 * @ingroup Ecore_Con_Server_Group
591 */
592typedef enum _Ecore_Con_Type
593{
594 /** Socket in ~/.ecore */
595 ECORE_CON_LOCAL_USER = 0,
596 /** Socket in /tmp */
597 ECORE_CON_LOCAL_SYSTEM = 1,
598 /** Abstract socket */
599 ECORE_CON_LOCAL_ABSTRACT = 2,
600 /** Remote server using TCP */
601 ECORE_CON_REMOTE_TCP = 3,
602 /** Remote multicast server */
603 ECORE_CON_REMOTE_MCAST = 4,
604 /** Remote server using UDP */
605 ECORE_CON_REMOTE_UDP = 5,
606 /** Remote broadcast using UDP */
607 ECORE_CON_REMOTE_BROADCAST = 6,
608 ECORE_CON_REMOTE_NODELAY = 7,
609 /** Use SSL2: UNSUPPORTED. **/
610 ECORE_CON_USE_SSL2 = (1 << 4),
611 /** Use SSL3 */
612 ECORE_CON_USE_SSL3 = (1 << 5),
613 /** Use TLS */
614 ECORE_CON_USE_TLS = (1 << 6),
615 /** Use both TLS and SSL3 */
616 ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
617 /** Attempt to use the loaded certificate */
618 ECORE_CON_LOAD_CERT = (1 << 7)
619} Ecore_Con_Type;
620
621/**
622 * Initialises the Ecore_Con library.
623 * @return Number of times the library has been initialised without being
624 * shut down.
625 *
626 * @note This function already calls ecore_init() internally, so you don't need
627 * to call it explicitly.
628 */
629EAPI int ecore_con_init(void);
630
631/**
632 * Shuts down the Ecore_Con library.
633 * @return Number of times the library has been initialised without being
634 * shut down.
635 * @note This function already calls ecore_shutdown() internally, so you don't
636 * need to call it explicitly unless you called ecore_init() explicitly too.
637 */
638EAPI int ecore_con_shutdown(void);
639
640/**
641 * Do an asynchronous DNS lookup.
642 *
643 * @param name IP address or server name to translate.
644 * @param done_cb Callback to notify when done.
645 * @param data User data to be given to done_cb.
646 * @return EINA_TRUE if the request did not fail to be set up, EINA_FALSE if it
647 * failed.
648 *
649 * This function performs a DNS lookup on the hostname specified by @p name,
650 * then calls @p done_cb with the result and the @p data given as parameter.
651 * The result will be given to the @p done_cb as follows:
652 * @li @c canonname - the canonical name of the address
653 * @li @c ip - the resolved ip address
654 * @li @c addr - a pointer to the socket address
655 * @li @c addrlen - the length of the socket address, in bytes
656 * @li @c data - the data pointer given as parameter to ecore_con_lookup()
657 */
658EAPI Eina_Bool ecore_con_lookup(const char *name,
659 Ecore_Con_Dns_Cb done_cb,
660 const void *data);
661
662/**
663 * @}
664 */
665
666/**
667 * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
668 *
669 * @{
670 */
671EAPI int ecore_con_ssl_available_get(void);
672EAPI Eina_Bool ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert);
673EAPI Eina_Bool ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file);
674EAPI Eina_Bool ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file);
675EAPI Eina_Bool ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file);
676EAPI void ecore_con_ssl_server_verify(Ecore_Con_Server *svr);
677EAPI void ecore_con_ssl_server_verify_basic(Ecore_Con_Server *svr);
678EAPI Eina_Bool ecore_con_ssl_server_upgrade(Ecore_Con_Server *svr, Ecore_Con_Type compl_type);
679EAPI Eina_Bool ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_Con_Type compl_type);
680
681/**
682 * @}
683 */
684
685/**
686 * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
687 *
688 * This group of functions is applied to an @ref Ecore_Con_Server object. It
689 * doesn't mean that they should be used in the server application, but on the
690 * server object. In fact, most of them should be used in the client
691 * application, when retrieving information or sending data.
692 *
693 * Setting up a server is very simple: you just need to start it with
694 * ecore_con_server_add() and setup some callbacks to the events
695 * #ECORE_CON_EVENT_CLIENT_ADD, #ECORE_CON_EVENT_CLIENT_DEL and
696 * #ECORE_CON_EVENT_CLIENT_DATA, that will be called when a client is
697 * communicating with the server:
698 *
699 * @code
700 * if (!(svr = ecore_con_server_add(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)))
701 * exit(1);
702 *
703 * ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_ADD, _add_cb, NULL);
704 * ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DEL, _del_cb, NULL);
705 * ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DATA, _data_cb, NULL);
706 *
707 * ecore_main_loop_begin();
708 * @endcode
709 *
710 * The function ecore_con_server_connect() can be used to write a client that
711 * connects to a server. The resulting code will be very similar to the server
712 * code:
713 *
714 * @code
715 * if (!(svr = ecore_con_server_connect(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)))
716 * exit(1);
717 *
718 * ecore_event_handler_add(ECORE_CON_EVENT_SERVER_ADD, _add_cb, NULL);
719 * ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DEL, _del_cb, NULL);
720 * ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DATA, _data_cb, NULL);
721 *
722 * ecore_main_loop_begin();
723 * @endcode
724 *
725 * After these two pieces of code are executed, respectively, in the server and
726 * client code, the server will be up and running and the client will try to
727 * connect to it. The connection, with its subsequent messages being sent from
728 * server to client and client to server, can be represented in the following
729 * sequence diagram:
730 *
731 * @htmlonly
732 * <img src="ecore_con-client-server.png" style="max-width: 400px"/>
733 * <a href="ecore_con-client-server.png">Full size</a>
734 * @endhtmlonly
735 *
736 * @image rtf ecore_con-client-server.png
737 * @image latex ecore_con-client-server.eps width=\textwidth
738 *
739 * Please notice the important difference between these two codes: the first is
740 * used for writing a @b server, while the second should be used for writing a
741 * @b client.
742 *
743 * A reference for the @c client functions can be found at @ref
744 * Ecore_Con_Client_Group.
745 *
746 * Examples of usage for this API can be found here:
747 * @li @ref ecore_con_server_simple_example_c
748 * @li @ref ecore_con_client_simple_example_c
749 *
750 * @{
751 */
752
753/**
754 * Creates a server to listen for connections.
755 *
756 * @param type The connection type.
757 * @param name Name to associate with the socket. It is used when
758 * generating the socket name of a Unix socket, or for
759 * determining what host to listen on for TCP sockets.
760 * @c NULL will not be accepted.
761 * @param port Number to identify socket. When a Unix socket is used,
762 * it becomes part of the socket name. When a TCP socket
763 * is used, it is used as the TCP port.
764 * @param data Data to associate with the created Ecore_Con_Server
765 * object.
766 * @return A new Ecore_Con_Server.
767 *
768 * The socket on which the server listens depends on the connection
769 * type:
770 * @li If @a type is @c ECORE_CON_LOCAL_USER, the server will listen on
771 * the Unix socket "~/.ecore/[name]/[port]".
772 * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen
773 * on Unix socket "/tmp/.ecore_service|[name]|[port]".
774 * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server will listen
775 * on TCP port @c port.
776 *
777 * More information about the @p type can be found at @ref _Ecore_Con_Type.
778 *
779 * The @p data parameter can be fetched later using ecore_con_server_data_get()
780 * or changed with ecore_con_server_data_set().
781 */
782EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
783 const char *name, int port,
784 const void *data);
785
786/**
787 * Creates a connection to the specified server and returns an associated object.
788 *
789 * @param type The connection type.
790 * @param name Name used when determining what socket to connect to.
791 * It is used to generate the socket name when the socket
792 * is a Unix socket. It is used as the hostname when
793 * connecting with a TCP socket.
794 * @param port Number to identify the socket to connect to. Used when
795 * generating the socket name for a Unix socket, or as the
796 * TCP port when connecting to a TCP socket.
797 * @param data Data to associate with the created Ecore_Con_Server
798 * object.
799 * @return A new Ecore_Con_Server.
800 *
801 * The socket to which the connection is made depends on the connection type:
802 * @li If @a type is @c ECORE_CON_LOCAL_USER, the function will
803 * connect to the server at the Unix socket
804 * "~/.ecore/[name]/[port]".
805 * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function will
806 * connect to the server at the Unix socket
807 * "/tmp/.ecore_service|[name]|[port]".
808 * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function will
809 * connect to the server at the TCP port "[name]:[port]".
810 *
811 * More information about the @p type can be found at @ref _Ecore_Con_Type.
812 *
813 * This function won't block. It will either succeed, or fail due to invalid
814 * parameters, failed memory allocation, etc., returning @c NULL on that case.
815 *
816 * However, even if this call returns a valid @ref Ecore_Con_Server, the
817 * connection will only be successfully completed if an event of type
818 * #ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
819 * #ECORE_CON_EVENT_SERVER_DEL will be received.
820 *
821 * The @p data parameter can be fetched later using ecore_con_server_data_get()
822 * or changed with ecore_con_server_data_set().
823 */
824EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
825 const char *name, int port,
826 const void *data);
827/**
828 * Closes the connection and frees the given server.
829 *
830 * @param svr The given server.
831 * @return Data associated with the server when it was created.
832 *
833 * All the clients connected to this server will be disconnected.
834 *
835 * @see ecore_con_server_add, ecore_con_server_connect
836 */
837EAPI void * ecore_con_server_del(Ecore_Con_Server *svr);
838
839/**
840 * Retrieves the data associated with the given server.
841 *
842 * @param svr The given server.
843 * @return The associated data.
844 *
845 * @see ecore_con_server_data_set()
846 */
847EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
848/**
849 * Sets the data associated with the given server.
850 *
851 * @param svr The given server.
852 * @param data The data to associate with @p svr
853 * @return The previously associated data, if any.
854 *
855 * @see ecore_con_server_data_get()
856 */
857EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr,
858 void *data);
859/**
860 * Retrieves whether the given server is currently connected.
861 *
862 * @param svr The given server.
863 * @return #EINA_TRUE if the server is connected. #EINA_FALSE otherwise.
864 */
865EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr);
866/**
867 * Retrieves the current list of clients.
868 *
869 * @param svr The given server.
870 * @return The list of clients on this server.
871 *
872 * Each node in the returned list points to an @ref Ecore_Con_Client. This list
873 * cannot be modified or freed. It can also change if new clients are connected
874 * or disconnected, and will become invalid when the server is deleted/freed.
875 */
876EAPI const Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr);
877
878/**
879 * Retrieves the name of server.
880 *
881 * @param svr The given server.
882 * @return The name of the server.
883 *
884 * The name returned is the name used to connect on this server.
885 */
886EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr);
887
888/**
889 * Retrieves the server port in use.
890 *
891 * @param svr The given server.
892 * @return The server port in use.
893 *
894 * The port where the server is listening for connections.
895 */
896EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr);
897/**
898 * @brief Check how long a server has been connected
899 *
900 * @param svr The server to check
901 * @return The total time, in seconds, that the server has been
902 * connected/running
903 *
904 * This function is used to find out the time that has been elapsed since
905 * ecore_con_server_add() succeeded.
906 */
907EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
908/**
909 * Sends the given data to the given server.
910 *
911 * @param svr The given server.
912 * @param data The given data.
913 * @param size Length of the data, in bytes, to send.
914 * @return The number of bytes sent. @c 0 will be returned if there is an
915 * error.
916 *
917 * This function will send the given data to the server as soon as the program
918 * is back to the main loop. Thus, this function returns immediately
919 * (non-blocking). If the data needs to be sent @b now, call
920 * ecore_con_server_flush() after this one.
921 *
922 * @see ecore_con_client_send()
923 * @see ecore_con_server_flush()
924 */
925EAPI int ecore_con_server_send(Ecore_Con_Server *svr,
926 const void *data,
927 int size);
928/**
929 * Sets a limit on the number of clients that can be handled concurrently
930 * by the given server, and a policy on what to do if excess clients try to
931 * connect.
932 *
933 * @param svr The given server.
934 * @param client_limit The maximum number of clients to handle
935 * concurrently. -1 means unlimited (default). 0
936 * effectively disables the server.
937 * @param reject_excess_clients Set to 1 to automatically disconnect
938 * excess clients as soon as they connect if you are
939 * already handling client_limit clients. Set to 0
940 * (default) to just hold off on the "accept()"
941 * system call until the number of active clients
942 * drops. This causes the kernel to queue up to 4096
943 * connections (or your kernel's limit, whichever is
944 * lower).
945 *
946 * Beware that if you set this once ecore is already running, you may
947 * already have pending CLIENT_ADD events in your event queue. Those
948 * clients have already connected and will not be affected by this call.
949 * Only clients subsequently trying to connect will be affected.
950 */
951EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
952 int client_limit,
953 char reject_excess_clients);
954/**
955 * Gets the IP address of a server that has been connected to.
956 *
957 * @param svr The given server.
958 * @return A pointer to an internal string that contains the IP address of
959 * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
960 * This string should not be modified or trusted to stay valid after
961 * deletion for the @p svr object. If no IP is known NULL is returned.
962 */
963EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr);
964/**
965 * Flushes all pending data to the given server.
966 *
967 * @param svr The given server.
968 *
969 * This function will block until all data is sent to the server.
970 *
971 * @see ecore_con_server_send()
972 * @see ecore_con_client_flush()
973 */
974EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
975/**
976 * Set the default time after which an inactive client will be disconnected
977 *
978 * @param svr The server object
979 * @param timeout The timeout, in seconds, to disconnect after
980 *
981 * This function is used by the server to set the default idle timeout on
982 * clients. If the any of the clients becomes idle for a time higher than this
983 * value, it will be disconnected. A value of < 1 disables the idle timeout.
984 *
985 * This timeout is not affected by the one set by
986 * ecore_con_client_timeout_set(). A client will be disconnected whenever the
987 * client or the server timeout is reached. That means, the lower timeout value
988 * will be used for that client if ecore_con_client_timeout_set() is used on it.
989 *
990 * @see ecore_con_server_timeout_get()
991 * @see ecore_con_client_timeout_set()
992 */
993EAPI void ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout);
994/**
995 * Get the default time after which an inactive client will be disconnected
996 *
997 * @param svr The server object
998 * @return The timeout, in seconds, to disconnect after
999 *
1000 * This function is used to get the idle timeout for clients. A value of < 1
1001 * means the idle timeout is disabled.
1002 *
1003 * @see ecore_con_server_timeout_set()
1004 * @see ecore_con_client_timeout_get()
1005 */
1006EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr);
1007
1008/**
1009 * Get the fd that the server is connected to
1010 *
1011 * @param svr The server object
1012 * @return The fd, or -1 on failure
1013 *
1014 * This function returns the fd which is used by the underlying server connection.
1015 * It should not be tampered with unless you REALLY know what you are doing.
1016 * @note This function is only valid for servers created with ecore_con_server_connect()
1017 * @warning Seriously. Don't use this unless you know what you are doing.
1018 * @since 1.1
1019 */
1020EAPI int ecore_con_server_fd_get(Ecore_Con_Server *svr);
1021
1022/**
1023 * Get the fd that the client is connected to
1024 *
1025 * @param cl The client object
1026 * @return The fd, or -1 on failure
1027 *
1028 * This function returns the fd which is used by the underlying client connection.
1029 * It should not be tampered with unless you REALLY know what you are doing.
1030 * @since 1.1
1031 */
1032EAPI int ecore_con_client_fd_get(Ecore_Con_Client *cl);
1033/**
1034 * @}
1035 */
1036
1037/**
1038 * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
1039 *
1040 * Functions to communicate with and/or set options on a client.
1041 *
1042 * This set of functions, as explained in @ref Ecore_Con_Server_Group, is used
1043 * to send data to a client, or to set options and get information about this
1044 * client. Most of them should be used on the server, applied on the client
1045 * object.
1046 *
1047 * If you need to implement a client, the way to connect to a server is
1048 * described in @ref Ecore_Con_Server_Group.
1049 *
1050 * An example of usage of these functions can be found at:
1051 * @li @ref ecore_con_client_simple_example_c
1052 *
1053 * @{
1054 */
1055
1056/**
1057 * Sends the given data to the given client.
1058 *
1059 * @param cl The given client.
1060 * @param data The given data.
1061 * @param size Length of the data, in bytes, to send.
1062 * @return The number of bytes sent. @c 0 will be returned if there is an
1063 * error.
1064 *
1065 * This function will send the given data to the client as soon as the program
1066 * is back to the main loop. Thus, this function returns immediately
1067 * (non-blocking). If the data needs to be sent @b now, call
1068 * ecore_con_client_flush() after this one.
1069 *
1070 * @see ecore_con_server_send()
1071 * @see ecore_con_client_flush()
1072 */
1073EAPI int ecore_con_client_send(Ecore_Con_Client *cl,
1074 const void *data,
1075 int size);
1076/**
1077 * Retrieves the server representing the socket the client has
1078 * connected to.
1079 *
1080 * @param cl The given client.
1081 * @return The server that the client connected to.
1082 */
1083EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
1084/**
1085 * Closes the connection and frees memory allocated to the given client.
1086 *
1087 * @param cl The given client.
1088 * @return Data associated with the client.
1089 */
1090EAPI void * ecore_con_client_del(Ecore_Con_Client *cl);
1091/**
1092 * Sets the data associated with the given client to @p data.
1093 *
1094 * @param cl The given client.
1095 * @param data What to set the data to.
1096 */
1097EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl,
1098 const void *data);
1099/**
1100 * Retrieves the data associated with the given client.
1101 *
1102 * @param cl The given client.
1103 * @return The data associated with @p cl.
1104 */
1105EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl);
1106
1107/**
1108 * Gets the IP address of a client that has connected.
1109 *
1110 * @param cl The given client.
1111 * @return A pointer to an internal string that contains the IP address of
1112 * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation.
1113 *
1114 * The returned string should not be modified, freed or trusted to stay valid
1115 * after deletion for the @p cl object. If no IP is known NULL is returned.
1116 */
1117EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl);
1118/**
1119 * Flushes all pending data to the given client.
1120 *
1121 * @param cl The given client.
1122 *
1123 * This function will block until all data is sent to the server.
1124 *
1125 * @see ecore_con_client_send()
1126 * @see ecore_con_server_flush()
1127 */
1128EAPI void ecore_con_client_flush(Ecore_Con_Client *cl);
1129/**
1130 * @brief Check how long a client has been connected
1131 *
1132 * @param cl The client to check
1133 * @return The total time, in seconds, that the client has been connected to
1134 * the server
1135 *
1136 * This function is used to find out how long a client has been connected for.
1137 */
1138EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl);
1139/**
1140 * Get the default time after which the client will be disconnected when
1141 * inactive
1142 *
1143 * @param cl The client object
1144 * @return The timeout, in seconds, to disconnect after
1145 *
1146 * This function is used to get the idle timeout for a client. A value of < 1
1147 * means the idle timeout is disabled.
1148 *
1149 * @see ecore_con_client_timeout_set()
1150 */
1151EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl);
1152/**
1153 * Set the time after which the client will be disconnected when inactive
1154 *
1155 * @param cl The client object
1156 * @param timeout The timeout, in seconds, to disconnect after
1157 *
1158 * This function is used by the server to set the idle timeout on a specific
1159 * client. If the client becomes idle for a time higher than this value, it will
1160 * be disconnected. A value of < 1 disables the idle timeout.
1161 *
1162 * This timeout is not affected by the one set by
1163 * ecore_con_server_timeout_set(). A client will be disconnected whenever the
1164 * client or the server timeout is reached. That means, the lower timeout value
1165 * will be used for that client if ecore_con_server_timeout_set() is used on the
1166 * server.
1167 *
1168 * @see ecore_con_client_timeout_get()
1169 * @see ecore_con_server_timeout_set()
1170 */
1171EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout);
1172/**
1173 * Returns whether the client is still connected
1174 *
1175 * @param cl The given client.
1176 * @return #EINA_TRUE if connected, else EINA_FALSE
1177 */
1178EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl);
1179/**
1180 * @brief Return the port that the client has connected to
1181 *
1182 * @param cl The client
1183 * @return The port that @p cl has connected to, or -1 on error
1184 * Use this function to return the port on which a given client has connected.
1185 */
1186EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl);
1187
1188/**
1189 * @}
1190 */
1191
1192/**
1193 * @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions
1194 *
1195 * Utility functions that set up, use and shut down the Ecore URL
1196 * Connection library.
1197 *
1198 * These functions are a shortcut to make it easy to perform http requests
1199 * (POST, GET, etc).
1200 *
1201 * Brief usage:
1202 * 1. Create an Ecore_Con_Url object with ecore_con_url_new(url);
1203 * 2. Register to receive the #ECORE_CON_EVENT_URL_COMPLETE event
1204 * (and optionally the #ECORE_CON_EVENT_URL_DATA and
1205 * #ECORE_CON_EVENT_URL_PROGRESS event to receive
1206 * the response, e.g. for HTTP/FTP downloads)
1207 * 3. Perform the operation with ecore_con_url_get(...);
1208 *
1209 * Note that it is good to reuse @ref Ecore_Con_Url objects wherever possible,
1210 * but bear in mind that each one can only perform one operation at a time. You
1211 * need to wait for the #ECORE_CON_EVENT_URL_COMPLETE event before re-using or
1212 * destroying the object.
1213 *
1214 * If it's necessary to change the @ref Ecore_Con_Url object url, use
1215 * ecore_con_url_url_set().
1216 *
1217 * Simple Usage 1 (HTTP GET):
1218 * @code
1219 * ecore_con_url_url_set(url_con, "http://www.google.com");
1220 * ecore_con_url_get(url_con);
1221 * @endcode
1222 *
1223 * Simple usage 2 (HTTP POST):
1224 * @code
1225 * ecore_con_url_url_set(url_con, "http://www.example.com/post_handler.cgi");
1226 * ecore_con_url_post(url_con, data, data_length, "multipart/form-data");
1227 * @endcode
1228 *
1229 * Simple Usage 3 (FTP download):
1230 * @code
1231 * fd = creat(filename, 0644)
1232 * ecore_con_url_url_set(url_con, "ftp://ftp.example.com/pub/myfile");
1233 * ecore_con_url_fd_set(url_con, fd);
1234 * ecore_con_url_get(url_con);
1235 * @endcode
1236 *
1237 * Simple Usage 4 (FTP upload as ftp://ftp.example.com/file):
1238 * @code
1239 * ecore_con_url_url_set(url_con, "ftp://ftp.example.com");
1240 * ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass", NULL);
1241 * @endcode
1242 *
1243 * Simple Usage 5 (FTP upload as ftp://ftp.example.com/dir/file):
1244 * @code
1245 * ecore_con_url_url_set(url_con, "ftp://ftp.example.com");
1246 * ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass","dir");
1247 * @endcode
1248 *
1249 * These are complete examples for the API:
1250 * @li @ref ecore_con_url_download_example.c "Downloading a file"
1251 * @li @ref ecore_con_url_headers_example.c "Setting many options for the
1252 * connection"
1253 *
1254 * @{
1255 */
1256
1257/**
1258 * @typedef Ecore_Con_Url_Time
1259 * @enum _Ecore_Con_Url_Time
1260 * The type of condition to use when making an HTTP request dependent on time,
1261 * so that headers such as "If-Modified-Since" are used.
1262 */
1263typedef enum _Ecore_Con_Url_Time
1264{
1265 /**
1266 * Do not place time restrictions on the HTTP requests.
1267 */
1268 ECORE_CON_URL_TIME_NONE = 0,
1269 /**
1270 * Add the "If-Modified-Since" HTTP header, so that the request is performed
1271 * by the server only if the target has been modified since the time value
1272 * passed to it in the request.
1273 */
1274 ECORE_CON_URL_TIME_IFMODSINCE,
1275 /**
1276 * Add the "If-Unmodified-Since" HTTP header, so that the request is
1277 * performed by the server only if the target has NOT been modified since
1278 * the time value passed to it in the request.
1279 */
1280 ECORE_CON_URL_TIME_IFUNMODSINCE
1281} Ecore_Con_Url_Time;
1282
1283/**
1284 * Initialises the Ecore_Con_Url library.
1285 * @return Number of times the library has been initialised without being
1286 * shut down.
1287 *
1288 * @note This function doesn't call ecore_con_init(). You still need to call it
1289 * explicitly before calling this one.
1290 */
1291EAPI int ecore_con_url_init(void);
1292
1293/**
1294 * Shuts down the Ecore_Con_Url library.
1295 * @return Number of calls that still uses Ecore_Con_Url
1296 *
1297 * @note This function doesn't call ecore_con_shutdown(). You still need to call
1298 * it explicitly after calling this one.
1299 */
1300EAPI int ecore_con_url_shutdown(void);
1301
1302/**
1303 * Enable or disable HTTP 1.1 pipelining.
1304 * @param enable EINA_TRUE will turn it on, EINA_FALSE will disable it.
1305 *
1306 * Pipelining allows to send one request after another one, without having to
1307 * wait for the reply of the first request. The respective replies are received
1308 * in the order that the requests were sent.
1309 *
1310 * Enabling this feature will be valid for all requests done using @c
1311 * ecore_con_url.
1312 *
1313 * See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.
1314 *
1315 * @see ecore_con_url_pipeline_get()
1316 */
1317EAPI void ecore_con_url_pipeline_set(Eina_Bool enable);
1318/**
1319 * Is HTTP 1.1 pipelining enable ?
1320 * @return EINA_TRUE if it is enable.
1321 *
1322 * @see ecore_con_url_pipeline_set()
1323 */
1324EAPI Eina_Bool ecore_con_url_pipeline_get(void);
1325
1326/**
1327 * Creates and initializes a new Ecore_Con_Url connection object.
1328 *
1329 * @param url URL that will receive requests. Can be changed using
1330 * ecore_con_url_url_set.
1331 *
1332 * @return NULL on error, a new Ecore_Con_Url on success.
1333 *
1334 * Creates and initializes a new Ecore_Con_Url connection object that can be
1335 * used for sending requests.
1336 *
1337 * @see ecore_con_url_custom_new()
1338 * @see ecore_con_url_url_set()
1339 */
1340EAPI Ecore_Con_Url * ecore_con_url_new(const char *url);
1341/**
1342 * Creates a custom connection object.
1343 *
1344 * @param url URL that will receive requests
1345 * @param custom_request Custom request (e.g. GET, POST, HEAD, PUT, etc)
1346 *
1347 * @return NULL on error, a new Ecore_Con_Url on success.
1348 *
1349 * Creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD,
1350 * SUBSCRIBE and other obscure HTTP requests). This object should be used like
1351 * one created with ecore_con_url_new().
1352 *
1353 * @see ecore_con_url_new()
1354 * @see ecore_con_url_url_set()
1355 */
1356EAPI Ecore_Con_Url * ecore_con_url_custom_new(const char *url,
1357 const char *custom_request);
1358/**
1359 * Destroys a Ecore_Con_Url connection object.
1360 *
1361 * @param url_con Connection object to free.
1362 *
1363 * @see ecore_con_url_new()
1364 */
1365EAPI void ecore_con_url_free(Ecore_Con_Url *url_con);
1366/**
1367 * Sets the URL to send the request to.
1368 *
1369 * @param url_con Connection object through which the request will be sent.
1370 * @param url URL that will receive the request
1371 *
1372 * @return EINA_TRUE on success, EINA_FALSE on error.
1373 *
1374 */
1375EAPI Eina_Bool ecore_con_url_url_set(Ecore_Con_Url *url_con,
1376 const char *url);
1377/**
1378 * Gets the URL to send the request to.
1379 *
1380 * @param url_con Connection object through which the request will be sent.
1381 * @return URL that will receive the request, NULL on failure. URL is stringshared.
1382 * @since 1.1
1383 */
1384EAPI const char *ecore_con_url_url_get(Ecore_Con_Url *url_con);
1385/**
1386 * Associates data with a connection object.
1387 *
1388 * @param url_con Connection object to associate data.
1389 * @param data Data to be set.
1390 *
1391 * Associates data with a connection object, which can be retrieved later with
1392 * ecore_con_url_data_get()).
1393 *
1394 * @see ecore_con_url_data_get()
1395 */
1396EAPI void ecore_con_url_data_set(Ecore_Con_Url *url_con,
1397 void *data);
1398/**
1399 * Retrieves data associated with a Ecore_Con_Url connection object.
1400 *
1401 * @param url_con Connection object to retrieve data from.
1402 *
1403 * @return Data associated with the given object.
1404 *
1405 * Retrieves data associated with a Ecore_Con_Url connection object (previously
1406 * set with ecore_con_url_data_set()).
1407 *
1408 * @see ecore_con_url_data_set()
1409 */
1410EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con);
1411/**
1412 * Adds an additional header to the request connection object.
1413 *
1414 * @param url_con Connection object
1415 * @param key Header key
1416 * @param value Header value
1417 *
1418 * Adds an additional header (User-Agent, Content-Type, etc.) to the request
1419 * connection object. This addition will be valid for only one
1420 * ecore_con_url_get() or ecore_con_url_post() call.
1421 *
1422 * Some functions like ecore_con_url_time() also add headers to the request.
1423 *
1424 * @see ecore_con_url_get()
1425 * @see ecore_con_url_post()
1426 * @see ecore_con_url_additional_headers_clear()
1427 */
1428EAPI void ecore_con_url_additional_header_add(Ecore_Con_Url *url_con,
1429 const char *key,
1430 const char *value);
1431/**
1432 * Cleans additional headers.
1433 *
1434 * @param url_con Connection object to clean additional headers.
1435 *
1436 * Cleans additional headers associated with a connection object (previously
1437 * added with ecore_con_url_additional_header_add()).
1438 *
1439 * @see ecore_con_url_additional_header_add()
1440 * @see ecore_con_url_get()
1441 * @see ecore_con_url_post()
1442 */
1443EAPI void ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con);
1444/**
1445 * Retrieves headers from last request sent.
1446 *
1447 * @param url_con Connection object to retrieve response headers from.
1448 *
1449 * Retrieves a list containing the response headers. This function should be
1450 * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be
1451 * ready at that time).
1452 *
1453 * @return List of response headers. This list must not be modified by the user.
1454 */
1455EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con);
1456/**
1457 * Setup a file for receiving response data.
1458 *
1459 * @param url_con Connection object to set file
1460 * @param fd File descriptor associated with the file. A negative value will
1461 * unset any previously set fd.
1462 *
1463 * Sets up a file to have response data written into. Note that
1464 * ECORE_CON_EVENT_URL_DATA events will not be emitted if a file has been set to
1465 * receive the response data.
1466 *
1467 * This call can be used to easily setup a file where the downloaded data will
1468 * be saved.
1469 */
1470EAPI void ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
1471/**
1472 * Retrieves the number of bytes received.
1473 *
1474 * Retrieves the number of bytes received on the last request of the given
1475 * connection object.
1476 *
1477 * @param url_con Connection object which the request was sent on.
1478 *
1479 * @return Number of bytes received on request.
1480 *
1481 * @see ecore_con_url_get()
1482 * @see ecore_con_url_post()
1483 */
1484EAPI int ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
1485/**
1486 * Sets url_con to use http auth, with given username and password, "safely" or not.
1487 *
1488 * @param url_con Connection object to perform a request on, previously created
1489 * with ecore_con_url_new() or ecore_con_url_custom_new().
1490 * @param username Username to use in authentication
1491 * @param password Password to use in authentication
1492 * @param safe Whether to use "safer" methods (eg, NOT http basic auth)
1493 *
1494 * @return #EINA_TRUE on success, #EINA_FALSE on error.
1495 *
1496 * ATTENTION: requires libcurl >= 7.19.1 to work, otherwise will always return 0.
1497 */
1498EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
1499 const char *username,
1500 const char *password,
1501 Eina_Bool safe);
1502/**
1503 * Sends a request.
1504 *
1505 * @param url_con Connection object to perform a request on, previously created
1506 * with ecore_con_url_new() or ecore_con_url_custom_new().
1507 * @param data Payload (data sent on the request)
1508 * @param length Payload length. If @c -1, rely on automatic length
1509 * calculation via @c strlen() on @p data.
1510 * @param content_type Content type of the payload (e.g. text/xml)
1511 *
1512 * @return #EINA_TRUE on success, #EINA_FALSE on error.
1513 *
1514 * @see ecore_con_url_custom_new()
1515 * @see ecore_con_url_additional_headers_clear()
1516 * @see ecore_con_url_additional_header_add()
1517 * @see ecore_con_url_data_set()
1518 * @see ecore_con_url_data_get()
1519 * @see ecore_con_url_response_headers_get()
1520 * @see ecore_con_url_time()
1521 * @see ecore_con_url_get()
1522 * @see ecore_con_url_post()
1523 *
1524 * @deprecated Use ecore_con_url_post() instead of this.
1525 */
1526EINA_DEPRECATED EAPI Eina_Bool ecore_con_url_send(Ecore_Con_Url *url_con,
1527 const void *data, long length,
1528 const char *content_type);
1529/**
1530 * Sends a get request.
1531 *
1532 * @param url_con Connection object to perform a request on, previously created
1533 *
1534 * @return #EINA_TRUE on success, #EINA_FALSE on error.
1535 *
1536 * The request is performed immediately, but you need to setup event handlers
1537 * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
1538 * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
1539 *
1540 * @see ecore_con_url_custom_new()
1541 * @see ecore_con_url_additional_headers_clear()
1542 * @see ecore_con_url_additional_header_add()
1543 * @see ecore_con_url_data_set()
1544 * @see ecore_con_url_data_get()
1545 * @see ecore_con_url_response_headers_get()
1546 * @see ecore_con_url_time()
1547 * @see ecore_con_url_post()
1548 */
1549EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con);
1550/**
1551 * Sends a post request.
1552 *
1553 * @param url_con Connection object to perform a request on, previously created
1554 * with ecore_con_url_new() or ecore_con_url_custom_new().
1555 * @param data Payload (data sent on the request). Can be @c NULL.
1556 * @param length Payload length. If @c -1, rely on automatic length
1557 * calculation via @c strlen() on @p data.
1558 * @param content_type Content type of the payload (e.g. text/xml). Can be @c
1559 * NULL.
1560 *
1561 * @return #EINA_TRUE on success, #EINA_FALSE on error.
1562 *
1563 * The request starts immediately, but you need to setup event handlers
1564 * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
1565 * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
1566 *
1567 * This call won't block your main loop.
1568 *
1569 * @see ecore_con_url_custom_new()
1570 * @see ecore_con_url_additional_headers_clear()
1571 * @see ecore_con_url_additional_header_add()
1572 * @see ecore_con_url_data_set()
1573 * @see ecore_con_url_data_get()
1574 * @see ecore_con_url_response_headers_get()
1575 * @see ecore_con_url_time()
1576 * @see ecore_con_url_get()
1577 */
1578EAPI Eina_Bool ecore_con_url_post(Ecore_Con_Url *url_con,
1579 const void *data, long length,
1580 const char *content_type);
1581/**
1582 * Sets whether HTTP requests should be conditional, dependent on
1583 * modification time.
1584 *
1585 * @param url_con Ecore_Con_Url to act upon.
1586 * @param condition Condition to use for HTTP requests.
1587 * @param timestamp Time since 1 Jan 1970 to use in the condition.
1588 *
1589 * This function may set the header "If-Modified-Since" or
1590 * "If-Unmodified-Since", depending on the value of @p time_condition, with the
1591 * value @p timestamp.
1592 *
1593 * @sa ecore_con_url_get()
1594 * @sa ecore_con_url_post()
1595 */
1596EAPI void ecore_con_url_time(Ecore_Con_Url *url_con,
1597 Ecore_Con_Url_Time time_condition,
1598 double timestamp);
1599
1600/**
1601 * @brief Uploads a file to an ftp site.
1602 * @param url_con The Ecore_Con_Url object to send with
1603 * @param filename The path to the file to send
1604 * @param user The username to log in with
1605 * @param pass The password to log in with
1606 * @param upload_dir The directory to which the file should be uploaded
1607 * @return #EINA_TRUE on success, else #EINA_FALSE.
1608 * Upload @p filename to an ftp server set in @p url_con using @p user
1609 * and @p pass to directory @p upload_dir
1610 */
1611EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
1612 const char *filename,
1613 const char *user,
1614 const char *pass,
1615 const char *upload_dir);
1616/**
1617 * Toggle libcurl's verbose output.
1618 *
1619 * @param url_con Ecore_Con_Url instance which will be acted upon.
1620 * @param verbose Whether or not to enable libcurl's verbose output.
1621 *
1622 * If @p verbose is @c EINA_TRUE, libcurl will output a lot of verbose
1623 * information about its operations, which is useful for
1624 * debugging. The verbose information will be sent to stderr.
1625 */
1626EAPI void ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
1627 Eina_Bool verbose);
1628/**
1629 * Enable or disable EPSV extension
1630 * @return FIXME: To be more documented.
1631 */
1632EAPI void ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
1633 Eina_Bool use_epsv);
1634
1635/**
1636 * Enables the cookie engine for subsequent HTTP requests.
1637 *
1638 * @param url_con Ecore_Con_Url instance which will be acted upon.
1639 *
1640 * After this function is called, cookies set by the server in HTTP responses
1641 * will be parsed and stored, as well as sent back to the server in new HTTP
1642 * requests.
1643 *
1644 * @note Even though this function is called @c ecore_con_url_cookies_init(),
1645 * there is no symmetrical shutdown operation.
1646 */
1647EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con);
1648/**
1649 * Controls whether session cookies from previous sessions shall be loaded.
1650 *
1651 * @param url_con Ecore_Con_Url instance which will be acted upon.
1652 * @param ignore If @c EINA_TRUE, ignore session cookies when loading cookies
1653 * from files. If @c EINA_FALSE, all cookies will be loaded.
1654 *
1655 * Session cookies are cookies with no expire date set, which usually means
1656 * they are removed after the current session is closed.
1657 *
1658 * By default, when Ecore_Con_Url loads cookies from a file, all cookies are
1659 * loaded, including session cookies, which, most of the time, were supposed
1660 * to be loaded and valid only for that session.
1661 *
1662 * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from
1663 * the files passed to @c ecore_con_url_cookies_file_add(), session cookies
1664 * will not be loaded.
1665 *
1666 * @see ecore_con_url_cookies_file_add()
1667 */
1668EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con,
1669 Eina_Bool ignore);
1670/**
1671 * Clears currently loaded cookies.
1672 * @param url_con Ecore_Con_Url instance which will be acted upon.
1673 *
1674 * The cleared cookies are removed and will not be sent in subsequent HTTP
1675 * requests, nor will they be written to the cookiejar file set via
1676 * @c ecore_con_url_cookies_jar_file_set().
1677 *
1678 * @note This function will initialize the cookie engine if it has not been
1679 * initialized yet.
1680 * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
1681 * immediately, just when the request is started. Thus, if you ask to
1682 * clear the cookies, but has a file already set by that function, the
1683 * cookies will then be loaded and you will have old cookies set. In order
1684 * to don't have any old cookie set, you need to don't call
1685 * ecore_con_url_cookies_file_add() ever on the @p url_con handler, and
1686 * call this function to clear any cookie set by a previous request on
1687 * this handler.
1688 *
1689 * @see ecore_con_url_cookies_session_clear()
1690 * @see ecore_con_url_cookies_ignore_old_session_set()
1691 */
1692EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con);
1693/**
1694 * Clears currently loaded session cookies.
1695 *
1696 * @param url_con Ecore_Con_Url instance which will be acted upon.
1697 *
1698 * Session cookies are cookies with no expire date set, which usually means
1699 * they are removed after the current session is closed.
1700 *
1701 * The cleared cookies are removed and will not be sent in subsequent HTTP
1702 * requests, nor will they be written to the cookiejar file set via
1703 * @c ecore_con_url_cookies_jar_file_set().
1704 *
1705 * @note This function will initialize the cookie engine if it has not been
1706 * initialized yet.
1707 * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
1708 * immediately, just when the request is started. Thus, if you ask to
1709 * clear the session cookies, but has a file already set by that function,
1710 * the session cookies will then be loaded and you will have old cookies
1711 * set. In order to don't have any old session cookie set, you need to
1712 * don't call ecore_con_url_cookies_file_add() ever on the @p url_con
1713 * handler, and call this function to clear any session cookie set by a
1714 * previous request on this handler. An easier way to don't use old
1715 * session cookies is by using the function
1716 * ecore_con_url_cookies_ignore_old_session_set().
1717 *
1718 * @see ecore_con_url_cookies_clear()
1719 * @see ecore_con_url_cookies_ignore_old_session_set()
1720 */
1721EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con);
1722/**
1723 * Adds a file to the list of files from which to load cookies.
1724 *
1725 * @param url_con Ecore_Con_Url instance which will be acted upon.
1726 * @param file_name Name of the file that will be added to the list.
1727 *
1728 * Files must contain cookies defined according to two possible formats:
1729 *
1730 * @li HTTP-style header ("Set-Cookie: ...").
1731 * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a>
1732 *
1733 * Cookies will only be @b read from this file. If you want to save cookies to a
1734 * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this
1735 * function supports the both types of cookie file cited above, while
1736 * ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's
1737 * format.
1738 *
1739 * Please notice that the file will not be read immediately, but rather added
1740 * to a list of files that will be loaded and parsed at a later time.
1741 *
1742 * @note This function will initialize the cookie engine if it has not been
1743 * initialized yet.
1744 *
1745 * @see ecore_con_url_cookies_ignore_old_session_set()
1746 * @see ecore_con_url_cookies_jar_file_set()
1747 */
1748EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con,
1749 const char * const file_name);
1750/**
1751 * Sets the name of the file to which all current cookies will be written when
1752 * either cookies are flushed or Ecore_Con is shut down.
1753 *
1754 * @param url_con Ecore_Con_Url instance which will be acted upon.
1755 * @param cookiejar_file File to which the cookies will be written.
1756 *
1757 * @return @c EINA_TRUE is the file name has been set successfully,
1758 * @c EINA_FALSE otherwise.
1759 *
1760 * Cookies are written following Netscape/Mozilla's data format, also known as
1761 * cookie-jar.
1762 *
1763 * Cookies will only be @b saved to this file. If you need to read cookies from
1764 * a file, use ecore_con_url_cookies_file_add() instead.
1765 *
1766 * @note This function will initialize the cookie engine if it has not been
1767 * initialized yet.
1768 *
1769 * @see ecore_con_url_cookies_jar_write()
1770 */
1771EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con,
1772 const char * const cookiejar_file);
1773/**
1774 * Writes all current cookies to the cookie jar immediately.
1775 *
1776 * @param url_con Ecore_Con_Url instance which will be acted upon.
1777 *
1778 * A cookie-jar file must have been previously set by
1779 * @c ecore_con_url_jar_file_set, otherwise nothing will be done.
1780 *
1781 * @note This function will initialize the cookie engine if it has not been
1782 * initialized yet.
1783 *
1784 * @see ecore_con_url_cookies_jar_file_set()
1785 */
1786EAPI void ecore_con_url_cookies_jar_write(Ecore_Con_Url *url_con);
1787
1788EAPI void ecore_con_url_ssl_verify_peer_set(Ecore_Con_Url *url_con,
1789 Eina_Bool verify);
1790EAPI int ecore_con_url_ssl_ca_set(Ecore_Con_Url *url_con,
1791 const char *ca_path);
1792
1793/**
1794 * @}
1795 */
1796
1797#ifdef __cplusplus
1798}
1799#endif
1800
1801#endif
generated by cgit v1.1 at 2024-08-29 02:16:31 +0000