mobile/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    /** Disable all types of proxy on the server
 658     * @note Only functional for clients
 659     * @since 1.2
 660     */
 661    ECORE_CON_NO_PROXY = (1 << 8)
 662 } Ecore_Con_Type;
 663
 664 /**
 665  * Initialises the Ecore_Con library.
 666  * @return  Number of times the library has been initialised without being
 667  *          shut down.
 668  *
 669  * @note This function already calls ecore_init() internally, so you don't need
 670  * to call it explicitly.
 671  */
 672 EAPI int               ecore_con_init(void);
 673
 674 /**
 675  * Shuts down the Ecore_Con library.
 676  * @return  Number of times the library has been initialised without being
 677  *          shut down.
 678  * @note This function already calls ecore_shutdown() internally, so you don't
 679  * need to call it explicitly unless you called ecore_init() explicitly too.
 680  */
 681 EAPI int               ecore_con_shutdown(void);
 682
 683 /**
 684  * Do an asynchronous DNS lookup.
 685  *
 686  * @param name IP address or server name to translate.
 687  * @param done_cb Callback to notify when done.
 688  * @param data User data to be given to done_cb.
 689  * @return @c EINA_TRUE if the request did not fail to be set up, @c EINA_FALSE
 690  * if it failed.
 691  *
 692  * This function performs a DNS lookup on the hostname specified by @p name,
 693  * then calls @p done_cb with the result and the @p data given as parameter.
 694  * The result will be given to the @p done_cb as follows:
 695  * @li @c canonname - the canonical name of the address
 696  * @li @c ip - the resolved ip address
 697  * @li @c addr - a pointer to the socket address
 698  * @li @c addrlen - the length of the socket address, in bytes
 699  * @li @c data - the data pointer given as parameter to ecore_con_lookup()
 700  */
 701 EAPI Eina_Bool         ecore_con_lookup(const char *name,
 702                                             Ecore_Con_Dns_Cb done_cb,
 703                                             const void *data);
 704
 705 /**
 706  * @}
 707  */
 708
 709 /**
 710  * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
 711  *
 712  * @{
 713  */
 714 EAPI int               ecore_con_ssl_available_get(void);
 715 EAPI Eina_Bool         ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert);
 716 EAPI Eina_Bool         ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file);
 717 EAPI Eina_Bool         ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file);
 718 EAPI Eina_Bool         ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file);
 719 EAPI void              ecore_con_ssl_server_verify(Ecore_Con_Server *svr);
 720 EAPI void              ecore_con_ssl_server_verify_basic(Ecore_Con_Server *svr);
 721 EAPI void              ecore_con_ssl_server_verify_name_set(Ecore_Con_Server *svr, const char *name);
 722 EAPI const char       *ecore_con_ssl_server_verify_name_get(Ecore_Con_Server *svr);
 723 EAPI Eina_Bool         ecore_con_ssl_server_upgrade(Ecore_Con_Server *svr, Ecore_Con_Type compl_type);
 724 EAPI Eina_Bool         ecore_con_ssl_client_upgrade(Ecore_Con_Client *cl, Ecore_Con_Type compl_type);
 725
 726 /**
 727  * @}
 728  */
 729
 730 EAPI Ecore_Con_Socks *ecore_con_socks4_remote_add(const char *ip, int port, const char *username);
 731 EAPI Eina_Bool        ecore_con_socks4_remote_exists(const char *ip, int port, const char *username);
 732 EAPI void             ecore_con_socks4_remote_del(const char *ip, int port, const char *username);
 733 EAPI Ecore_Con_Socks *ecore_con_socks5_remote_add(const char *ip, int port, const char *username, const char *password);
 734 EAPI Eina_Bool        ecore_con_socks5_remote_exists(const char *ip, int port, const char *username, const char *password);
 735 EAPI void             ecore_con_socks5_remote_del(const char *ip, int port, const char *username, const char *password);
 736 EAPI void             ecore_con_socks_lookup_set(Ecore_Con_Socks *ecs, Eina_Bool enable);
 737 EAPI Eina_Bool        ecore_con_socks_lookup_get(Ecore_Con_Socks *ecs);
 738 EAPI void             ecore_con_socks_bind_set(Ecore_Con_Socks *ecs, Eina_Bool is_bind);
 739 EAPI Eina_Bool        ecore_con_socks_bind_get(Ecore_Con_Socks *ecs);
 740 EAPI unsigned int     ecore_con_socks_version_get(Ecore_Con_Socks *ecs);
 741 EAPI void             ecore_con_socks_remote_del(Ecore_Con_Socks *ecs);
 742 EAPI void             ecore_con_socks_apply_once(Ecore_Con_Socks *ecs);
 743 EAPI void             ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
 744
 745 /**
 746  * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
 747  *
 748  * This group of functions is applied to an @ref Ecore_Con_Server object. It
 749  * doesn't mean that they should be used in the server application, but on the
 750  * server object. In fact, most of them should be used in the client
 751  * application, when retrieving information or sending data.
 752  *
 753  * Setting up a server is very simple: you just need to start it with
 754  * ecore_con_server_add() and setup some callbacks to the events
 755  * @ref ECORE_CON_EVENT_CLIENT_ADD, @ref ECORE_CON_EVENT_CLIENT_DEL and
 756  * @ref ECORE_CON_EVENT_CLIENT_DATA, that will be called when a client is
 757  * communicating with the server:
 758  *
 759  * @code
 760  * if (!(svr = ecore_con_server_add(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)))
 761  *   exit(1);
 762  *
 763  * ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_ADD, _add_cb, NULL);
 764  * ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DEL, _del_cb, NULL);
 765  * ecore_event_handler_add(ECORE_CON_EVENT_CLIENT_DATA, _data_cb, NULL);
 766  *
 767  * ecore_main_loop_begin();
 768  * @endcode
 769  *
 770  * The function ecore_con_server_connect() can be used to write a client that
 771  * connects to a server. The resulting code will be very similar to the server
 772  * code:
 773  *
 774  * @code
 775  * if (!(svr = ecore_con_server_connect(ECORE_CON_REMOTE_TCP, "127.0.0.1", 8080, NULL)))
 776  *   exit(1);
 777  *
 778  * ecore_event_handler_add(ECORE_CON_EVENT_SERVER_ADD, _add_cb, NULL);
 779  * ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DEL, _del_cb, NULL);
 780  * ecore_event_handler_add(ECORE_CON_EVENT_SERVER_DATA, _data_cb, NULL);
 781  *
 782  * ecore_main_loop_begin();
 783  * @endcode
 784  *
 785  * After these two pieces of code are executed, respectively, in the server and
 786  * client code, the server will be up and running and the client will try to
 787  * connect to it. The connection, with its subsequent messages being sent from
 788  * server to client and client to server, can be represented in the following
 789  * sequence diagram:
 790  *
 791  * @htmlonly
 792  * <img src="ecore_con-client-server.png" style="max-width: 400px"/>
 793  * <a href="ecore_con-client-server.png">Full size</a>
 794  * @endhtmlonly
 795  *
 796  * @image rtf ecore_con-client-server.png
 797  * @image latex ecore_con-client-server.eps width=\textwidth
 798  *
 799  * Please notice the important difference between these two codes: the first is
 800  * used for writing a @b server, while the second should be used for writing a
 801  * @b client.
 802  *
 803  * A reference for the @c client functions can be found at @ref
 804  * Ecore_Con_Client_Group.
 805  *
 806  * Examples of usage for this API can be found here:
 807  * @li @ref ecore_con_server_simple_example_c
 808  * @li @ref ecore_con_client_simple_example_c
 809  *
 810  * @{
 811  */
 812
 813 /**
 814  * Creates a server to listen for connections.
 815  *
 816  * @param  type The connection type.
 817  * @param  name       Name to associate with the socket.  It is used when
 818  *                    generating the socket name of a Unix socket, or for
 819  *                    determining what host to listen on for TCP sockets.
 820  *                    @c NULL will not be accepted.
 821  * @param  port       Number to identify socket.  When a Unix socket is used,
 822  *                    it becomes part of the socket name.  When a TCP socket
 823  *                    is used, it is used as the TCP port.
 824  * @param  data       Data to associate with the created Ecore_Con_Server
 825  *                    object.
 826  * @return A new Ecore_Con_Server.
 827  *
 828  * The socket on which the server listens depends on the connection
 829  * type:
 830  * @li If @a type is @c ECORE_CON_LOCAL_USER, the server will listen on
 831  *     the Unix socket "~/.ecore/[name]/[port]".
 832  * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen
 833  *     on Unix socket "/tmp/.ecore_service|[name]|[port]".
 834  * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server will listen
 835  *     on TCP port @c port.
 836  *
 837  * More information about the @p type can be found at @ref _Ecore_Con_Type.
 838  *
 839  * The @p data parameter can be fetched later using ecore_con_server_data_get()
 840  * or changed with ecore_con_server_data_set().
 841  */
 842 EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
 843                                             const char *name, int port,
 844                                             const void *data);
 845
 846 /**
 847  * Creates a connection to the specified server and returns an associated object.
 848  *
 849  * @param  type The connection type.
 850  * @param  name       Name used when determining what socket to connect to.
 851  *                    It is used to generate the socket name when the socket
 852  *                    is a Unix socket.  It is used as the hostname when
 853  *                    connecting with a TCP socket.
 854  * @param  port       Number to identify the socket to connect to.  Used when
 855  *                    generating the socket name for a Unix socket, or as the
 856  *                    TCP port when connecting to a TCP socket.
 857  * @param  data       Data to associate with the created Ecore_Con_Server
 858  *                    object.
 859  * @return A new Ecore_Con_Server.
 860  *
 861  * The socket to which the connection is made depends on the connection type:
 862  * @li If @a type is @c ECORE_CON_LOCAL_USER, the function will
 863  *     connect to the server at the Unix socket
 864  *     "~/.ecore/[name]/[port]".
 865  * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function will
 866  *     connect to the server at the Unix socket
 867  *     "/tmp/.ecore_service|[name]|[port]".
 868  * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function will
 869  *     connect to the server at the TCP port "[name]:[port]".
 870  *
 871  * More information about the @p type can be found at @ref _Ecore_Con_Type.
 872  *
 873  * This function won't block. It will either succeed, or fail due to invalid
 874  * parameters, failed memory allocation, etc., returning @c NULL on that case.
 875  *
 876  * However, even if this call returns a valid @ref Ecore_Con_Server, the
 877  * connection will only be successfully completed if an event of type
 878  * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
 879  * @ref ECORE_CON_EVENT_SERVER_DEL will be received.
 880  *
 881  * The @p data parameter can be fetched later using ecore_con_server_data_get()
 882  * or changed with ecore_con_server_data_set().
 883  */
 884 EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
 885                                                 const char *name, int port,
 886                                                 const void *data);
 887 /**
 888  * Closes the connection and frees the given server.
 889  *
 890  * @param   svr The given server.
 891  * @return  Data associated with the server when it was created.
 892  *
 893  * All the clients connected to this server will be disconnected.
 894  *
 895  * @see ecore_con_server_add, ecore_con_server_connect
 896  */
 897 EAPI void *            ecore_con_server_del(Ecore_Con_Server *svr);
 898
 899 /**
 900  * Retrieves the data associated with the given server.
 901  *
 902  * @param   svr The given server.
 903  * @return  The associated data.
 904  *
 905  * @see ecore_con_server_data_set()
 906  */
 907 EAPI void *            ecore_con_server_data_get(Ecore_Con_Server *svr);
 908 /**
 909  * Sets the data associated with the given server.
 910  *
 911  * @param svr The given server.
 912  * @param data The data to associate with @p svr
 913  * @return  The previously associated data, if any.
 914  *
 915  * @see ecore_con_server_data_get()
 916  */
 917 EAPI void *            ecore_con_server_data_set(Ecore_Con_Server *svr,
 918                                                  void *data);
 919 /**
 920  * Retrieves whether the given server is currently connected.
 921  *
 922  * @param   svr The given server.
 923  * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise.
 924  */
 925 EAPI Eina_Bool         ecore_con_server_connected_get(Ecore_Con_Server *svr);
 926 /**
 927  * Retrieves the current list of clients.
 928  *
 929  * @param   svr The given server.
 930  * @return  The list of clients on this server.
 931  *
 932  * Each node in the returned list points to an @ref Ecore_Con_Client. This list
 933  * cannot be modified or freed. It can also change if new clients are connected
 934  * or disconnected, and will become invalid when the server is deleted/freed.
 935  */
 936 EAPI const Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr);
 937
 938 /**
 939  * Retrieves the name of server.
 940  *
 941  * @param   svr The given server.
 942  * @return  The name of the server.
 943  *
 944  * The name returned is the name used to connect on this server.
 945  */
 946 EAPI const char *      ecore_con_server_name_get(Ecore_Con_Server *svr);
 947
 948 /**
 949  * Retrieves the server port in use.
 950  *
 951  * @param   svr The given server.
 952  * @return  The server port in use.
 953  *
 954  * The port where the server is listening for connections.
 955  */
 956 EAPI int               ecore_con_server_port_get(Ecore_Con_Server *svr);
 957 /**
 958  * @brief Check how long a server has been connected
 959  *
 960  * @param svr The server to check
 961  * @return The total time, in seconds, that the server has been
 962  * connected/running
 963  *
 964  * This function is used to find out the time that has been elapsed since
 965  * ecore_con_server_add() succeeded.
 966  */
 967 EAPI double            ecore_con_server_uptime_get(Ecore_Con_Server *svr);
 968 /**
 969  * Sends the given data to the given server.
 970  *
 971  * @param   svr  The given server.
 972  * @param   data The given data.
 973  * @param   size Length of the data, in bytes, to send.
 974  * @return  The number of bytes sent.  @c 0 will be returned if there is an
 975  *          error.
 976  *
 977  * This function will send the given data to the server as soon as the program
 978  * is back to the main loop. Thus, this function returns immediately
 979  * (non-blocking). If the data needs to be sent @b now, call
 980  * ecore_con_server_flush() after this one.
 981  *
 982  * @see ecore_con_client_send()
 983  * @see ecore_con_server_flush()
 984  */
 985 EAPI int               ecore_con_server_send(Ecore_Con_Server *svr,
 986                                              const void *data,
 987                                              int size);
 988 /**
 989  * Sets a limit on the number of clients that can be handled concurrently
 990  * by the given server, and a policy on what to do if excess clients try to
 991  * connect.
 992  *
 993  * @param   svr           The given server.
 994  * @param   client_limit  The maximum number of clients to handle
 995  *                        concurrently.  -1 means unlimited (default).  0
 996  *                        effectively disables the server.
 997  * @param   reject_excess_clients  Set to 1 to automatically disconnect
 998  *                        excess clients as soon as they connect if you are
 999  *                        already handling client_limit clients.  Set to 0
1000  *                        (default) to just hold off on the "accept()"
1001  *                        system call until the number of active clients
1002  *                        drops. This causes the kernel to queue up to 4096
1003  *                        connections (or your kernel's limit, whichever is
1004  *                        lower).
1005  *
1006  * Beware that if you set this once ecore is already running, you may
1007  * already have pending CLIENT_ADD events in your event queue.  Those
1008  * clients have already connected and will not be affected by this call.
1009  * Only clients subsequently trying to connect will be affected.
1010  */
1011 EAPI void              ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
1012                                                          int client_limit,
1013                                                          char reject_excess_clients);
1014 /**
1015  * Gets the IP address of a server that has been connected to.
1016  *
1017  * @param   svr           The given server.
1018  * @return  A pointer to an internal string that contains the IP address of
1019  *          the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
1020  *          This string should not be modified or trusted to stay valid after
1021  *          deletion for the @p svr object. If no IP is known @c NULL is
1022  *          returned.
1023  */
1024 EAPI const char *      ecore_con_server_ip_get(Ecore_Con_Server *svr);
1025 /**
1026  * Flushes all pending data to the given server.
1027  *
1028  * @param   svr           The given server.
1029  *
1030  * This function will block until all data is sent to the server.
1031  *
1032  * @see ecore_con_server_send()
1033  * @see ecore_con_client_flush()
1034  */
1035 EAPI void              ecore_con_server_flush(Ecore_Con_Server *svr);
1036 /**
1037  * Set the default time after which an inactive client will be disconnected
1038  *
1039  * @param svr The server object
1040  * @param timeout The timeout, in seconds, to disconnect after
1041  *
1042  * This function is used by the server to set the default idle timeout on
1043  * clients. If the any of the clients becomes idle for a time higher than this
1044  * value, it will be disconnected. A value of < 1 disables the idle timeout.
1045  *
1046  * This timeout is not affected by the one set by
1047  * ecore_con_client_timeout_set(). A client will be disconnected whenever the
1048  * client or the server timeout is reached. That means, the lower timeout value
1049  * will be used for that client if ecore_con_client_timeout_set() is used on it.
1050  *
1051  * @see ecore_con_server_timeout_get()
1052  * @see ecore_con_client_timeout_set()
1053  */
1054 EAPI void              ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout);
1055 /**
1056  * Get the default time after which an inactive client will be disconnected
1057  *
1058  * @param svr The server object
1059  * @return The timeout, in seconds, to disconnect after
1060  *
1061  * This function is used to get the idle timeout for clients.  A value of < 1
1062  * means the idle timeout is disabled.
1063  *
1064  * @see ecore_con_server_timeout_set()
1065  * @see ecore_con_client_timeout_get()
1066  */
1067 EAPI double            ecore_con_server_timeout_get(Ecore_Con_Server *svr);
1068
1069 /**
1070  * Get the fd that the server is connected to
1071  *
1072  * @param svr The server object
1073  * @return The fd, or -1 on failure
1074  *
1075  * This function returns the fd which is used by the underlying server connection.
1076  * It should not be tampered with unless you REALLY know what you are doing.
1077  * @note This function is only valid for servers created with ecore_con_server_connect()
1078  * @warning Seriously. Don't use this unless you know what you are doing.
1079  * @since 1.1
1080  */
1081 EAPI int               ecore_con_server_fd_get(Ecore_Con_Server *svr);
1082
1083 /**
1084  * Get the fd that the client is connected to
1085  *
1086  * @param cl The client object
1087  * @return The fd, or -1 on failure
1088  *
1089  * This function returns the fd which is used by the underlying client connection.
1090  * It should not be tampered with unless you REALLY know what you are doing.
1091  * @since 1.1
1092  */
1093 EAPI int               ecore_con_client_fd_get(Ecore_Con_Client *cl);
1094 /**
1095  * @}
1096  */
1097
1098 /**
1099  * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
1100  *
1101  * Functions to communicate with and/or set options on a client.
1102  *
1103  * This set of functions, as explained in @ref Ecore_Con_Server_Group, is used
1104  * to send data to a client, or to set options and get information about this
1105  * client. Most of them should be used on the server, applied on the client
1106  * object.
1107  *
1108  * If you need to implement a client, the way to connect to a server is
1109  * described in @ref Ecore_Con_Server_Group.
1110  *
1111  * An example of usage of these functions can be found at:
1112  * @li @ref ecore_con_client_simple_example_c
1113  *
1114  * @{
1115  */
1116
1117 /**
1118  * Sends the given data to the given client.
1119  *
1120  * @param   cl   The given client.
1121  * @param   data The given data.
1122  * @param   size Length of the data, in bytes, to send.
1123  * @return  The number of bytes sent.  @c 0 will be returned if there is an
1124  *          error.
1125  *
1126  * This function will send the given data to the client as soon as the program
1127  * is back to the main loop. Thus, this function returns immediately
1128  * (non-blocking). If the data needs to be sent @b now, call
1129  * ecore_con_client_flush() after this one.
1130  *
1131  * @see ecore_con_server_send()
1132  * @see ecore_con_client_flush()
1133  */
1134 EAPI int               ecore_con_client_send(Ecore_Con_Client *cl,
1135                                              const void *data,
1136                                              int size);
1137 /**
1138  * Retrieves the server representing the socket the client has
1139  * connected to.
1140  *
1141  * @param   cl The given client.
1142  * @return  The server that the client connected to.
1143  */
1144 EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
1145 /**
1146  * Closes the connection and frees memory allocated to the given client.
1147  *
1148  * @param   cl The given client.
1149  * @return  Data associated with the client.
1150  */
1151 EAPI void *            ecore_con_client_del(Ecore_Con_Client *cl);
1152 /**
1153  * Sets the data associated with the given client to @p data.
1154  *
1155  * @param   cl   The given client.
1156  * @param   data What to set the data to.
1157  */
1158 EAPI void              ecore_con_client_data_set(Ecore_Con_Client *cl,
1159                                                  const void       *data);
1160 /**
1161  * Retrieves the data associated with the given client.
1162  *
1163  * @param   cl The given client.
1164  * @return  The data associated with @p cl.
1165  */
1166 EAPI void *            ecore_con_client_data_get(Ecore_Con_Client *cl);
1167
1168 /**
1169  * Gets the IP address of a client that has connected.
1170  *
1171  * @param   cl            The given client.
1172  * @return  A pointer to an internal string that contains the IP address of
1173  *          the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation.
1174  *
1175  * The returned string should not be modified, freed or trusted to stay valid
1176  * after deletion for the @p cl object. If no IP is known @c NULL is returned.
1177  */
1178 EAPI const char *      ecore_con_client_ip_get(Ecore_Con_Client *cl);
1179 /**
1180  * Flushes all pending data to the given client.
1181  *
1182  * @param   cl            The given client.
1183  *
1184  * This function will block until all data is sent to the server.
1185  *
1186  * @see ecore_con_client_send()
1187  * @see ecore_con_server_flush()
1188  */
1189 EAPI void              ecore_con_client_flush(Ecore_Con_Client *cl);
1190 /**
1191  * @brief Check how long a client has been connected
1192  *
1193  * @param cl The client to check
1194  * @return The total time, in seconds, that the client has been connected to
1195  * the server
1196  *
1197  * This function is used to find out how long a client has been connected for.
1198  */
1199 EAPI double            ecore_con_client_uptime_get(Ecore_Con_Client *cl);
1200 /**
1201  * Get the default time after which the client will be disconnected when
1202  * inactive
1203  *
1204  * @param cl The client object
1205  * @return The timeout, in seconds, to disconnect after
1206  *
1207  * This function is used to get the idle timeout for a client.  A value of < 1
1208  * means the idle timeout is disabled.
1209  *
1210  * @see ecore_con_client_timeout_set()
1211  */
1212 EAPI double            ecore_con_client_timeout_get(Ecore_Con_Client *cl);
1213 /**
1214  * Set the time after which the client will be disconnected when inactive
1215  *
1216  * @param cl The client object
1217  * @param timeout The timeout, in seconds, to disconnect after
1218  *
1219  * This function is used by the server to set the idle timeout on a specific
1220  * client. If the client becomes idle for a time higher than this value, it will
1221  * be disconnected. A value of < 1 disables the idle timeout.
1222  *
1223  * This timeout is not affected by the one set by
1224  * ecore_con_server_timeout_set(). A client will be disconnected whenever the
1225  * client or the server timeout is reached. That means, the lower timeout value
1226  * will be used for that client if ecore_con_server_timeout_set() is used on the
1227  * server.
1228  *
1229  * @see ecore_con_client_timeout_get()
1230  * @see ecore_con_server_timeout_set()
1231  */
1232 EAPI void              ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout);
1233 /**
1234  * Returns whether the client is still connected
1235  *
1236  * @param   cl The given client.
1237  * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise.
1238  */
1239 EAPI Eina_Bool         ecore_con_client_connected_get(Ecore_Con_Client *cl);
1240 /**
1241  * @brief Return the port that the client has connected to
1242  *
1243  * @param cl The client
1244  * @return The port that @p cl has connected to, or -1 on error
1245  * Use this function to return the port on which a given client has connected.
1246  */
1247 EAPI int               ecore_con_client_port_get(Ecore_Con_Client *cl);
1248
1249
1250
1251 /**
1252  * @}
1253  */
1254
1255 /**
1256  * @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions
1257  *
1258  * Utility functions that set up, use and shut down the Ecore URL
1259  * Connection library.
1260  *
1261  * These functions are a shortcut to make it easy to perform http requests
1262  * (POST, GET, etc).
1263  *
1264  * Brief usage:
1265  * 1. Create an Ecore_Con_Url object with ecore_con_url_new(url);
1266  * 2. Register to receive the #ECORE_CON_EVENT_URL_COMPLETE event
1267  *    (and optionally the #ECORE_CON_EVENT_URL_DATA and
1268  *    #ECORE_CON_EVENT_URL_PROGRESS event to receive
1269  *    the response, e.g. for HTTP/FTP downloads)
1270  * 3. Perform the operation with ecore_con_url_get(...);
1271  *
1272  * Note that it is good to reuse @ref Ecore_Con_Url objects wherever possible,
1273  * but bear in mind that each one can only perform one operation at a time.  You
1274  * need to wait for the #ECORE_CON_EVENT_URL_COMPLETE event before re-using or
1275  * destroying the object.
1276  *
1277  * If it's necessary to change the @ref Ecore_Con_Url object url, use
1278  * ecore_con_url_url_set().
1279  *
1280  * Simple Usage 1 (HTTP GET):
1281  * @code
1282  *   ecore_con_url_url_set(url_con, "http://www.google.com");
1283  *   ecore_con_url_get(url_con);
1284  * @endcode
1285  *
1286  * Simple usage 2 (HTTP POST):
1287  * @code
1288  *   ecore_con_url_url_set(url_con, "http://www.example.com/post_handler.cgi");
1289  *   ecore_con_url_post(url_con, data, data_length, "multipart/form-data");
1290  * @endcode
1291  *
1292  * Simple Usage 3 (FTP download):
1293  * @code
1294  *   fd = creat(filename, 0644)
1295  *   ecore_con_url_url_set(url_con, "ftp://ftp.example.com/pub/myfile");
1296  *   ecore_con_url_fd_set(url_con, fd);
1297  *   ecore_con_url_get(url_con);
1298  * @endcode
1299  *
1300  * Simple Usage 4 (FTP upload as ftp://ftp.example.com/file):
1301  * @code
1302  *   ecore_con_url_url_set(url_con, "ftp://ftp.example.com");
1303  *   ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass", NULL);
1304  * @endcode
1305  *
1306  * Simple Usage 5 (FTP upload as ftp://ftp.example.com/dir/file):
1307  * @code
1308  *   ecore_con_url_url_set(url_con, "ftp://ftp.example.com");
1309  *   ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass","dir");
1310  * @endcode
1311  *
1312  * These are complete examples for the API:
1313  * @li @ref ecore_con_url_download_example.c "Downloading a file"
1314  * @li @ref ecore_con_url_headers_example.c "Setting many options for the connection"
1315  *
1316  * @{
1317  */
1318
1319 /**
1320  * @typedef Ecore_Con_Url_Time
1321  * @enum _Ecore_Con_Url_Time
1322  * The type of condition to use when making an HTTP request dependent on time,
1323  * so that headers such as "If-Modified-Since" are used.
1324  */
1325 typedef enum _Ecore_Con_Url_Time
1326 {
1327    /**
1328     * Do not place time restrictions on the HTTP requests.
1329     */
1330    ECORE_CON_URL_TIME_NONE = 0,
1331    /**
1332     * Add the "If-Modified-Since" HTTP header, so that the request is performed
1333     * by the server only if the target has been modified since the time value
1334     * passed to it in the request.
1335     */
1336    ECORE_CON_URL_TIME_IFMODSINCE,
1337    /**
1338     * Add the "If-Unmodified-Since" HTTP header, so that the request is
1339     * performed by the server only if the target has NOT been modified since
1340     * the time value passed to it in the request.
1341     */
1342    ECORE_CON_URL_TIME_IFUNMODSINCE
1343 } Ecore_Con_Url_Time;
1344
1345 /**
1346  * @typedef Ecore_Con_Url_Http_Version
1347  * @enum _Ecore_Con_Url_Http_Version
1348  * The http version to use
1349  * @since 1.2
1350  */
1351 typedef enum _Ecore_Con_Url_Http_Version
1352 {
1353    /**
1354     * HTTP version 1.0
1355     * @since 1.2
1356     */
1357    ECORE_CON_URL_HTTP_VERSION_1_0,
1358    /**
1359     * HTTP version 1.1 (default)
1360     * @since 1.2
1361     */
1362    ECORE_CON_URL_HTTP_VERSION_1_1
1363 } Ecore_Con_Url_Http_Version;
1364
1365 /**
1366  * Change the HTTP version used for the request
1367  * @param url_con Connection object through which the request will be sent.
1368  * @param version The version to be used
1369  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure to change version.
1370  * @since 1.2
1371  * @see ecore_con_url_pipeline_get()
1372  */
1373 EAPI Eina_Bool         ecore_con_url_http_version_set(Ecore_Con_Url *url_con, Ecore_Con_Url_Http_Version version);
1374
1375 /**
1376  * Initialises the Ecore_Con_Url library.
1377  * @return Number of times the library has been initialised without being
1378  *          shut down.
1379  *
1380  * @note This function doesn't call ecore_con_init(). You still need to call it
1381  * explicitly before calling this one.
1382  */
1383 EAPI int               ecore_con_url_init(void);
1384
1385 /**
1386  * Shuts down the Ecore_Con_Url library.
1387  * @return  Number of calls that still uses Ecore_Con_Url
1388  *
1389  * @note This function doesn't call ecore_con_shutdown(). You still need to call
1390  * it explicitly after calling this one.
1391  */
1392 EAPI int               ecore_con_url_shutdown(void);
1393
1394 /**
1395  * Enable or disable HTTP 1.1 pipelining.
1396  * @param enable @c EINA_TRUE will turn it on, @c EINA_FALSE will disable it.
1397  *
1398  * Pipelining allows to send one request after another one, without having to
1399  * wait for the reply of the first request. The respective replies are received
1400  * in the order that the requests were sent.
1401  *
1402  * Enabling this feature will be valid for all requests done using @c
1403  * ecore_con_url.
1404  *
1405  * See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.
1406  *
1407  * @see ecore_con_url_pipeline_get()
1408  */
1409 EAPI void              ecore_con_url_pipeline_set(Eina_Bool enable);
1410 /**
1411  * Is HTTP 1.1 pipelining enable ?
1412  * @return @c EINA_TRUE if it is enable.
1413  *
1414  * @see ecore_con_url_pipeline_set()
1415  */
1416 EAPI Eina_Bool         ecore_con_url_pipeline_get(void);
1417
1418 /**
1419  * Creates and initializes a new Ecore_Con_Url connection object.
1420  *
1421  * @param url URL that will receive requests. Can be changed using
1422  *            ecore_con_url_url_set.
1423  *
1424  * @return @c NULL on error, a new Ecore_Con_Url on success.
1425  *
1426  * Creates and initializes a new Ecore_Con_Url connection object that can be
1427  * used for sending requests.
1428  *
1429  * @see ecore_con_url_custom_new()
1430  * @see ecore_con_url_url_set()
1431  */
1432 EAPI Ecore_Con_Url *   ecore_con_url_new(const char *url);
1433 /**
1434  * Creates a custom connection object.
1435  *
1436  * @param url URL that will receive requests
1437  * @param custom_request Custom request (e.g. GET, POST, HEAD, PUT, etc)
1438  *
1439  * @return @c NULL on error, a new Ecore_Con_Url on success.
1440  *
1441  * Creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD,
1442  * SUBSCRIBE and other obscure HTTP requests). This object should be used like
1443  * one created with ecore_con_url_new().
1444  *
1445  * @see ecore_con_url_new()
1446  * @see ecore_con_url_url_set()
1447  */
1448 EAPI Ecore_Con_Url *   ecore_con_url_custom_new(const char *url,
1449                                                 const char *custom_request);
1450 /**
1451  * Destroys a Ecore_Con_Url connection object.
1452  *
1453  * @param url_con Connection object to free.
1454  *
1455  * @see ecore_con_url_new()
1456  */
1457 EAPI void              ecore_con_url_free(Ecore_Con_Url *url_con);
1458 /**
1459  * Sets the URL to send the request to.
1460  *
1461  * @param url_con Connection object through which the request will be sent.
1462  * @param url URL that will receive the request
1463  *
1464  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1465  */
1466 EAPI Eina_Bool         ecore_con_url_url_set(Ecore_Con_Url *url_con,
1467                                              const char *url);
1468 /**
1469  * Gets the URL to send the request to.
1470  *
1471  * @param url_con Connection object through which the request will be sent.
1472  * @return URL that will receive the request, @c NULL on failure. URL is
1473  * stringshared.
1474  * @since 1.1
1475  */
1476 EAPI const char       *ecore_con_url_url_get(Ecore_Con_Url *url_con);
1477 /**
1478  * Associates data with a connection object.
1479  *
1480  * @param url_con Connection object to associate data.
1481  * @param data Data to be set.
1482  *
1483  * Associates data with a connection object, which can be retrieved later with
1484  * ecore_con_url_data_get()).
1485  *
1486  * @see ecore_con_url_data_get()
1487  */
1488 EAPI void              ecore_con_url_data_set(Ecore_Con_Url *url_con,
1489                                               void *data);
1490 /**
1491  * Retrieves data associated with a Ecore_Con_Url connection object.
1492  *
1493  * @param url_con Connection object to retrieve data from.
1494  *
1495  * @return Data associated with the given object.
1496  *
1497  * Retrieves data associated with a Ecore_Con_Url connection object (previously
1498  * set with ecore_con_url_data_set()).
1499  *
1500  * @see ecore_con_url_data_set()
1501  */
1502 EAPI void *            ecore_con_url_data_get(Ecore_Con_Url *url_con);
1503 /**
1504  * Adds an additional header to the request connection object.
1505  *
1506  * @param url_con Connection object
1507  * @param key Header key
1508  * @param value Header value
1509  *
1510  * Adds an additional header (User-Agent, Content-Type, etc.) to the request
1511  * connection object. This addition will be valid for only one
1512  * ecore_con_url_get() or ecore_con_url_post() call.
1513  *
1514  * Some functions like ecore_con_url_time() also add headers to the request.
1515  *
1516  * @see ecore_con_url_get()
1517  * @see ecore_con_url_post()
1518  * @see ecore_con_url_additional_headers_clear()
1519  */
1520 EAPI void              ecore_con_url_additional_header_add(Ecore_Con_Url *url_con,
1521                                                            const char *key,
1522                                                            const char *value);
1523 /**
1524  * Cleans additional headers.
1525  *
1526  * @param url_con Connection object to clean additional headers.
1527  *
1528  * Cleans additional headers associated with a connection object (previously
1529  * added with ecore_con_url_additional_header_add()).
1530  *
1531  * @see ecore_con_url_additional_header_add()
1532  * @see ecore_con_url_get()
1533  * @see ecore_con_url_post()
1534  */
1535 EAPI void              ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con);
1536 /**
1537  * Retrieves headers from last request sent.
1538  *
1539  * @param url_con Connection object to retrieve response headers from.
1540  *
1541  * Retrieves a list containing the response headers. This function should be
1542  * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be
1543  * ready at that time).
1544  *
1545  * @return List of response headers. This list must not be modified by the user.
1546  */
1547 EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con);
1548 /**
1549  * Setup a file for receiving response data.
1550  *
1551  * @param url_con Connection object to set file
1552  * @param fd File descriptor associated with the file. A negative value will
1553  * unset any previously set fd.
1554  *
1555  * Sets up a file to have response data written into. Note that
1556  * ECORE_CON_EVENT_URL_DATA events will not be emitted if a file has been set to
1557  * receive the response data.
1558  *
1559  * This call can be used to easily setup a file where the downloaded data will
1560  * be saved.
1561  */
1562 EAPI void              ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
1563 /**
1564  * Retrieves the number of bytes received.
1565  *
1566  * Retrieves the number of bytes received on the last request of the given
1567  * connection object.
1568  *
1569  * @param url_con Connection object which the request was sent on.
1570  *
1571  * @return Number of bytes received on request.
1572  *
1573  * @see ecore_con_url_get()
1574  * @see ecore_con_url_post()
1575  */
1576 EAPI int               ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
1577 /**
1578  * Sets url_con to use http auth, with given username and password, "safely" or not.
1579  *
1580  * @param url_con Connection object to perform a request on, previously created
1581  *    with ecore_con_url_new() or ecore_con_url_custom_new().
1582  * @param username Username to use in authentication
1583  * @param password Password to use in authentication
1584  * @param safe Whether to use "safer" methods (eg, NOT http basic auth)
1585  *
1586  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1587  *
1588  * @attention Requires libcurl >= 7.19.1 to work, otherwise will always return
1589  * @c 0.
1590  */
1591 EAPI Eina_Bool         ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
1592                                                   const char *username,
1593                                                   const char *password,
1594                                                   Eina_Bool safe);
1595 /**
1596  * Sends a get request.
1597  *
1598  * @param url_con Connection object to perform a request on, previously created
1599  *
1600  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1601  *
1602  * The request is performed immediately, but you need to setup event handlers
1603  * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
1604  * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
1605  *
1606  * @see ecore_con_url_custom_new()
1607  * @see ecore_con_url_additional_headers_clear()
1608  * @see ecore_con_url_additional_header_add()
1609  * @see ecore_con_url_data_set()
1610  * @see ecore_con_url_data_get()
1611  * @see ecore_con_url_response_headers_get()
1612  * @see ecore_con_url_time()
1613  * @see ecore_con_url_post()
1614  */
1615 EAPI Eina_Bool         ecore_con_url_get(Ecore_Con_Url *url_con);
1616 /**
1617  * Sends a post request.
1618  *
1619  * @param url_con Connection object to perform a request on, previously created
1620  *                with ecore_con_url_new() or ecore_con_url_custom_new().
1621  * @param data    Payload (data sent on the request). Can be @c NULL.
1622  * @param length  Payload length. If @c -1, rely on automatic length
1623  *                calculation via @c strlen() on @p data.
1624  * @param content_type Content type of the payload (e.g. text/xml). Can be @c
1625  * NULL.
1626  *
1627  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1628  *
1629  * The request starts immediately, but you need to setup event handlers
1630  * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
1631  * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
1632  *
1633  * This call won't block your main loop.
1634  *
1635  * @see ecore_con_url_custom_new()
1636  * @see ecore_con_url_additional_headers_clear()
1637  * @see ecore_con_url_additional_header_add()
1638  * @see ecore_con_url_data_set()
1639  * @see ecore_con_url_data_get()
1640  * @see ecore_con_url_response_headers_get()
1641  * @see ecore_con_url_time()
1642  * @see ecore_con_url_get()
1643  */
1644 EAPI Eina_Bool         ecore_con_url_post(Ecore_Con_Url *url_con,
1645                                           const void *data, long length,
1646                                           const char *content_type);
1647 /**
1648  * Sets whether HTTP requests should be conditional, dependent on
1649  * modification time.
1650  *
1651  * @param url_con   Ecore_Con_Url to act upon.
1652  * @param time_condition Condition to use for HTTP requests.
1653  * @param timestamp Time since 1 Jan 1970 to use in the condition.
1654  *
1655  * This function may set the header "If-Modified-Since" or
1656  * "If-Unmodified-Since", depending on the value of @p time_condition, with the
1657  * value @p timestamp.
1658  *
1659  * @sa ecore_con_url_get()
1660  * @sa ecore_con_url_post()
1661  */
1662 EAPI void              ecore_con_url_time(Ecore_Con_Url *url_con,
1663                                           Ecore_Con_Url_Time time_condition,
1664                                           double timestamp);
1665
1666 /**
1667  * @brief Uploads a file to an ftp site.
1668  *
1669  * @param url_con The Ecore_Con_Url object to send with
1670  * @param filename The path to the file to send
1671  * @param user The username to log in with
1672  * @param pass The password to log in with
1673  * @param upload_dir The directory to which the file should be uploaded
1674  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
1675  *
1676  * Upload @p filename to an ftp server set in @p url_con using @p user
1677  * and @p pass to directory @p upload_dir
1678  */
1679 EAPI Eina_Bool         ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
1680                                                 const char *filename,
1681                                                 const char *user,
1682                                                 const char *pass,
1683                                                 const char *upload_dir);
1684 /**
1685  * Toggle libcurl's verbose output.
1686  *
1687  * @param url_con Ecore_Con_Url instance which will be acted upon.
1688  * @param verbose Whether or not to enable libcurl's verbose output.
1689  *
1690  * If @p verbose is @c EINA_TRUE, libcurl will output a lot of verbose
1691  * information about its operations, which is useful for
1692  * debugging. The verbose information will be sent to stderr.
1693  */
1694 EAPI void              ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
1695                                                  Eina_Bool verbose);
1696 /**
1697  * Enable or disable EPSV extension
1698  * @param url_con  The Ecore_Con_Url instance which will be acted upon.
1699  * @param use_epsv Boolean to enable/disable the EPSV extension.
1700  */
1701 EAPI void              ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
1702                                                       Eina_Bool use_epsv);
1703
1704 /**
1705  * Enables the cookie engine for subsequent HTTP requests.
1706  *
1707  * @param url_con Ecore_Con_Url instance which will be acted upon.
1708  *
1709  * After this function is called, cookies set by the server in HTTP responses
1710  * will be parsed and stored, as well as sent back to the server in new HTTP
1711  * requests.
1712  *
1713  * @note Even though this function is called @c ecore_con_url_cookies_init(),
1714  * there is no symmetrical shutdown operation.
1715  */
1716 EAPI void              ecore_con_url_cookies_init(Ecore_Con_Url *url_con);
1717 /**
1718  * Controls whether session cookies from previous sessions shall be loaded.
1719  *
1720  * @param url_con Ecore_Con_Url instance which will be acted upon.
1721  * @param ignore  If @c EINA_TRUE, ignore session cookies when loading cookies
1722  *                from files. If @c EINA_FALSE, all cookies will be loaded.
1723  *
1724  * Session cookies are cookies with no expire date set, which usually means
1725  * they are removed after the current session is closed.
1726  *
1727  * By default, when Ecore_Con_Url loads cookies from a file, all cookies are
1728  * loaded, including session cookies, which, most of the time, were supposed
1729  * to be loaded and valid only for that session.
1730  *
1731  * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from
1732  * the files passed to @c ecore_con_url_cookies_file_add(), session cookies
1733  * will not be loaded.
1734  *
1735  * @see ecore_con_url_cookies_file_add()
1736  */
1737 EAPI void              ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con,
1738                                                                     Eina_Bool ignore);
1739 /**
1740  * Clears currently loaded cookies.
1741  * @param url_con      Ecore_Con_Url instance which will be acted upon.
1742  *
1743  * The cleared cookies are removed and will not be sent in subsequent HTTP
1744  * requests, nor will they be written to the cookiejar file set via
1745  * @c ecore_con_url_cookies_jar_file_set().
1746  *
1747  * @note This function will initialize the cookie engine if it has not been
1748  *       initialized yet.
1749  * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
1750  *       immediately, just when the request is started. Thus, if you ask to
1751  *       clear the cookies, but has a file already set by that function, the
1752  *       cookies will then be loaded and you will have old cookies set. In order
1753  *       to don't have any old cookie set, you need to don't call
1754  *       ecore_con_url_cookies_file_add() ever on the @p url_con handler, and
1755  *       call this function to clear any cookie set by a previous request on
1756  *       this handler.
1757  *
1758  * @see ecore_con_url_cookies_session_clear()
1759  * @see ecore_con_url_cookies_ignore_old_session_set()
1760  */
1761 EAPI void              ecore_con_url_cookies_clear(Ecore_Con_Url *url_con);
1762 /**
1763  * Clears currently loaded session cookies.
1764  *
1765  * @param url_con      Ecore_Con_Url instance which will be acted upon.
1766  *
1767  * Session cookies are cookies with no expire date set, which usually means
1768  * they are removed after the current session is closed.
1769  *
1770  * The cleared cookies are removed and will not be sent in subsequent HTTP
1771  * requests, nor will they be written to the cookiejar file set via
1772  * @c ecore_con_url_cookies_jar_file_set().
1773  *
1774  * @note This function will initialize the cookie engine if it has not been
1775  *       initialized yet.
1776  * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
1777  *       immediately, just when the request is started. Thus, if you ask to
1778  *       clear the session cookies, but has a file already set by that function,
1779  *       the session cookies will then be loaded and you will have old cookies
1780  *       set.  In order to don't have any old session cookie set, you need to
1781  *       don't call ecore_con_url_cookies_file_add() ever on the @p url_con
1782  *       handler, and call this function to clear any session cookie set by a
1783  *       previous request on this handler. An easier way to don't use old
1784  *       session cookies is by using the function
1785  *       ecore_con_url_cookies_ignore_old_session_set().
1786  *
1787  * @see ecore_con_url_cookies_clear()
1788  * @see ecore_con_url_cookies_ignore_old_session_set()
1789  */
1790 EAPI void              ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con);
1791 /**
1792  * Adds a file to the list of files from which to load cookies.
1793  *
1794  * @param url_con   Ecore_Con_Url instance which will be acted upon.
1795  * @param file_name Name of the file that will be added to the list.
1796  *
1797  * Files must contain cookies defined according to two possible formats:
1798  *
1799  * @li HTTP-style header ("Set-Cookie: ...").
1800  * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a>
1801  *
1802  * Cookies will only be @b read from this file. If you want to save cookies to a
1803  * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this
1804  * function supports the both types of cookie file cited above, while
1805  * ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's
1806  * format.
1807  *
1808  * Please notice that the file will not be read immediately, but rather added
1809  * to a list of files that will be loaded and parsed at a later time.
1810  *
1811  * @note This function will initialize the cookie engine if it has not been
1812  *       initialized yet.
1813  *
1814  * @see ecore_con_url_cookies_ignore_old_session_set()
1815  * @see ecore_con_url_cookies_jar_file_set()
1816  */
1817 EAPI void              ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con,
1818                                                       const char * const file_name);
1819 /**
1820  * Sets the name of the file to which all current cookies will be written when
1821  * either cookies are flushed or Ecore_Con is shut down.
1822  *
1823  * @param url_con        Ecore_Con_Url instance which will be acted upon.
1824  * @param cookiejar_file File to which the cookies will be written.
1825  *
1826  * @return @c EINA_TRUE is the file name has been set successfully,
1827  *         @c EINA_FALSE otherwise.
1828  *
1829  * Cookies are written following Netscape/Mozilla's data format, also known as
1830  * cookie-jar.
1831  *
1832  * Cookies will only be @b saved to this file. If you need to read cookies from
1833  * a file, use ecore_con_url_cookies_file_add() instead.
1834  *
1835  * @note This function will initialize the cookie engine if it has not been
1836  *       initialized yet.
1837  *
1838  * @see ecore_con_url_cookies_jar_write()
1839  */
1840 EAPI Eina_Bool         ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con,
1841                                                           const char * const cookiejar_file);
1842 /**
1843  * Writes all current cookies to the cookie jar immediately.
1844  *
1845  * @param url_con Ecore_Con_Url instance which will be acted upon.
1846  *
1847  * A cookie-jar file must have been previously set by
1848  * @c ecore_con_url_jar_file_set, otherwise nothing will be done.
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_file_set()
1854  */
1855 EAPI void              ecore_con_url_cookies_jar_write(Ecore_Con_Url *url_con);
1856
1857 EAPI void              ecore_con_url_ssl_verify_peer_set(Ecore_Con_Url *url_con,
1858                                                          Eina_Bool verify);
1859 EAPI int               ecore_con_url_ssl_ca_set(Ecore_Con_Url *url_con,
1860                                                 const char *ca_path);
1861
1862 /**
1863  * Set HTTP proxy to use.
1864  *
1865  * The parameter should be a char * to a zero terminated string holding
1866  * the host name or dotted IP address. To specify port number in this string,
1867  * append :[port] to the end of the host name.
1868  * The proxy string may be prefixed with [protocol]:// since any such prefix
1869  * will be ignored.
1870  * The proxy's port number may optionally be specified with the separate option.
1871  * If not specified, libcurl will default to using port 1080 for proxies.
1872  *
1873  * @param url_con Connection object that will use the proxy.
1874  * @param proxy Porxy string or @c NULL to disable
1875  *
1876  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1877  * @since 1.2
1878  */
1879 EAPI Eina_Bool ecore_con_url_proxy_set(Ecore_Con_Url *url_con, const char *proxy);
1880
1881 /**
1882  * Set zero terminated username to use for proxy.
1883  *
1884  * if socks protocol is used for proxy, protocol should be socks5 and above.
1885  *
1886  * @param url_con Connection object that will use the proxy.
1887  * @param username Username string.
1888  *
1889  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1890  *
1891  * @see ecore_con_url_proxy_set()
1892  *
1893  * @since 1.2
1894  */
1895 EAPI Eina_Bool ecore_con_url_proxy_username_set(Ecore_Con_Url *url_con, const char *username);
1896
1897 /**
1898  * Set zero terminated password to use for proxy.
1899  *
1900  * if socks protocol is used for proxy, protocol should be socks5 and above.
1901  *
1902  * @param url_con Connection object that will use the proxy.
1903  * @param password Password string.
1904  *
1905  * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
1906  *
1907  * @see ecore_con_url_proxy_set()
1908  *
1909  * @since 1.2
1910  */
1911 EAPI Eina_Bool ecore_con_url_proxy_password_set(Ecore_Con_Url *url_con, const char *password);
1912
1913 /**
1914  * Set timeout in seconds.
1915  *
1916  * the maximum time in seconds that you allow the ecore con url transfer
1917  * operation to take. Normally, name lookups can take a considerable time
1918  * and limiting operations to less than a few minutes risk aborting perfectly
1919  * normal operations.
1920  *
1921  * @param url_con Connection object that will use the timeout.
1922  * @param timeout time in seconds.
1923  *
1924  * @see ecore_con_url_cookies_jar_file_set()
1925  *
1926  * @since 1.2
1927  */
1928 EAPI void ecore_con_url_timeout_set(Ecore_Con_Url *url_con, double timeout);
1929
1930 /**
1931  * Get the returned HTTP STATUS code
1932  *
1933  * This is used to, at any time, try to return the status code for a transmission.
1934  * @param url_con Connection object
1935  * @return A valid HTTP STATUS code, or 0 on failure
1936  *
1937  * @since 1.2
1938  */
1939 EAPI int ecore_con_url_status_code_get(Ecore_Con_Url *url_con);
1940 /**
1941  * @}
1942  */
1943
1944 #ifdef __cplusplus
1945 }
1946 #endif
1947
1948 #endif