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