diff options
author | David Walter Seikel | 2012-01-04 18:41:13 +1000 |
---|---|---|
committer | David Walter Seikel | 2012-01-04 18:41:13 +1000 |
commit | dd7595a3475407a7fa96a97393bae8c5220e8762 (patch) | |
tree | e341e911d7eb911a51684a7412ef7f7c7605d28e /libraries/ecore/src/lib/ecore_con/Ecore_Con.h | |
parent | Add the skeleton. (diff) | |
download | SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.zip SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.gz SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.bz2 SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.xz |
Add the base Enlightenment Foundation Libraries - eina, eet, evas, ecore, embryo, and edje.
Note that embryo wont be used, but I'm not sure yet if you can build edje without it.
Diffstat (limited to 'libraries/ecore/src/lib/ecore_con/Ecore_Con.h')
-rw-r--r-- | libraries/ecore/src/lib/ecore_con/Ecore_Con.h | 1801 |
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 | ||
216 | extern "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 | */ | ||
227 | typedef 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 | */ | ||
234 | typedef 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 | */ | ||
241 | typedef 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 | */ | ||
253 | typedef 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 | */ | ||
260 | typedef 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 | */ | ||
266 | typedef 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 | */ | ||
273 | typedef 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 | */ | ||
279 | typedef 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 | */ | ||
286 | typedef 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 | */ | ||
292 | typedef 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 | */ | ||
299 | typedef 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 | */ | ||
305 | typedef 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 | */ | ||
311 | typedef 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 | */ | ||
318 | typedef 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 | */ | ||
325 | typedef 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 | */ | ||
332 | typedef 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 | */ | ||
339 | typedef 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 | */ | ||
346 | typedef 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 | */ | ||
352 | struct _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 | */ | ||
362 | struct _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 | */ | ||
371 | struct _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 | */ | ||
380 | struct _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 | */ | ||
390 | struct _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 | */ | ||
400 | struct _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 | */ | ||
409 | struct _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 | */ | ||
418 | struct _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 | */ | ||
428 | struct _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 | */ | ||
439 | struct _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 | */ | ||
450 | struct _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 | */ | ||
460 | struct _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 | */ | ||
471 | struct _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 | */ | ||
483 | struct _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 | */ | ||
494 | struct _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 */ | ||
510 | EAPI extern int ECORE_CON_EVENT_CLIENT_ADD; | ||
511 | /** A client has disconnected from the server */ | ||
512 | EAPI extern int ECORE_CON_EVENT_CLIENT_DEL; | ||
513 | /** A client experienced an error | ||
514 | * @since 1.1 | ||
515 | */ | ||
516 | EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR; | ||
517 | /** A client connection has been upgraded to SSL | ||
518 | * @since 1.1 | ||
519 | */ | ||
520 | EAPI extern int ECORE_CON_EVENT_CLIENT_UPGRADE; | ||
521 | /** A server was created */ | ||
522 | EAPI extern int ECORE_CON_EVENT_SERVER_ADD; | ||
523 | /** A server connection was lost */ | ||
524 | EAPI extern int ECORE_CON_EVENT_SERVER_DEL; | ||
525 | /** A server experienced an error | ||
526 | * @since 1.1 | ||
527 | */ | ||
528 | EAPI extern int ECORE_CON_EVENT_SERVER_ERROR; | ||
529 | /** A server connection has been upgraded to SSL | ||
530 | * @since 1.1 | ||
531 | */ | ||
532 | EAPI extern int ECORE_CON_EVENT_SERVER_UPGRADE; | ||
533 | /** A server connection has sent data to its client | ||
534 | * @since 1.1 | ||
535 | */ | ||
536 | EAPI extern int ECORE_CON_EVENT_CLIENT_WRITE; | ||
537 | /** A server connection object has sent data | ||
538 | * @since 1.1 | ||
539 | */ | ||
540 | EAPI extern int ECORE_CON_EVENT_SERVER_WRITE; | ||
541 | /** A client connected to the server has sent data */ | ||
542 | EAPI extern int ECORE_CON_EVENT_CLIENT_DATA; | ||
543 | /** A server connection object has data */ | ||
544 | EAPI extern int ECORE_CON_EVENT_SERVER_DATA; | ||
545 | /** A URL object has data */ | ||
546 | EAPI extern int ECORE_CON_EVENT_URL_DATA; | ||
547 | /** A URL object has completed its transfer to and from the server and can be reused */ | ||
548 | EAPI extern int ECORE_CON_EVENT_URL_COMPLETE; | ||
549 | /** A URL object has made progress in its transfer */ | ||
550 | EAPI 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 | */ | ||
575 | typedef 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 | */ | ||
592 | typedef 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 | */ | ||
629 | EAPI 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 | */ | ||
638 | EAPI 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 | */ | ||
658 | EAPI 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 | */ | ||
671 | EAPI int ecore_con_ssl_available_get(void); | ||
672 | EAPI Eina_Bool ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert); | ||
673 | EAPI Eina_Bool ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file); | ||
674 | EAPI Eina_Bool ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file); | ||
675 | EAPI Eina_Bool ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file); | ||
676 | EAPI void ecore_con_ssl_server_verify(Ecore_Con_Server *svr); | ||
677 | EAPI void ecore_con_ssl_server_verify_basic(Ecore_Con_Server *svr); | ||
678 | EAPI Eina_Bool ecore_con_ssl_server_upgrade(Ecore_Con_Server *svr, Ecore_Con_Type compl_type); | ||
679 | EAPI 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 | */ | ||
782 | EAPI 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 | */ | ||
824 | EAPI 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 | */ | ||
837 | EAPI 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 | */ | ||
847 | EAPI 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 | */ | ||
857 | EAPI 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 | */ | ||
865 | EAPI 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 | */ | ||
876 | EAPI 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 | */ | ||
886 | EAPI 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 | */ | ||
896 | EAPI 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 | */ | ||
907 | EAPI 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 | */ | ||
925 | EAPI 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 | */ | ||
951 | EAPI 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 | */ | ||
963 | EAPI 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 | */ | ||
974 | EAPI 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 | */ | ||
993 | EAPI 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 | */ | ||
1006 | EAPI 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 | */ | ||
1020 | EAPI 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 | */ | ||
1032 | EAPI 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 | */ | ||
1073 | EAPI 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 | */ | ||
1083 | EAPI 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 | */ | ||
1090 | EAPI 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 | */ | ||
1097 | EAPI 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 | */ | ||
1105 | EAPI 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 | */ | ||
1117 | EAPI 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 | */ | ||
1128 | EAPI 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 | */ | ||
1138 | EAPI 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 | */ | ||
1151 | EAPI 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 | */ | ||
1171 | EAPI 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 | */ | ||
1178 | EAPI 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 | */ | ||
1186 | EAPI 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 | */ | ||
1263 | typedef 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 | */ | ||
1291 | EAPI 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 | */ | ||
1300 | EAPI 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 | */ | ||
1317 | EAPI 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 | */ | ||
1324 | EAPI 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 | */ | ||
1340 | EAPI 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 | */ | ||
1356 | EAPI 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 | */ | ||
1365 | EAPI 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 | */ | ||
1375 | EAPI 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 | */ | ||
1384 | EAPI 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 | */ | ||
1396 | EAPI 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 | */ | ||
1410 | EAPI 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 | */ | ||
1428 | EAPI 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 | */ | ||
1443 | EAPI 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 | */ | ||
1455 | EAPI 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 | */ | ||
1470 | EAPI 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 | */ | ||
1484 | EAPI 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 | */ | ||
1498 | EAPI 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 | */ | ||
1526 | EINA_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 | */ | ||
1549 | EAPI 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 | */ | ||
1578 | EAPI 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 | */ | ||
1596 | EAPI 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 | */ | ||
1611 | EAPI 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 | */ | ||
1626 | EAPI 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 | */ | ||
1632 | EAPI 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 | */ | ||
1647 | EAPI 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 | */ | ||
1668 | EAPI 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 | */ | ||
1692 | EAPI 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 | */ | ||
1721 | EAPI 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 | */ | ||
1748 | EAPI 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 | */ | ||
1771 | EAPI 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 | */ | ||
1786 | EAPI void ecore_con_url_cookies_jar_write(Ecore_Con_Url *url_con); | ||
1787 | |||
1788 | EAPI void ecore_con_url_ssl_verify_peer_set(Ecore_Con_Url *url_con, | ||
1789 | Eina_Bool verify); | ||
1790 | EAPI 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 | ||