src/lib/ecore_con/Ecore_Con.h

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