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 _MSC_VER
  18 # ifdef BUILDING_DLL
  19 #  define EAPI __declspec(dllexport)
  20 # else
  21 #  define EAPI __declspec(dllimport)
  22 # endif
  23 #else
  24 # ifdef __GNUC__
  25 #  if __GNUC__ >= 4
  26 #   define EAPI __attribute__ ((visibility("default")))
  27 #  else
  28 #   define EAPI
  29 #  endif
  30 # else
  31 #  define EAPI
  32 # endif
  33 #endif
  34
  35 /**
  36  * @defgroup Ecore_Con_Group Ecore_Con - Connection functions
  37  *
  38  * The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
  39  * for communications between programs using reliable sockets.  It saves
  40  * the programmer from having to worry about file descriptors and waiting
  41  * for incoming connections.
  42  *
  43  * There are two main objects in the @c Ecore_Con library: the @c
  44  * Ecore_Con_Server and the @c Ecore_Con_Client.
  45  *
  46  * The @c Ecore_Con_Server represents a server that can be connected to.
  47  * It is used regardless of whether the program is acting as a server or
  48  * client itself.
  49  *
  50  * To create a listening server call @c ecore_con_server_add(), optionally using
  51  * an ECORE_CON_USE_* encryption type OR'ed with the type for encryption.
  52  *
  53  * To connect to a server, call @c ecore_con_server_connect().  Data can
  54  * then be sent to the server using the @c ecore_con_server_send().
  55  *
  56  * Functions are described in the following groupings:
  57  * @li @ref Ecore_Con_Lib_Group
  58  * @li @ref Ecore_Con_Server_Group
  59  * @li @ref Ecore_Con_Client_Group
  60  * @li @ref Ecore_Con_Url_Group
  61  *
  62  * Events are described in @ref Ecore_Con_Events_Group.
  63  */
  64
  65
  66 /**
  67  * @defgroup Ecore_Con_Events_Group Events
  68  *
  69  * @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
  70  * @c Ecore_Con_Server, an event of this type is emitted, allowing the
  71  * retrieval of the client's ip with @ref ecore_con_client_ip_get and
  72  * associating data with the client using ecore_con_client_data_set.
  73  * @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
  74  * @c Ecore_Con_Server, an event of this type is emitted.  The contents of
  75  * the data with this event are variable, but if the client object in the data
  76  * is non-null, it must be freed with @ref ecore_con_client_del.
  77  * @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
  78  * with @ref ecore_con_server_connect, an event of this type is emitted,
  79  * allowing for data to be serialized and sent to the server using
  80  * @ref ecore_con_server_send. At this point, the http handshake has
  81  * occurred.
  82  * @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
  83  * usually by the server connection being refused or dropped, an event of this
  84  * type is emitted.  The contents of the data with this event are variable,
  85  * but if the server object in the data is non-null, it must be freed
  86  * with @ref ecore_con_server_del.
  87  * @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server
  88  * object and sends data, an event of this type is emitted.  The data will contain both
  89  * the size and contents of the message sent by the client.  It should be noted that
  90  * data within this object is transient, so it must be duplicated in order to be
  91  * retained.  This event will continue to occur until the client has stopped sending its
  92  * message, so a good option for storing this data is an Eina_Strbuf.  Once the message has
  93  * been received in full, the client object must be freed with ecore_con_client_free.
  94  * @li ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination
  95  * and receives data, an event of this type is emitted.  The data will contain both
  96  * the size and contents of the message sent by the server.  It should be noted that
  97  * data within this object is transient, so it must be duplicated in order to be
  98  * retained.  This event will continue to occur until the server has stopped sending its
  99  * message, so a good option for storing this data is an Eina_Strbuf.  Once the message has
 100  * been received in full, the server object must be freed with ecore_con_server_free.
 101  *
 102  */
 103
 104 #ifdef __cplusplus
 105 extern "C" {
 106 #endif
 107 #define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
 108 #define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
 109
 110
 111 /**
 112  * @typedef Ecore_Con_Server
 113  * A connection handle to a server
 114  * @ingroup Ecore_Con_Server_Group
 115  */
 116 typedef struct _Ecore_Con_Server Ecore_Con_Server;
 117
 118 /**
 119  * @typedef Ecore_Con_Client
 120  * A connection handle to a client
 121  * @ingroup Ecore_Con_Client_Group
 122  */
 123 typedef struct _Ecore_Con_Client Ecore_Con_Client;
 124
 125 /**
 126  * @typedef Ecore_Con_Url
 127  * A handle to an http upload/download object
 128  * @ingroup Ecore_Con_Url_Group
 129  */
 130 typedef struct _Ecore_Con_Url Ecore_Con_Url;
 131
 132
 133 /**
 134  * @addtogroup Ecore_Con_Events_Group Events
 135  * @{
 136  */
 137
 138 /**
 139  * @typedef Ecore_Con_Event_Client_Add
 140  * Used as the @p data param for the corresponding event
 141  */
 142 typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
 143
 144 /**
 145  * @typedef Ecore_Con_Event_Client_Del
 146  * Used as the @p data param for the corresponding event
 147  */
 148 typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
 149
 150 /**
 151  * @typedef Ecore_Con_Event_Server_Add
 152  * Used as the @p data param for the corresponding event
 153  */
 154 typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
 155
 156 /**
 157  * @typedef Ecore_Con_Event_Server_Del
 158  * Used as the @p data param for the corresponding event
 159  */
 160 typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
 161
 162 /**
 163  * @typedef Ecore_Con_Event_Client_Data
 164  * Used as the @p data param for the corresponding event
 165  */
 166 typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
 167
 168 /**
 169  * @typedef Ecore_Con_Event_Server_Data
 170  * Used as the @p data param for the corresponding event
 171  */
 172 typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
 173
 174 /**
 175  * @typedef Ecore_Con_Event_Url_Data
 176  * Used as the @p data param for the corresponding event
 177  */
 178 typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
 179
 180 /**
 181  * @typedef Ecore_Con_Event_Url_Complete
 182  * Used as the @p data param for the corresponding event
 183  */
 184 typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
 185
 186 /**
 187  * @typedef Ecore_Con_Event_Url_Progress
 188  * Used as the @p data param for the corresponding event
 189  */
 190 typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
 191
 192 /**
 193  * @struct _Ecore_Con_Event_Client_Add
 194  * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event
 195  */
 196 struct _Ecore_Con_Event_Client_Add
 197 {
 198    Ecore_Con_Client *client; /** the client that connected */
 199 };
 200
 201 /**
 202  * @struct _Ecore_Con_Event_Client_Del
 203  * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event
 204  */
 205 struct _Ecore_Con_Event_Client_Del
 206 {
 207    Ecore_Con_Client *client; /** the client that was lost */
 208 };
 209
 210 /**
 211  * @struct _Ecore_Con_Event_Server_Add
 212  * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event
 213  */
 214 struct _Ecore_Con_Event_Server_Add
 215 {
 216    Ecore_Con_Server *server; /** the server that was connected to */
 217 };
 218
 219 /**
 220  * @struct _Ecore_Con_Event_Server_Del
 221  * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event
 222  */
 223 struct _Ecore_Con_Event_Server_Del
 224 {
 225    Ecore_Con_Server *server; /** the client that was lost */
 226 };
 227
 228 /**
 229  * @struct _Ecore_Con_Event_Client_Data
 230  * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event
 231  */
 232 struct _Ecore_Con_Event_Client_Data
 233 {
 234    Ecore_Con_Client *client; /**< the client that connected */
 235    void *data;               /**< the data that the client sent */
 236    int size;                 /**< the length of the data sent */
 237 };
 238
 239 /**
 240  * @struct _Ecore_Con_Event_Server_Data
 241  * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
 242  */
 243 struct _Ecore_Con_Event_Server_Data
 244 {
 245    Ecore_Con_Server *server; /**< the server that was connected to */
 246    void *data;               /**< the data that the server sent */
 247    int size;                 /**< the length of the data sent */
 248 };
 249
 250 /**
 251  * @struct _Ecore_Con_Event_Url_Data
 252  * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event
 253  */
 254 struct _Ecore_Con_Event_Url_Data
 255 {
 256    Ecore_Con_Url *url_con;
 257    int size;
 258    unsigned char data[1];
 259 };
 260
 261 /**
 262  * @struct _Ecore_Con_Event_Url_Complete
 263  * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event
 264  */
 265 struct _Ecore_Con_Event_Url_Complete
 266 {
 267    Ecore_Con_Url *url_con;
 268    int status;
 269 };
 270
 271 /**
 272  * @struct _Ecore_Con_Event_Url_Progress
 273  * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event
 274  */
 275 struct _Ecore_Con_Event_Url_Progress
 276 {
 277    Ecore_Con_Url *url_con;
 278    struct
 279    {
 280       double total;
 281       double now;
 282    } down;
 283    struct
 284    {
 285       double total;
 286       double now;
 287    } up;
 288 };
 289
 290 /** A client has connected to the server */
 291 EAPI extern int ECORE_CON_EVENT_CLIENT_ADD;
 292 /** A client has disconnected from the server */
 293 EAPI extern int ECORE_CON_EVENT_CLIENT_DEL;
 294 /** A server was created */
 295 EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
 296 /** A server connection was lost */
 297 EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
 298 /** A client connected to the server has sent data */
 299 EAPI extern int ECORE_CON_EVENT_CLIENT_DATA;
 300 /** A server connection object has data */
 301 EAPI extern int ECORE_CON_EVENT_SERVER_DATA;
 302 /** A URL object has data */
 303 EAPI extern int ECORE_CON_EVENT_URL_DATA;
 304 /** A URL object has completed its transfer to and from the server and can be reused */
 305 EAPI extern int ECORE_CON_EVENT_URL_COMPLETE;
 306 /** A URL object has made progress in its transfer */
 307 EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
 308
 309 /**
 310  * @}
 311  */
 312
 313 /**
 314  * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
 315  *
 316  * @{
 317  */
 318
 319 /**
 320  * @typedef Ecore_Con_Dns_Cb
 321  * A callback type for use with @ref ecore_con_lookup.
 322  */
 323 typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
 324                                  const char *ip,
 325                                  struct sockaddr *addr,
 326                                  int addrlen,
 327                                  void *data);
 328
 329 /**
 330  * @typedef Ecore_Con_Type
 331  * @enum _Ecore_Con_Type
 332  * Types for an ecore_con client/server object.  A correct way to set this type is
 333  * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
 334  * and LOAD_CERT if the previously loaded certificate should be used.
 335  * @code
 336  * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
 337  * @endcode
 338  */
 339 typedef enum _Ecore_Con_Type
 340 {
 341    /** Socket in ~/.ecore */
 342    ECORE_CON_LOCAL_USER = 0,
 343    /** Socket in /tmp */
 344    ECORE_CON_LOCAL_SYSTEM = 1,
 345    /** Abstract socket */
 346    ECORE_CON_LOCAL_ABSTRACT = 2,
 347    /** Remote server using TCP */
 348    ECORE_CON_REMOTE_TCP = 3,
 349    /** Remote multicast server */
 350    ECORE_CON_REMOTE_MCAST = 4,
 351    /** Remote server using UDP */
 352    ECORE_CON_REMOTE_UDP = 5,
 353    /** Remote broadcast using UDP */
 354    ECORE_CON_REMOTE_BROADCAST = 6,
 355    ECORE_CON_REMOTE_NODELAY = 7,
 356    /** Use SSL2: UNSUPPORTED. **/
 357    ECORE_CON_USE_SSL2 = (1 << 4),
 358    /** Use SSL3 */
 359    ECORE_CON_USE_SSL3 = (1 << 5),
 360    /** Use TLS */
 361    ECORE_CON_USE_TLS = (1 << 6),
 362    /** Use both TLS and SSL3 */
 363    ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
 364    /** Attempt to use the loaded certificate */
 365    ECORE_CON_LOAD_CERT = (1 << 7)
 366 } Ecore_Con_Type;
 367
 368 EAPI int               ecore_con_init(void);
 369 EAPI int               ecore_con_shutdown(void);
 370
 371 EAPI Eina_Bool         ecore_con_lookup(const char *name,
 372                                             Ecore_Con_Dns_Cb done_cb,
 373                                             const void *data);
 374
 375 /**
 376  * @}
 377  */
 378
 379 /**
 380  * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
 381  *
 382  * @{
 383  */
 384 EAPI int               ecore_con_ssl_available_get(void);
 385 EAPI Eina_Bool         ecore_con_ssl_server_cert_add(Ecore_Con_Server *svr, const char *cert);
 386 EAPI Eina_Bool         ecore_con_ssl_server_privkey_add(Ecore_Con_Server *svr, const char *key_file);
 387 EAPI Eina_Bool         ecore_con_ssl_server_crl_add(Ecore_Con_Server *svr, const char *crl_file);
 388 EAPI Eina_Bool         ecore_con_ssl_server_cafile_add(Ecore_Con_Server *svr, const char *ca_file);
 389 EAPI void              ecore_con_ssl_server_verify(Ecore_Con_Server *svr);
 390
 391 /**
 392  * @}
 393  */
 394
 395 /**
 396  * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
 397  *
 398  * @{
 399  */
 400
 401 EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
 402                                             const char *name, int port,
 403                                             const void *data);
 404
 405 EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
 406                                                 const char *name, int port,
 407                                                 const void *data);
 408 EAPI void *            ecore_con_server_del(Ecore_Con_Server *svr);
 409 EAPI void *            ecore_con_server_data_get(Ecore_Con_Server *svr);
 410 EAPI void *            ecore_con_server_data_set(Ecore_Con_Server *svr,
 411                                                  void *data);
 412 EAPI Eina_Bool         ecore_con_server_connected_get(Ecore_Con_Server *svr);
 413 EAPI Eina_List *       ecore_con_server_clients_get(Ecore_Con_Server *svr);
 414 EAPI const char *      ecore_con_server_name_get(Ecore_Con_Server *svr);
 415 EAPI int               ecore_con_server_port_get(Ecore_Con_Server *svr);
 416 EAPI double            ecore_con_server_uptime_get(Ecore_Con_Server *svr);
 417 EAPI int               ecore_con_server_send(Ecore_Con_Server *svr,
 418                                              const void *data,
 419                                              int size);
 420 EAPI void              ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
 421                                                          int client_limit,
 422                                                          char reject_excess_clients);
 423 EAPI const char *      ecore_con_server_ip_get(Ecore_Con_Server *svr);
 424 EAPI void              ecore_con_server_flush(Ecore_Con_Server *svr);
 425 EAPI void              ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout);
 426 EAPI double            ecore_con_server_timeout_get(Ecore_Con_Server *svr);
 427
 428 /**
 429  * @}
 430  */
 431
 432 /**
 433  * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
 434  *
 435  * @{
 436  */
 437
 438 EAPI int               ecore_con_client_send(Ecore_Con_Client *cl,
 439                                              const void *data,
 440                                              int size);
 441 EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
 442 EAPI void *            ecore_con_client_del(Ecore_Con_Client *cl);
 443 EAPI void              ecore_con_client_data_set(Ecore_Con_Client *cl,
 444                                                  const void *data);
 445 EAPI void *            ecore_con_client_data_get(Ecore_Con_Client *cl);
 446 EAPI const char *      ecore_con_client_ip_get(Ecore_Con_Client *cl);
 447 EAPI void              ecore_con_client_flush(Ecore_Con_Client *cl);
 448 EAPI double            ecore_con_client_uptime_get(Ecore_Con_Client *cl);
 449 EAPI double            ecore_con_client_timeout_get(Ecore_Con_Client *cl);
 450 EAPI void              ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout);
 451
 452 /**
 453  * @}
 454  */
 455
 456 /**
 457  * @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions
 458  *
 459  * @{
 460  */
 461
 462 /**
 463  * @typedef Ecore_Con_Url_Time
 464  * @enum _Ecore_Con_Url_Time
 465  * The type of condition to use when making an HTTP request dependent on time,
 466  * so that headers such as "If-Modified-Since" are used.
 467  */
 468 typedef enum _Ecore_Con_Url_Time
 469 {
 470    /**
 471     * Do not place time restrictions on the HTTP requests.
 472     */
 473    ECORE_CON_URL_TIME_NONE = 0,
 474    /**
 475     * Add the "If-Modified-Since" HTTP header, so that the request is performed
 476     * by the server only if the target has been modified since the time value
 477     * passed to it in the request.
 478     */
 479    ECORE_CON_URL_TIME_IFMODSINCE,
 480    /**
 481     * Add the "If-Unmodified-Since" HTTP header, so that the request is
 482     * performed by the server only if the target has NOT been modified since
 483     * the time value passed to it in the request.
 484     */
 485    ECORE_CON_URL_TIME_IFUNMODSINCE
 486 } Ecore_Con_Url_Time;
 487
 488 EAPI int               ecore_con_url_init(void);
 489 EAPI int               ecore_con_url_shutdown(void);
 490 EAPI Ecore_Con_Url *   ecore_con_url_new(const char *url);
 491 EAPI Ecore_Con_Url *   ecore_con_url_custom_new(const char *url,
 492                                                 const char *custom_request);
 493 EAPI void              ecore_con_url_free(Ecore_Con_Url *url_con);
 494 EAPI Eina_Bool         ecore_con_url_url_set(Ecore_Con_Url *url_con,
 495                                              const char *url);
 496 EAPI void              ecore_con_url_data_set(Ecore_Con_Url *url_con,
 497                                               void *data);
 498 EAPI void *            ecore_con_url_data_get(Ecore_Con_Url *url_con);
 499 EAPI void              ecore_con_url_additional_header_add(Ecore_Con_Url *url_con,
 500                                                            const char *key,
 501                                                            const char *value);
 502 EAPI void              ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con);
 503 EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con);
 504 EAPI void              ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
 505 EAPI int               ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
 506 EAPI Eina_Bool         ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
 507                                                   const char *username,
 508                                                   const char *password,
 509                                                   Eina_Bool safe);
 510 EAPI Eina_Bool         ecore_con_url_send(Ecore_Con_Url *url_con,
 511                                           const void *data, long length,
 512                                           const char *content_type);
 513 EAPI void              ecore_con_url_time(Ecore_Con_Url *url_con,
 514                                           Ecore_Con_Url_Time time_condition,
 515                                           double timestamp);
 516
 517 EAPI Eina_Bool         ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
 518                                                 const char *filename,
 519                                                 const char *user,
 520                                                 const char *pass,
 521                                                 const char *upload_dir);
 522 EAPI void              ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
 523                                                  Eina_Bool verbose);
 524 EAPI void              ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
 525                                                       Eina_Bool use_epsv);
 526
 527 /**
 528  * @}
 529  */
 530
 531 #ifdef __cplusplus
 532 }
 533 #endif
 534
 535 #endif