19 # define EAPI __declspec(dllexport)
21 # define EAPI __declspec(dllimport)
26 # define EAPI __attribute__ ((visibility("default")))
36 * @defgroup Ecore_Con_Group Ecore_Con - Connection functions
38 * The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
39 * for communications between programs using reliable sockets. It saves
40 * the programmer from having to worry about file descriptors and waiting
41 * for incoming connections.
43 * There are two main objects in the @c Ecore_Con library: the @c
44 * Ecore_Con_Server and the @c Ecore_Con_Client.
46 * The @c Ecore_Con_Server represents a server that can be connected to.
47 * It is used regardless of whether the program is acting as a server or
50 * To create a listening server call @c ecore_con_server_add(), optionally using
51 * an ECORE_CON_USE_* encryption type OR'ed with the type for encryption.
53 * To connect to a server, call @c ecore_con_server_connect(). Data can
54 * then be sent to the server using the @c ecore_con_server_send().
56 * Functions are described in the following groupings:
57 * @li @ref Ecore_Con_Lib_Group
58 * @li @ref Ecore_Con_Server_Group
59 * @li @ref Ecore_Con_Client_Group
60 * @li @ref Ecore_Con_Url_Group
62 * Events are described in @ref Ecore_Con_Events_Group.
67 * @defgroup Ecore_Con_Events_Group Events
69 * @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
70 * @c Ecore_Con_Server, an event of this type is emitted, allowing the
71 * retrieval of the client's ip with @ref ecore_con_client_ip_get and
72 * associating data with the client using ecore_con_client_data_set.
73 * @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
74 * @c Ecore_Con_Server, an event of this type is emitted. The contents of
75 * the data with this event are variable, but if the client object in the data
76 * is non-null, it must be freed with @ref ecore_con_client_del.
77 * @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
78 * with @ref ecore_con_server_connect, an event of this type is emitted,
79 * allowing for data to be serialized and sent to the server using
80 * @ref ecore_con_server_send. At this point, the http handshake has
82 * @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
83 * usually by the server connection being refused or dropped, an event of this
84 * type is emitted. The contents of the data with this event are variable,
85 * but if the server object in the data is non-null, it must be freed
86 * with @ref ecore_con_server_del.
87 * @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server
88 * object and sends data, an event of this type is emitted. The data will contain both
89 * the size and contents of the message sent by the client. It should be noted that
90 * data within this object is transient, so it must be duplicated in order to be
91 * retained. This event will continue to occur until the client has stopped sending its
92 * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
93 * been received in full, the client object must be freed with ecore_con_client_free.
94 * @li ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination
95 * and receives data, an event of this type is emitted. The data will contain both
96 * the size and contents of the message sent by the server. It should be noted that
97 * data within this object is transient, so it must be duplicated in order to be
98 * retained. This event will continue to occur until the server has stopped sending its
99 * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
100 * been received in full, the server object must be freed with ecore_con_server_free.
107 #define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
108 #define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
112 * @typedef Ecore_Con_Server
113 * A connection handle to a server
114 * @ingroup Ecore_Con_Server_Group
116 typedef struct _Ecore_Con_Server Ecore_Con_Server;
119 * @typedef Ecore_Con_Client
120 * A connection handle to a client
121 * @ingroup Ecore_Con_Client_Group
123 typedef struct _Ecore_Con_Client Ecore_Con_Client;
126 * @typedef Ecore_Con_Url
127 * A handle to an http upload/download object
128 * @ingroup Ecore_Con_Url_Group
130 typedef struct _Ecore_Con_Url Ecore_Con_Url;
134 * @addtogroup Ecore_Con_Events_Group Events
139 * @typedef Ecore_Con_Event_Client_Add
140 * Used as the @p data param for the corresponding event
142 typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
145 * @typedef Ecore_Con_Event_Client_Del
146 * Used as the @p data param for the corresponding event
148 typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
151 * @typedef Ecore_Con_Event_Client_Error
152 * Used as the @p data param for the corresponding event
154 typedef struct _Ecore_Con_Event_Client_Error Ecore_Con_Event_Client_Error;
157 * @typedef Ecore_Con_Event_Server_Add
158 * Used as the @p data param for the corresponding event
160 typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
163 * @typedef Ecore_Con_Event_Server_Del
164 * Used as the @p data param for the corresponding event
166 typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
169 * @typedef Ecore_Con_Event_Server_Error
170 * Used as the @p data param for the corresponding event
172 typedef struct _Ecore_Con_Event_Server_Error Ecore_Con_Event_Server_Error;
175 * @typedef Ecore_Con_Event_Client_Data
176 * Used as the @p data param for the corresponding event
178 typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
181 * @typedef Ecore_Con_Event_Server_Data
182 * Used as the @p data param for the corresponding event
184 typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
187 * @typedef Ecore_Con_Event_Url_Data
188 * Used as the @p data param for the corresponding event
190 typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
193 * @typedef Ecore_Con_Event_Url_Complete
194 * Used as the @p data param for the corresponding event
196 typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
199 * @typedef Ecore_Con_Event_Url_Progress
200 * Used as the @p data param for the corresponding event
202 typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
205 * @struct _Ecore_Con_Event_Client_Add
206 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event
208 struct _Ecore_Con_Event_Client_Add
210 Ecore_Con_Client *client; /** the client that connected */
214 * @struct _Ecore_Con_Event_Client_Del
215 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event
217 struct _Ecore_Con_Event_Client_Del
219 Ecore_Con_Client *client; /** the client that was lost */
223 * @struct _Ecore_Con_Event_Client_Error
224 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event
226 struct _Ecore_Con_Event_Client_Error
228 Ecore_Con_Client *client; /** the client for which an error occurred */
229 char *error; /**< the error string describing what happened */
233 * @struct _Ecore_Con_Event_Server_Add
234 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event
236 struct _Ecore_Con_Event_Server_Add
238 Ecore_Con_Server *server; /** the server that was connected to */
242 * @struct _Ecore_Con_Event_Server_Del
243 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event
245 struct _Ecore_Con_Event_Server_Del
247 Ecore_Con_Server *server; /** the client that was lost */
251 * @struct _Ecore_Con_Event_Server_Error
252 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event
254 struct _Ecore_Con_Event_Server_Error
256 Ecore_Con_Server *server; /** the server for which an error occurred */
257 char *error; /**< the error string describing what happened */
261 * @struct _Ecore_Con_Event_Client_Data
262 * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event
264 struct _Ecore_Con_Event_Client_Data
266 Ecore_Con_Client *client; /**< the client that connected */
267 void *data; /**< the data that the client sent */
268 int size; /**< the length of the data sent */
272 * @struct _Ecore_Con_Event_Server_Data
273 * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
275 struct _Ecore_Con_Event_Server_Data
277 Ecore_Con_Server *server; /**< the server that was connected to */
278 void *data; /**< the data that the server sent */
279 int size; /**< the length of the data sent */
283 * @struct _Ecore_Con_Event_Url_Data
284 * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event
286 struct _Ecore_Con_Event_Url_Data
288 Ecore_Con_Url *url_con;
290 unsigned char data[1];
294 * @struct _Ecore_Con_Event_Url_Complete
295 * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event
297 struct _Ecore_Con_Event_Url_Complete
299 Ecore_Con_Url *url_con;
304 * @struct _Ecore_Con_Event_Url_Progress
305 * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event
307 struct _Ecore_Con_Event_Url_Progress
309 Ecore_Con_Url *url_con;
322 /** A client has connected to the server */
323 EAPI extern int ECORE_CON_EVENT_CLIENT_ADD;
324 /** A client has disconnected from the server */
325 EAPI extern int ECORE_CON_EVENT_CLIENT_DEL;
326 /** A client experienced an error */
327 EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR;
328 /** A server was created */
329 EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
330 /** A server connection was lost */
331 EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
332 /** A server experienced an error */
333 EAPI extern int ECORE_CON_EVENT_SERVER_ERROR;
334 /** A client connected to the server has sent data */
335 EAPI extern int ECORE_CON_EVENT_CLIENT_DATA;
336 /** A server connection object has data */
337 EAPI extern int ECORE_CON_EVENT_SERVER_DATA;
338 /** A URL object has data */
339 EAPI extern int ECORE_CON_EVENT_URL_DATA;
340 /** A URL object has completed its transfer to and from the server and can be reused */
341 EAPI extern int ECORE_CON_EVENT_URL_COMPLETE;
342 /** A URL object has made progress in its transfer */
343 EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
350 * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
356 * @typedef Ecore_Con_Dns_Cb
357 * A callback type for use with @ref ecore_con_lookup.
359 typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
361 struct sockaddr *addr,
366 * @typedef Ecore_Con_Type
367 * @enum _Ecore_Con_Type
368 * Types for an ecore_con client/server object. A correct way to set this type is
369 * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
370 * and LOAD_CERT if the previously loaded certificate should be used.
372 * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
375 typedef enum _Ecore_Con_Type
377 /** Socket in ~/.ecore */
378 ECORE_CON_LOCAL_USER = 0,
379 /** Socket in /tmp */
380 ECORE_CON_LOCAL_SYSTEM = 1,
381 /** Abstract socket */
382 ECORE_CON_LOCAL_ABSTRACT = 2,
383 /** Remote server using TCP */
384 ECORE_CON_REMOTE_TCP = 3,
385 /** Remote multicast server */
386 ECORE_CON_REMOTE_MCAST = 4,
387 /** Remote server using UDP */
388 ECORE_CON_REMOTE_UDP = 5,
389 /** Remote broadcast using UDP */
390 ECORE_CON_REMOTE_BROADCAST = 6,
391 ECORE_CON_REMOTE_NODELAY = 7,
392 /** Use SSL2: UNSUPPORTED. **/
393 ECORE_CON_USE_SSL2 = (1 << 4),
395 ECORE_CON_USE_SSL3 = (1 << 5),
397 ECORE_CON_USE_TLS = (1 << 6),
398 /** Use both TLS and SSL3 */
399 ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
400 /** Attempt to use the loaded certificate */
401 ECORE_CON_LOAD_CERT = (1 << 7)
404 EAPI int ecore_con_init(void);
405 EAPI int ecore_con_shutdown(void);
407 EAPI Eina_Bool ecore_con_lookup(const char *name,
408 Ecore_Con_Dns_Cb done_cb,
416 * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
420 EAPI int ecore_con_ssl_available_get(void);
421 EAPI Eina_Bool ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert);
422 EAPI Eina_Bool ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file);
423 EAPI Eina_Bool ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file);
424 EAPI Eina_Bool ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file);
425 EAPI void ecore_con_ssl_server_verify(Ecore_Con_Server *svr);
432 * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
437 EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
438 const char *name, int port,
441 EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
442 const char *name, int port,
444 EAPI void * ecore_con_server_del(Ecore_Con_Server *svr);
445 EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
446 EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr,
448 EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr);
449 EAPI Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr);
450 EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr);
451 EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr);
452 EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
453 EAPI int ecore_con_server_send(Ecore_Con_Server *svr,
456 EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
458 char reject_excess_clients);
459 EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr);
460 EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
461 EAPI void ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout);
462 EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr);
469 * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
474 EAPI int ecore_con_client_send(Ecore_Con_Client *cl,
477 EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
478 EAPI void * ecore_con_client_del(Ecore_Con_Client *cl);
479 EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl,
481 EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl);
482 EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl);
483 EAPI void ecore_con_client_flush(Ecore_Con_Client *cl);
484 EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl);
485 EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl);
486 EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout);
487 EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl);
488 EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl);
495 * @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions
501 * @typedef Ecore_Con_Url_Time
502 * @enum _Ecore_Con_Url_Time
503 * The type of condition to use when making an HTTP request dependent on time,
504 * so that headers such as "If-Modified-Since" are used.
506 typedef enum _Ecore_Con_Url_Time
509 * Do not place time restrictions on the HTTP requests.
511 ECORE_CON_URL_TIME_NONE = 0,
513 * Add the "If-Modified-Since" HTTP header, so that the request is performed
514 * by the server only if the target has been modified since the time value
515 * passed to it in the request.
517 ECORE_CON_URL_TIME_IFMODSINCE,
519 * Add the "If-Unmodified-Since" HTTP header, so that the request is
520 * performed by the server only if the target has NOT been modified since
521 * the time value passed to it in the request.
523 ECORE_CON_URL_TIME_IFUNMODSINCE
524 } Ecore_Con_Url_Time;
526 EAPI int ecore_con_url_init(void);
527 EAPI int ecore_con_url_shutdown(void);
528 EAPI Ecore_Con_Url * ecore_con_url_new(const char *url);
529 EAPI Ecore_Con_Url * ecore_con_url_custom_new(const char *url,
530 const char *custom_request);
531 EAPI void ecore_con_url_free(Ecore_Con_Url *url_con);
532 EAPI Eina_Bool ecore_con_url_url_set(Ecore_Con_Url *url_con,
534 EAPI void ecore_con_url_data_set(Ecore_Con_Url *url_con,
536 EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con);
537 EAPI void ecore_con_url_additional_header_add(Ecore_Con_Url *url_con,
540 EAPI void ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con);
541 EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con);
542 EAPI void ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
543 EAPI int ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
544 EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
545 const char *username,
546 const char *password,
548 EINA_DEPRECATED EAPI Eina_Bool ecore_con_url_send(Ecore_Con_Url *url_con,
549 const void *data, long length,
550 const char *content_type);
551 EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con);
552 EAPI Eina_Bool ecore_con_url_post(Ecore_Con_Url *url_con,
553 const void *data, long length,
554 const char *content_type);
555 EAPI void ecore_con_url_time(Ecore_Con_Url *url_con,
556 Ecore_Con_Url_Time time_condition,
559 EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
560 const char *filename,
563 const char *upload_dir);
564 EAPI void ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
566 EAPI void ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
569 EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con);
570 EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con,
572 EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con);
573 EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con);
574 EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con,
575 const char * const file_name);
576 EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con,
577 const char * const cookiejar_file);
578 EAPI void ecore_con_url_cookies_jar_write(Ecore_Con_Url *url_con);
580 EAPI void ecore_con_url_ssl_verify_peer_set(Ecore_Con_Url *url_con,
582 EAPI int ecore_con_url_ssl_ca_set(Ecore_Con_Url *url_con,
583 const char *ca_path);